Access Tokens

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". Access Tokens have a few key characteristics. The most important of these is that they possess limited and bounded access. This means they have a very specific set of permissions which are good for a specific amount of time.

In our implementation, Access Tokens give 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 (optional)
  • for a particular institution
  • for a specific amount of time.

Definitions

Authorization Server
The server responsible for issuing access tokens to the client after successfully authenticating and authorizing the client. The Authorization server is sometimes also responsible for user authentication.
ClientId
The 80 character public portion of the WSKey.
Authenticating Institution ID
The institution that is responsible for authenticating the user and institution that the user's credentials are associated with.
Context Institution ID
The institution whose data the client is requesting access to
Scope
One or more web services that the client is requesting access to.

Obtaining an Access Token

Clients obtain Access Token from OCLC's Authorization Server using one of three OAuth2 flows:

Two of these flows: Explicit Authorization Code and User Agent, require users to authenticate in order to obtain an Access Token. With these two patterns, a client requests an Access Token and 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 as a url parameter on the redirect.

While both Explicit Authorization Code and User Agent 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.

The third flow: Client Credential Grant, does not require a user to authenticate. It assumes that either:

  • the client has authenticated the user already and is passing a valid user identifier as part of the request for an Access Token
  • the web service(s) for which the Access Token is being requested does not require user authentication

Refresh Tokens

OCLC also supports Refresh Tokens. By using a Refresh Token a client can obtain a new Access Token without having to login the user again. Clients can request a Refresh Token as part of the Explicit Authorization Code flow by specifying an additional scope of refresh_token. Note that multiple scopes are space separated.

Using a WSKey to Get Access Tokens for Different Institutions

A WSKey can be configured to allow a client to access to data associated with several institutions via Access Tokens. Using this single WSkey a cleint can request Access Tokens which allows it to access the data of several different libraries. The client can only request Access Tokens for libraries that are associated with its WSKey.

Example:

A client has a WSKey associated with three different libraries: Colgate, Keuka College and Ithaca College. The client can request an Access Token which access data on behalf of any one of these libraries by specifying the Context Institution ID. The client can also specify which institution to authenticate the user against by specifying the Authenticating Institution ID. These values are used in all of the flows for obtaining an Access Token.

Using an Access Token

All of these flows are built around the notion of authenticating to web services via an 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.

Currently, only a limited number of our web services support this model, but eventually the majority will support Authentication via Access Token.

Clients can make a request to access token enabled web services by submitting the token as aHTTP Authorization request header parameter. For example:

Authorization: Bearer tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW

Why use Access Tokens?

The Access Token model has several benefits:

  • 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.
  • 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.
  • 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.

We are a worldwide library cooperative, owned, governed and sustained by members since 1967. Our public purpose is a statement of commitment to each other—that we will work together to improve access to the information held in libraries around the globe, and find ways to reduce costs for libraries through collaboration. Learn more »