Authorization Code

How Does it Work?

Obtaining an Access Token using the Authorization Code Flow is a two step process. First, the client redirects an unauthenticated user to login via OCLC's 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.

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 OCLC's Authorization Server 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.

Clients can specify which user the should be authenticated at via the registryID. If no registryID is specified then the user is redirected to a Where Are You From (WAYF) screen to select an institution to authenticate at.

Base URL:  https://oauth.oclc.org/auth/{registryID}

Parameters

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

https://oauth.oclc.org/auth/128807?
client_id=jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa
&redirect_uri=http%3A%2F%2Flibrary.worldshare.edu%2Ftest.php
&response_type=code&scope=WMS_NCIP%20WMS_CIRCULATION
&state=account

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.

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

http://library.worldshare.edu/test.php?error=invalid_client_id&error_description=WSKey+is+invalid&http_code=401&state=%2Fmyaccount

Step 2: Getting an Access Token

The second step in the Authorization Code flow is to use the Authorization Code to request an Access Token.  

Base URL: https://oauth.oclc.org/token

Parameters

Requests will need to be signed using Basic Authentication

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 /token?grant_type=authorization_code&code=auth_Ztm8UjLSKpP5V0Gskgev3v2G21sfGx18vxtA
&redirect_uri=https%3A%2F%2Fwww.worldcat.org%2Ftest.php
HTTP/1.1
Host: https://oauth.oclc.org
Accept: application/json
Authorization: Basic RWQ0N1BNZFRXT01ENElPc2szbnFLUFlGS29Kb0dXYWtHVURUQnJsOHM5SVdZTnlnYWlsUXNZSThvZkd0M2RxM3JMbzBia0ZnUldSTjZvTUo6eG9XN0ZtQzZqS2N0THNPV3Y2Q3pPZz09
Content-Length: 0

Example Response

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

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 Authorization Code + PKCE to obtain access tokens.