OAuth

From Freebase

Jump to: navigation, search

Freebase implements the OAuth authentication protocol. This is an overview of how to use the Freebase OAuth support.

Quick ref

If you're already comfortable with OAuth, here are the key parameters you'll need in order to start using it:

Registering a consumer is documented here: api/oauth/enable

  • Request token URL: GET https://api.freebase.com/api/oauth/request_token (Documentation)
  • Authorize token URL: https://www.freebase.com/signin/authorize_token (Documentation)
  • Access token URL: GET https://api.freebase.com/api/oauth/access_token (Documentation)

Resource URLs that support OAuth access tokens:

  • api/service/mqlwrite
  • api/service/upload
  • api/service/user_info

Signatures:

  • We support HMAC-SHA1 at present.
  • RSA-SHA1 should work if you supply the X.509 public key as secret in oauth/enable.

OAuth Basics

OAuth negotiates between three parties:

  • A "provider" (Freebase, in this case) provides some service.
  • A "user" is a person who already has an account on the provider.
  • A "consumer" (your application) wants to do some operation on the provider for the user.

For example, if you want to create a convenient front-end for people to edit movie reviews on Freebase, OAuth would allow your application to perform MQL writes with all operations credited to the user.

If you're getting started with OAuth, the Beginner's Guide is a good place to start. Of course, the OAuth Core 1.0 spec is essential reading, especially the "Authentication Flow" diagram.

Why OAuth?

Some people have tried to have applications write to Freebase by creating a "robot user" that the application uses for writing. Unfortunately, the "robot user" approach has a couple of drawbacks:

  • The write is attributed to the robot, not to the real user.
  • Freebase daily write limits get applied to all writes from the robot account.

This second issue is particularly limiting if you're creating a public service that you expect to be used by many people.

In contrast, if you use OAuth:

  • The write is attributed to the real user (with an additional note referencing your application)
  • Freebase daily write limits get applied to each user individually.

Using OAuth

We assume you're already comfortable with the Freebase API in general and the MQL write service in particular. We also assume you've read the OAuth documentation on http://oauth.net/. The rest of this section explains how to use OAuth to perform MQL write operations to Freebase.

Register your application with Freebase

You'll first need to register your OAuth-enabled application with Freebase. This essentially creates a special "consumer" account that is used by your application. To create a consumer account, you need to:

Here's a recipe for grabbing your key and secret that uses the old "metaweb.py" python client found at freebase-0.5.tar.gz: 

import metaweb,urllib2,urllib
cred=metaweb.login('MYUSERNAME','MY_PASSWORD')
postdata=urllib.urlencode({'id':'MY_FREEBASE_APP_ID'})
req=urllib2.Request('https://api.freebase.com/api/oauth/enable',
                    postdata,{'Content-type':'application/x-www-form-urlencoded',
                              'X-Metaweb-Request':'True',
                              'Cookie':cred})
try:
    resp = urllib2.urlopen(req)
    print resp.read()
except urllib2.HTTPError, e:
    print e.code
    print e.read()

Write using OAuth

You can now use OAuth to perform MQL writes to Freebase by following the standard OAuth process:

  1. Get a request token (section 6.1.1): Make an HTTPS request to (https://api.freebase.com/api/oauth/request_token) with your Consumer Key and Consumer Secret. Freebase will return an "OAuth request token" and an "Oauth request secret."
  2. Direct the User to the Service Provider (section 6.2.1): Return an HTTP 302 Redirect to your user so they can log into Freebase
  3. When the user has completed logging in, they will be redirected back to the callback URL you provided.
  4. Obtain an access token (section 6.3): You make another request directly from your application to Freebase

The access token can now be used to access the Freebase mqlwrite service. When you access the mqlwrite service in this fashion, the write is attributed to the user with a separate annotation referring to your application. Using MQL, you can query Freebase.com to find out what writes were performed by your application.

Storing and Reusing OAuth Tokens

The OAuth access token can be reused for subsequent operations, so you should store it somewhere. Because it is useless without your consumer secret to sign the requests, you can safely store the access token and access secret in a browser cookie or other "insecure" storage. Of course, if you have your own login system where you can store user information, you might also store Freebase OAuth access tokens and secrets there for reuse.

For some applications, it makes sense to perform an OAuth authentication to Freebase even before the user tries to write. For example, some applications will want to go through this process as part of the regular sign-up process. This can make the user experience flow a little more smoothly.

However, please note that even if you already have an OAuth access token, there are unusual scenarios where you may need to repeat the authorization process:

  • By default, we do not accept access tokens that are more than 1 week old. If you have a particular need for a shorter or longer expiration, please let us know and we'll try to accomodate you.
  • Users are allowed to manually revoke their approval for particular applications. This forcibly expires the OAuth tokens already issued for that application.
  • If we suspect that OAuth tokens have been compromised, we reserve the right to expire them at any time.
  • Our OAuth support is currently in alpha test. Although we will try to avoid it, it may be necessary for us to revoke all issued tokens as part of software upgrades.

In any of these cases, we will return a 401 Authorization Required response even though you already have a Freebase OAuth access token. If you receive such a response, you should discard the existing token and repeat the OAuth authentication process.

However, repeating the OAuth authorization isn't as bad as it may sound. When the user authorizes your application, we also log them into Freebase. If they are already logged into Freebase, we'll skip that step and they'll only have to approve your app.

Summary of Optional Specification Elements

This is a summary of the behavior of Freebase's OAuth implementation in areas where the OAuth 1.0 specification lists behavior as optional or where Freebase's OAuth implementation provides additional features or requirements:

  • Section 4.3: The consumer secret is generated by Freebase.com when the developer registers their application with api/oauth/enable. When a developer registers their application, they MUST FIRST create a Freebase topic describing their application. They SHOULD provide detailed information in that topic, including name, description, URL, and contact information.
  • Section 5.2: Freebase.com accepts OAuth arguments in the Authorization headers ("SHOULD" per spec) , NOT in POST body (possibly later), or as query arguments to a GET request.
  • Section 5.4.2: do we generate WWW-Authenticate headers? - We do NOT
  • Section 6: Access Tokens: Freebase.com access tokens have a limited lifetime. The default lifetime is one week. Access tokens grant access only to data-manipulations APIs, including /api/service/mqlwrite and /api/trans/upload. Access tokens cannot be used to access account-management APIs. Access tokens can be revoked by the user through their account management page on freebase.com.
  • Section 6.2.2: When prompting the user for approval, Freebase.com displays information from the Freebase topic for the consumer application, including application name, description, site URL, XXXXXX. If the user declines approval, Freebase.com will redirect the user to the URL specified by the ondecline parameter. Lacking ondecline parameter a generic confirmation page with the same consumer info will be presented to the user, ditto oauth_callback
  • Section 7: How to access Freebase APIs using OAuth - parameters specified in http://oauth.net/core/1.0/#anchor13 can be supplied in the Authorization header - per spec, for "GET" requests they MAY be added to the query parameters instead
  • Section 9.1.1: Contents of files being posted to upload services are not included in the computed signature.

Additional Questions

  • REQUEST_TOKEN - Are there any security restrictions? Are requests for a particular REQUEST_TOKEN tied to a particular originating domain? No.
  • ACCESS_TOKEN - Are there any security restrictions? Are requests for a particular REQUEST_TOKEN tied to a particular originating domain? No.
  • 5.4.2 Does FB implementation respect RFC 2617 REALM parameter? Yes. However note that OAuth merely uses the WWW-Authenticate header for communication between the client and server, it does not do HTTP Authentication.
  • Will 401 responses now have WWW-Authenticate header per RFC2617 sec 1.2? Partially. Since we don't do HTTP authentication providing the scheme and challenge details do not help the clients. The only param provided is the realm parameter.
  • Section 5.2
    • Is Authorization header supported? Yes BUT not per RFC2616 Sec. 14. It is used by the library we use to transfer OAuth headers.
    • Are POSTS w content-type application/x-www-urlencoded? Yes.
    • in URLs as part of a query? Yes. I am assuming you are talking about OAuth parameters.
  • Section 5.4
    • Is OAuth HTTP Authorization Scheme Implemented? Yes.
  • Section 6
    • What is the mechanism for allowing the USER to revoke ACCESS_TOKEN authority? None. At this time OAuth consumer apps have to authorize once per week per restricted operation. The access token expires in one month. The plan is to implement a UI for this but none exists yet.

Example Implementation In Python

Here's a python script that takes you through the whole process. This script assumes you're using the OAuth python library at [1].

Retrieved from "http://wiki.freebase.com/wiki/OAuth"
Personal tools