Authentication and Authorization: Access Tokens

This is the fourth post in our topical series on Authentication and Authorization for OCLC web services. In the first post we introduced authentication for web services and our WSKey system. The second post discussed the HMAC Signature pattern of Authentication. The third post provided an overview of User Identifiers and discussed how the Authorization Server could be used to authenticate users and obtain user identifiers. Authenticating users is only one purposes of Authorization Server. The primary purpose of Authorization Server is to issue Access Tokens to clients.

What’s an Access Token?

Access Tokens are a significant part of the OAuth 2.0 specification. Our specific implementation uses what OAuth calls “Bearer Tokens”. Technically, the OAuth 2 specification supports other types of tokens. However, most implementations use Bearer Tokens rather than some other token type.

Access Tokens have a few key characteristics. The most important of these is that they possess limited and bounded access. This means they have very specific set of permissions which are good for a specific amount of time.

In the standard OAuth implementation, specific permissions are made up of two things: the “scopes” that the client application wants to access and the specific user on whose behalf the access is being requested. In the OAuth specification a scope is a set of permissions. Every OAuth implementation is responsible for defining its own scopes and publishing them for clients. Additionally, because OAuth is primarily being used by social networking applications, which are allowing users to delegate access to their information and rights to other applications, typically each Access Token is explicitly tied to a specific user.

OCLC’s implementation builds on these concepts but makes a few alterations. Currently, we have chosen to define our scopes as equivalent to web services. Our implementation varies slightly because not all our Access Tokens are tied to a specific user. We decided to support this model because not all of our web services require user authentication but we still wanted to be able to allow these services to use Access Tokens for authentication. However, because the vast majority of our services require user authentication, in many cases our Access Tokens are tied to a specific user.

Another area where we differ from the OAuth 2 specification is our use of “institution”. The notion of institution doesn’t exist in the OAuth 2 specification. However, because many of our web services provide access to data that “belongs” to a specific Institution, our Access Tokens are tied to a specific institution.When a client request an AccessToken it must specify what institution’s data it is requesting access for. This is the contextInstitutionId in the AccessToken request. Once a client gets an AccessToken, it can only use that AccessToken to get that institution’s data. So if a client requests an AccessToken for institution A and tries to use it to access data that belongs to institution B, the request will fail.

The result is that Access Tokens in our implementation gives an application the right to interact with

• a particular service or services
• on behalf of a particular user in order to read or write data
• for a particular institution
• for a specific amount of time.

Obtaining an Access Token

The OAuth 2 specification doesn’t prescribe a specific methodology for obtaining Access Tokens. Instead it offers a series of “flows” for obtaining Access Tokens. This is in order to:

• Support a diverse set of clients
• Ensure the highest level of security for each type of client
• Enable clients to obtain user identifiers for use with our web services

Currently we support three OAuth2 flows for obtaining an Access Token: Client Credentials Grant, Explicit Auth Code and User Agent. We will be discussing each of these flows in greater detail in future posts. In all these flows the client must specify several pieces of information as part of the request

• WSKey
• Authenticating Institution ID – the institution that is responsible for authenticating the user
• Context Institution ID – the institution’s whose data the client is requesting access to
• Scope – the services that the client is requesting access to

The client credential grant flow is used by server-side web applications. This flow assumes the client has successfully authenticated a user and if the web service requires it, obtained a valid user identifier to pass as part of the request for an Access Token.

The other two flows: Explicit Authorization Code and User Agent, require users to authenticate in order to obtain an Access Token. With these two patterns, the basic concept is that when a client requests an Access Token, the user’s web browser is redirected to the Authorization Server and asked to login. If the login is successful, then the user’s web browser is redirected back to the original client with an Access Token passed along on the redirect.

While both of these flows require the user to login, they differ slightly in how the client obtains the token. Server-side web applications should use the Explicit Authorization Code flow. This flow requires the client to redirect the user to the Authorization Server in order to login. A successful login results in an authorization code being returned to the client. The client then uses this code, their WSKey and secret to request an Access Token.

Client-side web applications such as JavaScript and native mobile applications, which are capable of opening a web browser, should use the User Agent/Mobile flow. Because these applications are not able to keep a secret secure, this flow does not require the client use a secret to make the request for an Access Token. Instead the client redirects the user to the Authorization Server to login. Upon successful login, an Access Token is returned to the client.

Using an Access Token

All of these flows are built around the notion of authenticating to web services via Access Token. In this model authenticating to the web service is a two-step process. Step one: obtain an Access Token. Step two: send the Access Token as part of the web service as part of the HTTP Authorization Header. This model has several benefits. First, it is more efficient for clients to use than the HMAC signature pattern which requires the client to build a unique signature for every request. Only one signature has to be built to obtain the Access Token, which reduces the cryptography overhead. Second, it allows clients to have a single WSkey that can request Access Tokens for different institutions, which eliminates the client’s need to manage multiple WSKeys. Third, once a client obtains an Access Token, this is the only piece of information that will need to be passed to the web service in order to authenticate both the application and user. This removes the need for the client to store user identifiers after an AccessToken has been obtained. Currently, only a limited number of our web services support this model. However, eventually the majority of our services will support Authentication via Access Token.