Explicit Authorization Code

How Does it Work?

Obtaining an Access Token using the Explicit Authorization Code Flow is a two step process. First, the client redirects an unauthenticated user to login via the Authorization Server. Once the user successfully logs in, they are redirected back to a url specified by the client. The client is responsible for retrieving an authorization code appended in the query string. Second, once the authorization code has been retrieved, the client redeems this authorization code for an access token. The access token is valid for a specific period of time, usually 20 minutes. During this time the client can use the access token to make requests to one or more web services.

Exlicit Authorization Flow

Note: This diagram simplifies the interaction to the client application perspective and removes the details of the OCLC Authorization Server side.

Step 1: Getting an Authorization Code

An Authorization Code is a unique string which represents the fact a user has successfully authenticated and the application has been granted the right to access a web service for a particular institution.  Authorization Codes are exchanged by clients to obtain Access Tokens, which are used to make specific OCLC API requests.

To request an Authorization Code, the client must build a url to WSKey's authorization code endpoint. The client will redirect the user to this url so the user can login. 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 (in this example, http://library.worldshare.edu/test.php) with the Authorization Code appended as a query parameter so the client can easily extract it.

Base URL: https://authn.sd00.worldcat.org/oauth2/authorizeCode

Parameters

Name Description Required? Expected / Sample Values
client_id The WSKey being used by the client
Yes  
authenticatingInstitutionId The WorldCat Registry ID for the institution responsible for authenticating a user when principal information is included on the request. Yes 128807
redirect_uri The url WSKey should redirect the user to on success or failure Yes http://library.worldshare.edu/test.php
contextInstitutionId The WorldCat Registry ID for the institution whose data the client is requesting to access or modify.
Yes 128807
response_type The type of response the server should return.   Yes code
scope A space separated list of the services for which the client is request access.
Yes
  • WorldCatMetadataAPI
  • WMS_ACQ%20WMS_VIC

Example URL - Your Application Redirects User To Login via the Authorization Server

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=WMS_NCIP%20WMS_CIRC

Example - Authorization Server Redirects User to Your Application's Redirect Uri

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

Notice the redirect uri has a authorization code appended to it in the form of a "code" parameter in the query string. This is the information you need to get an Access Token in Step 2.

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.  

Base URL: https://authn.sd00.worldcat.org/oauth2/accessToken

Parameters

grant_type The type of grant being used to obtain the access token.
Yes code
code The authorization code retrieved Yes auth_Ztm8UjLSKpP5V0Gskgev3v2G21sfGx18vxtA
authenticatingInstitutionId The WorldCat Registry ID for the institution responsible for authenticating a user when principal information is included on the request. Yes 128807
contextInstitutionId The WorldCat Registry ID for the institution whose data the client is requesting to access or modify.
Yes 128807
redirect_uri The url WSKey should redirect the user to on success or failure Yes http://library.worldshare.edu/test.php

Requests will need to be signed using the HMAC Signature documentation

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.

Example Request

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

Example Response

{
  "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"
}

A successful response for an Access Token will return a JSON document with the following fields:

Name Description
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 WorldCat Registry institution ID of the institution's data the Access Token has rights to access
expires_at Timestamp when the Access Token will expire.

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. Client side and mobile applications use the UserAgent/Mobile pattern to obtain access tokens.

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 »