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.
- 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.
- The 80 character public portion of the WSKey.
- Authenticating Institution ID
The WorldCat Registry ID of the institution that is responsible for authenticating the user and institution that the user's credentials are associated with.
- Context Institution ID
- The WorldCat Registry ID of the institution whose data the client is requesting access to.
- 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.
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
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 client 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.
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 a HTTP 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.