Authentication and Authorization: Explicit Authorization Code Flow

This is the fifth post in our topical series on Authentication and Authorization for OCLC web services. In our previous post, we discussed Access Tokens and the purpose they serve in OCLC’s web service infrastructure. We enumerated several flows which can be used to obtain an Access Token. This post will focus specifically on one of those flows: the Explicit Authorization Code flow.

In many other OAuth implementations you will see Explicit Authorization Code flow labeled as the Web App pattern. This is because this flow was designed to be used by server-side web applications.

Getting an Access Token using the Explicit Authorization Code Flow is a two step process in which a user logs into your application through an authentication system mediated by OCLC. Your application should detect the absence of an access token in a session associated with a given user trying to access your website. It then redirects the user’s web browser to the OCLC WSKey server, which will in turn send your user through a username/password login process on either OCLC’s servers or at your institution. Once the user login process is successful, the user is redirected back to your website, which will be responsible for accepting, or catching, an authorization code that can be redeemed for an access token. The access token is then used for a period of time, usually 20 minutes, to make subsequent requests to one or more web services.

Note: This diagram simplifies the interaction to the client application perspective and removes the details what happens at the OCLC Authorization Server. More on our "Cooperative Authorization server" in a future post.

Step 1: Getting an Authorization Code

The first step in the Explicit Authorization Code flow is to request an Authorization Code.  An Authorization Code is a unique string which represents the fact a user has successfully authenticated and granted an application the right to access a web service and data for a particular institution.  Authorization Codes are exchanged by clients in order to obtain Access Tokens.

To request an Authorization Code the client must build a url to the Authorization Server’s authorization code endpoint that contains the following parameters:

  • client_id - WSKey
  • authenticatingInstitutionId – the institution that is responsible for authenticating the user
  • contextInstitutionId – the institution’s whose data the client is requesting access to
  • scope – the services that the client is requesting access to
  • redirect_uri – the url the authorization server should redirect the user to after login

Then client must redirect the user to this url.

Example:

https://authn.sd00.worldcat.org/oauth2/authorizeCode?
client_id=jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa
&authenticatingInstitutionId=128807&contextInstitutionId=128807
&redirect_uri=http%3A%2F%2Flibrary.worldshare.edu%2Ftest.php&response_type=code&scope=platformConfig

Once the user is redirected they are presented with a login screen which they must give a valid username and password combination. If the user successfully logs in, the server will present them with a “grant” screen which asked them to allow or deny the application’s request to access different web services. Once the user allows the application to access the web services, the server redirects back to the specified redirect URL and append the Authorization Code as a query parameter.

Example:

http://library.worldshare.edu/test.php?code=auth_Ztm8UjLSKpP5V0Gskgev3v2G21sfGx18vxtA

Step 2: Getting an Access Token

The second step in the Explicit Authorization Code flow is to use the Authorization Code to request an Access Token. An Access Token is a unique string which the client will send to the web service in order to authenticate itself. Each Access Token represents a particular application’s right to access set of web services, on behalf of a given user in order to read or write data associated with a specific institution during a specific time period. For more detailed information on Access Token consult the Developer Network documentation.

To request an Access Token the client must send the following:

  • authenticatingInstitutionId – the institution that is responsible for authenticating the user
  • contextInstitutionId – the institution’s whose data the client is requesting access to
  • scope – the services that the client is requesting access to
  • redirect_uri – the url the authorization server should redirect the user to after login

The request must also be signed using an HMAC Signature generated using the client’s WSKey and secret. The request is signed as an added layer of security to ensure that the client (e.g., your web application) that requested the authorization code is the same one redeeming the code for a token.

Example:

POST /oauth2/accessToken?grant_type=authorization_code&code=auth_Ztm8UjLSKpP5V0Gskgev3v2G21sfGx18vxtA&authenticatingInstitutionId=128807&contextInstitutionId=128807&redirect_uri=http%3A%2F%2Fwww.worldcat.org%2Ftest.php HTTP/1.1
Host: https://authn.sd00.worldcat.org
Accept: application/json
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa ",
timestamp="1361911277", nonce="5368c00b", signature="CG+ENonHuWQ657pKGfpkFHb0MZgz7SWlL+A4902O5bA="
Content-Length: 0

If the request for an Access Token is successful then the Authorization Server will return a JSON response that contains a variety of information about the AccessToken to the client. This includes:

 

  • Token type – Type of token. In our implementation this will always be “bearer”
  • Access token – the value of the Access Token. This is what the client will need to send to the web service
  • Expires in – number of seconds in which the Access Token will expire
  • principalID - the user id of the user who logged in
  • principalIDNS – principal identity namespace the user’s principalID is in
  • contextInstitutionId – the registry ID of the institution’s data the Access Token has rights to access
  • expires_at – date timestamp when the Access Token will expire

 

Example:

{
"access_token":"tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW",
"token_type":"bearer",
"expires_in":"3599",
"principalID":"cpe4c7f6-f5a4-41fa-35c9-9d59443f544p",
"principalIDNS":"urn:oclc:platform:128807"
“contextInstitutionId”: “128807”,
“expires_at”: “2013-08-23 18:45:29Z”
}

Why would I use this flow?

This flow is designed to be used by client applications which are capable of keeping a WSKey “secret” secure and in which the user’s identity has not been verified. This is typically characterized by a server-side web application which needs to authenticate a user and obtain a valid user identifier for them before interacting with an OCLC web service. So for example let’s say I wanted to extend my electronic thesis and dissertation system so that a cataloger could review a given ETD, add subject headings then decide that ETD’s metadata was ready to be published WorldCat. As the application developer, I would use this pattern to allow the cataloger to login using her WorldShare Metadata Record Manager credentials. Once she was successfully logged in, the application would use her identity to make the request to the WorldCat Metadata web service in order add the record for the ETD to WorldCat.

This flow is not suitable for applications which incapable of keeping a WSKey “secret” secure, such as an application written in client-side Javascript. An application like this would have to expose the WSKey’s secret to the end user’s web browser, in effect compromising the integrity of the API key. This flow is also not suitable for mobile applications. In our next post we will discuss the User Agent or Mobile Flow which allows these types of applications to authenticate users.
 

For more information, please take a look at our updated Authentication and Authorization documentation.

  • Karen Coombs

    Karen Coombs

    Senior Product Analyst