Authorization Code with PKCE

Authorization Code with Proof Key for Code Exchange (PKCE) flow is an extension of the Authorization Code grant flow. However, with PKCE, requests do not need to include the client_secret in the /token request. The PKCE flow reduces security risks for desktop and mobile applications because the client_secret does not need to be embedded in source code.

Authorization Code with PKCE was designed for desktop and mobile apps, but it can be also used in web apps.

How it works

• code_verifier and code_challenge are generated.
• code_challenge is submitted to /authorize endpoint.
• The authorization server returns an authorization code.
• code_verifier and authorization code are submitted to /token endpoint.
• The server responds with an oauth_code, an id_token, an access_token, and a refresh_token.
• The access_token is used to authorize the application.

The following is a diagram that shows the Authorization Code with PKCE flow:

Applications using Authorization Code with PKCE must use Serial PKCE to refresh the access token with Trimble Identity. This means that a new (code_verifier, code_challenge) pair must be provided on each token or token refresh request. This creates a request sequence:

Authorization Request (code_challenge1) => Token Request (code_verifier1, code_challenge2) => Token Refresh(code_verifier2, code_challenge3) => …

For more details, check out this OAuth.net resource.

What you need

You will need the following information from the Developer Console.

• Client name
• Client id
• Client secret
• Callback url

Generate code challenge and verifier

The first step is the generation of a new code verifier and code challenge. This step is repeated for every authorization request.

Code verifier

The code verifier string must meet the following requirements:

• Include only the following characters: A-Z, a-z, 0-9, punctuation characters ._- or ~ (hyphen, period, underscore, and tilde.)
• The verifier string must be between 43 and 128 characters long.

Code challenge

The challenge code is a BASE64-URL-encoded string of the SHA256 hash of the code verifier.

Authorization Request

After generating the challenge code, it must be submitted to the authorization server in a GET request. The code generated is valid for 10 minutes.

Parameters

Prompt Options

Possible values for the optional prompt parameter

Authorization Response

The following is an example of the callback made to your callback endpoint. You will need to parse the code parameter from the callback to use in your token call.

http://localhost:5173/auth/callback?
code=us_9fd5fee3f3c74267910f8ed7c71c85a8&
state=Hn4K-n1m00000CiUUV-vOUNcOJZ8Jh_4shoo

Token Request

Authorization Server responds with an ID Token and Access Token (and optionally, a Refresh Token).

To later refresh the access token, another (code_verifier, code_challenge) pair needs to be created.

Headers

Body

Token Response

If the token request succeeds, the server responds with a 200 response code.

Response fields

Example response

{
  "access_token": "8aca1...",
  "refresh_token": "861e9...",
  "expires_in": 3600,
  "id_token": "eyJhbG...",
}

Refreshing the token

If the access token expires, it can be refreshed using the one-time refresh token.

Another (code_verifier, code_challenge) pair must be created.

The server will respond with a Token Response.

Headers

Body

Examples

Postman

Fork this Postman collection into your own workspace to quickly get started using Authorization Code with PKCE.

You need the following from your Developer Console application:

• Client name
• Client id
• Client secret
• Callback url

To use with Postman, the Postman callback url (https://oauth.pstmn.io/v1/browser-callback) must be configured for your application.