Explicit Authorization Code + PKCE

How Does it Work?

Obtaining an Access Token using the Explicit Authorization Code + PKCE 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.

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

Name Description Required? Expected / Sample Values
client_id The WSKey being used by the client Yes  
redirect_uri The url WSKey should redirect the user to on success or failure Yes http://library.worldshare.edu/test.php
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.

To obtain a Refresh token client should specify refresh_token as a value in the scope list

Yes
  • WorldCatMetadataAPI
  • WMS_ACQ%20WMS_VIC
  • WorldCatMetadataAPI%20refresh_token
state An opaque value to represent the application's state when the user chose to login. The parameter can be used to prevent
cross-site request forgery
No  
code_challenge Generated challege from the code verifier Yes  
code_challenge_method Method used to generate the challenge Yes
  • plain
  • S256

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

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

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 Explicit Authorization Code +PKCE flow is to use the Authorization Code to request an Access Token.  

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

Parameters

grant_type The type of grant being used to obtain the access token. Yes code
code The authorization code retrieved Yes auth_Ztm8UjLSKpP5V0Gskgev3v2G21sfGx18vxtA
redirect_uri The url WSKey should redirect the user to on success or failure Yes http://library.worldshare.edu/test.php
code_verifier base64 encoded random 32 byte string using the
unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
Yes HKFMnkdkjZjkJ5JyXYPyWXVnfuzuga7PKCcWy2SuS2D

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

Example Response

{
  "access_token":"tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW",
  "token_type":"bearer",
  "expires_in":"3599",
  "principalID":"",
  "principalIDNS":"",
  "scopes": "WMS_NCIP WMS_CIRCULATION",
  "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
scopes List of scopes the token is issued for
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 not capable of keeping a WSKey "secret" secure and in which the user's identity has not been verified. Examples of this include: mobile application and single page javascript applications

This flow would be used if a developer was building a Javascript form that allowed a user to request a book be purchased. The Javascript form would need to use this flow to login the user prior to collecting the information about the book being request for purchase.

This flow could also be used if a developer wanted to create a mobile application that allowed a user to view their checked out items, place holds or renew materials. Like the book request application, this app needs to log a user. To do this the app should to open a web browser and redirect the user to the appropriate login page. Once the user is logged in then the app would retrieve the user’s account information and display it.