Authorization Code + PKCE
How Does it Work?
Obtaining an Access Token using the 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.
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 |
|
| 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 |
|
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_challenge=QzZCNjgzNjNEQzVFQjIzODMzMTRENDRFMzFCNEFFNDMyN0ZEMTY5MzAzNTFCRjAyOUREODNGMzAzODhBRjgxRg== &code_challenge_method=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 Authorization Code + PKCE flow is to use the Authorization Code to request an Access Token.
Base URL: https://oauth.oclc.org/token
Parameters
| Name | Description | Required? | Expected / Sample Values |
|---|---|---|---|
| grant_type | The type of grant being used to obtain the access token. | Yes | authorization_code |
| code | The authorization code retrieved | Yes | auth_Ztm8UjLSKpP5V0Gskgev3v2G21sfGx18vxtA |
| 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 |
| 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 &client_id=jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa &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.