Gentle introduction to OAuth

By Cosimo Streppone

Introduction

OAuth is a specification defining an authentication protocol that allows applications to access users' data in a secure way. This article discusses why OAuth was invented, shows how it works and what it means for users and developers, and then goes through the specifics of Opera's OAuth implementation.

Why was OAuth invented?

OAuth was invented because a lot of emerging services and APIs were starting to use Google accounts, Twitter, Facebook, etc., so the users of these third-party applications were forced to share their own Google, Twitter or Facebook passwords. This resulted in third-party services having access to users' private passwords, which is not very desirable. We did that too when My Opera integrated Twitter and then Facebook status updates into the activity feed.

When Twitter recently ceased support for Basic Auth APIs, and migrated their systems to OAuth, our code was already using the new OAuth-based authentication. The main advantage for users is they are fully in control of what applications can or cannot do, and they don't have to share their passwords with third party applications.

OAuth for end users

As an end user, you only need to pay attention to the token authorization step, where you grant the application or website you want to use permission to access your personal data. Of course you can deny the permission, but the application won't be able to proceed if you do.

An example: Opera Portal

If you go to Opera Portal, you are presented with the web page shown in Figure 1:

Figure 1: Opera Portal.

Click on Authorize Opera Portal to set your status on My Opera (or the equivalent in your language). You will see an authorization page similar to Figure 2:

Figure 2: The Opera Portal authorization page.

On this page you can see important information that tells you what application you're going to authorize. In general, if the action that led you on this page took place on the same URL as advertised - in this case, http://portal.opera.com - then it's safe to proceed. If you want to deny the request, just click on the Deny access button. If you want to allow the application access on your behalf, then provide your Opera account credentials and then click on the Grant access button. This will only happen the first time you authorize an application or web site.

After granting access, you will either:

• Be redirected automatically to the originating web site: this is the case for web applications, like portal.opera.com.
• Be notified of a 6-digit code (eg 667227), called the verifier. This is the case for applications that run on a mobile phone, or from the command line, or in general when the application doesn't run in a browser, so it cannot follow user agent redirects.

Figure 3 shows an example of verifier screen.

Figure 3: A verifier screen.

The originating application will ask you to type in the verifier code (or input it in some other way). Without that code, you won't be able to continue.

That completes the OAuth initial flow, so from now on, the application will be able to access your data on your behalf until the grant expires. Some OAuth providers, like Twitter for example, never expire access tokens, so apps can go on using them forever or until you revoke them manually. In our case, we chose to expire the access tokens after 2 weeks in our first period just after the Link API release. We'll probably switch to never-expiring access tokens at a later date.

Managing grants

You can manage your existing grants at the following URL: https://auth.opera.com/service/oauth/grants/. Figure 4 shows an example of what you will see there:

Figure 4: An example of an Opera grant management page.

Within this page, you will be able to revoke tokens by application, or revoke all tokens issued for any application at the same time. The latter option will make sure no application can access your data anymore, should you ever need that.

How does OAuth work?

There's plenty of material available already to help you understand how OAuth works under the cover, for example the hueniverse OAuth 1.0 guide. In this article, we will take a more practical approach, focusing on simple examples to get you up and running quickly.

The OAuth "flow"

On My Opera you can set your status manually, or let My Opera automatically update by reading your Twitter and/or Facebook status. In general, you will want to keep your Twitter or Facebook password private. How can My Opera update your Twitter status without knowing your password?

Use the tokens, Luke

My Opera manages to update your status from Facebook or Twitter without knowing your password by replacing the need for a password with an access token. In Figure 5 you can see an overview of the OAuth initial flow:

Figure 5: The OAuth initial flow.

The steps to obtain the access token are:

1. My Opera sends a request to Twitter to get a request token
2. If the request is valid and signed correctly, Twitter returns a request token to My Opera.
3. MYO redirects the user to an authorization URL that contains the request token. This will look something like http://twitter.com/oauth/authorize?oauth_token=Xyc3TkOaVCTHUk44EYKw97yNTmmnuJjT.
4. The user has to then decide whether to grant My Opera access to his or her Twitter status data. This is the key part of the OAuth flow. If the user denies access, then the flow stops here.
5. If the user grants access, the request token is authorized.
6. My Opera issues a new request to Twitter, asking for an access token in exchange for the authorized request token.
7. Twitter checks the new request, and if it's correct, issues the access token, which may or may not have an expiry date, depending on which service issues it. For example, all Opera OAuth tokens currently expire after two weeks.
8. My Opera receives the access token and access token secret, so now My Opera can update the user's Twitter status by supplying the access token. At this point, the access token effectively acts as the password.

Once the access token has been supplied, subsequent requests are then made using the super simplified OAuth flow show in Figure 6:

Figure 6: Super simplified OAuth flow.

The flow is much simpler now:

• My Opera loads the current access token and access token secrets associated with the current user from a database.
• My Opera uses the access token and access token secrets to build a status update API request to Twitter.

Done! This is what you will need to do every time you want to update the status (or anything else your access token will allow you to).

Token secrets

So isn't the access token exactly like a password? Well, no — the access token alone doesn't give you access. You also need an access token secret, which is a string that you never send over the network. You use the secret to generate a signature of the OAuth request. Every OAuth request is timestamped and signed. It also contains a nonce string. The nonce is a one time string that you can generate randomly, but it has to be unique. Two different OAuth requests cannot have the same nonce.

Here's an example of an actual OAuth request to update a status on My Opera:

http://my.opera.com/community/api/users/status.pl?
    new_status=My%20new%20status%21%20Yeah%21&
    oauth_consumer_key=test_desktop_key&
    oauth_token=ATqkhy6nAijQ5yGInrhzCvWkXekZOYW2&
    oauth_signature_method=HMAC-SHA1&
    oauth_nonce=EVbeH7cE5KvVG8Lh8uKYf22hnW94cJ3c&
    oauth_timestamp=1288018976&
    oauth_version=1.0&
    oauth_signature=eM495mxdUxewMa9GJ1MPEyugSsI%3D

Any OAuth request like this is built in 3 steps:

1. You start with the API endpoint URL, plus any API own parameters you might have. In our case, the new_status parameter is the only one that belongs to the My Opera API. So you get: http://my.opera.com/community/api/users/status.pl?new_status=My%20new%20status%21%20Yeah%21. Every parameter has to be URL encoded, of course.

2. You add the required OAuth arguments. The exact list of arguments that you need to include depends on the step in the OAuth workflow that you're currently on. In this example, we already have an access token, and we need to access a protected resource, so we need to supply:

   • oauth_consumer_key: Mandatory, given to you by the OAuth provider
   • oauth_token: This is the key, the access token. Note that the access token secret is not included in the request
   • oauth_signature_method: Mandatory. Opera's OAuth provider only supports HMAC-SHA1
   • oauth_nonce: Mandatory. A random, unique, string
   • oauth_timestamp: Mandatory. The current timestamp, in Unix epoch format (seconds since 1/1/1970)
   • oauth_version: Optional. Must be 1.0. Opera's OAuth provider only supports OAuth 1.0A, but the version string must be 1.0 in any case.

3. You need to assemble the signature base string, which is a normalized version of the request method, URL and parameters, and you need to sign this base string with a signing key, which in our example is composed of the access token plus the access token string (ATqkhy6nAijQ5yGInrhzCvWkXekZOYW2&{some-random-access-token}). The obtained signature must be included in the original request as oauth_signature parameter. The algorithm to calculate the signature is HMAC-SHA1. The most used languages already have working libraries to produce HMAC signatures.

Don't worry if this seems complicated. It is, but all these operations will be carried out for you by your OAuth library of choice. Just be sure your library supports the revised OAuth 1.0A protocol version, which addresses a potential security problem known as OAuth session fixation. In our OAuth provider implementation, we chose to only support OAuth 1.0A, for security reasons.

OAuth security

These basic properties of OAuth requests (signature + nonce + timestamp) protect you from:

• Fake requests: Someone wanting to update your status would need your API keys (consumer key + secret), your access token, and your access token secret. Unless you communicate them openly, the secret strings are not sent over the network.
• Replay attacks: If an attacker logs all the OAuth traffic and tries to replay any request, he will only waste time, since the same signature + nonce + timestamp will never be valid again.

More details

If you want to know even more details about OAuth, you can refer to the current (1.0) specification, available as RFC5849 on http://tools.ietf.org/html/rfc5849.

OAuth based APIs

Examples of existing OAuth-based APIs and services are:

• Twitter
• Facebook
• Google Contacts
• YouTube
• etc...

Opera recently released the Opera Link API and My Opera API. The following is an example using the My Opera status API. This example will allow you to get or update your My Opera status using a command line application.

OAuth for developers

Now we will look at some more of the functionality that the OAuth provider offers, which will be of particular interest to developers. As with other OAuth APIs, you will need to register your application and get your API keys. In the case of Opera's OAuth provider, you can register new applications at the following URL, which takes you the screen shown in Figure 7:

https://auth.opera.com/service/oauth/applications/

Figure 7: Registering new applications on Opera's OAuth provider.

You will need to sign in first. If you don't have a Opera account yet, you can quickly sign up for one at the My Opera signup page. Once signed in, you can view your existing applications, and register a new one. Figure 8 shows an example:

Figure 8: An example of registering a new application with OAuth.

Choosing an application type

Applications can be of two types:

• Web applications
• Desktop/mobile applications

Web applications

Web applications are the ones that can accept web callbacks, typically web sites, or applications that run inside a browser and can redirect users to different URLs automatically. This redirection mechanism is used to signal to the originating application that the user has completed the authorization step (see the previous example about Opera Portal). Therefore every web application must define a callback_url. The OAuth provider will ask the user to authorize the application request, and then it will redirect the user back at the application-specified callback URL. An example of callback URL is:

https://superduper.example.com/callback/myopera/?oauth_token={token-string-here}&oauth_verifier={verifier_code}

Figure 9 shows an example of web application filled in and ready to be submitted:

Figure 9: A web application filled in and ready to be submitted.

Desktop/mobile applications

Desktop/mobile applications, by contrast, are the ones that cannot accept web callbacks, because they don't run in a browser, or more generically, they have no way to accept incoming callbacks. This is the case of command line applications, desktop applications or applications running on mobile phones.

Your API keys

When you have successfully registered your application, you will be assigned a set of API keys, called the consumer key and consumer secret, as shown in Figure 10:

Figure 10: Receiving your consumer key and consumer secret.

By requesting your application keys, you agree to the Opera OAuth terms of service.

OAuth libraries for any language will require you to fill in those consumer keys. The consumer secret will be used to sign every OAuth request, and must not be sent over the network at any time.

In the Resources section, you will find pointers to OAuth libraries for the most used programming languages.

You can also edit the settings of your application at any time, or even delete it, if you don't want to use it anymore. Deleting an application will immediately invalidate all the issued tokens that are linked to it, for any user.

Get your My Opera status

The My Opera status API is just one of the OAuth-enabled APIs provided by Opera. You can get the status of any user on My Opera using the following command:

http://my.opera.com/community/api/users/status.pl?username=cstrep

What you get back is a JSON response that you can parse with your favorite JSON library:

{
"status" : "test test test",
"last_modified" : "2010-10-12 13:32:11",
"code" : 200
}

Updating your My Opera status through the API

This is where the OAuth part gets really practical. The My Opera status update API needs an OAuth access token to do its job. To try this out, as detailed before, you will either need to register an application (usually recommended), or use the test application that we prepared for this article.

Let's use the test application for now, but feel free to create your own application. The test application consumer keys are:

Consumer key: test_desktop_key
Consumer secret: p2FlOFGr3XFm5gOwEKKDcg3CvA4pp0BC

Update your status!

To update your status, you need to either work out the details of how to build a OAuth request - and there's already good tutorials on the topic - or go and download an existing OAuth library for the programming language of your choice.

An example using Perl is available in the Net::MyOpera Perl module source code. To install it and use it:

• Download the tarball with the source code from http://github.com/operasoftware/perl5-net-myopera/tarball/master
• Unpack it with tar xzvf Net-MyOpera.tar.gz
• Enter the main directory, and install it with: perl Makefile.PL && make install
• Access the examples folder

Next run the myopera-status example script:

$ ./myopera-status 'I can haz status update!'

This will ask the OAuth provider for a request token. If everything works, you will see the following:

Please authorize me at https://auth.opera.com/service/oauth/authorize?oauth_token=RTzxcLG9zk4utuztK6rY8avDw9UzKTpY and then
type the verifier + ENTER to continue

Of course, the token string (here RTzxcLG9...) will be different in your case. Follow the link, authorize the token, note the verifier code, then go back to the script and type the verifier code. Press enter. This will update your My Opera status.

The tokens information is stored in a .myoperarc file in your home directory. So, from now on, the script will update your status without asking you to authorize it again.

More resources

You can check out an introductory article about the Opera Link API.

Complete code samples are also available at Opera's github page (http://github.com/operasoftware/):

• pyoperalink is a Python library that allows you to access the Opera Link API, which is also based on OAuth.
• Net::MyOpera is a Perl class that will allow you to update your My Opera status with OAuth, as explained in this article. There's a ready-made Perl5 example that will just work out of the box.
• Net::OperaLink is a Perl interface to the Opera Link API. It's still a work in progress, but it already allows you to get access to your bookmarks and speeddials.

Here's more resources you can check out if you want to read more about OAuth details:

• Hueniverse Tutorials
• OAuth own wiki
• Twitter's OAuth FAQ
• Twitter list of OAuth libraries for most languages

This article is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported license.