OAuth 2.0 PKCE Flow

PKCE (Proof Key for Code Exchange) is an extension to the Authorization Code flow designed to enhance security for public clients (e.g., mobile or JavaScript applications). It mitigates certain attack vectors, such as interception of authorization codes, and can be applied to any client type.

You need a code verifier, an authentication code challenge, and an OAuth provider configuration to initiate the PKCE flow.

The code_challenge and code_challenge_method are unique to the PKCE flow and must be included in the authorization request.

API Endpoint:

https://<siteurl>/service/oauth/{OauthAppName}/authorize?client_id={client_id}&redirect_uri={Callback URL}&scope={Scope}&response_type=code&state={random long string}&code_challenge={code_challenge}&code_challenge_method=SHA256

API Method: GET

Query Parameters:

Parameter	Requirement	Description
client_id	Required	OAuth Client ID
redirect_uri	Required	Callback URL to redirect users after authentication (e.g., https://abc.com).
state	Optional	Random string to maintain state between the request and response.
scope	Optional	Scopes to define access permissions (e.g., openid).
response_type	Required	The value must be code for Authorization Code flow.
code_challenge	Required	BASE64-URL-encoded string of the SHA256 hash of the code verifier.
code_challenge_method	Required	Set to SHA256 for PKCE flow.

1. Code Verifier: A high-entropy cryptographic random string. This is sent as a code_verifier in Step 2.
2. Code Challenge: Derived from the code verifier, this is included in the authorization request (code_challenge).

Tools: Use LoginRadius-provided tools or libraries to generate the code_verifier and code_challenge.

Example Authorization Request:

GET https://<siteurl>/service/oauth/{OauthAppName}/authorize
?client_id=your_client_id
&redirect_uri=https://your_callback_url
&response_type=code
&scope=openid
&state=random_string
&code_challenge=base64_encoded_challenge
&code_challenge_method=SHA256

Upon successful authentication, the provider redirects the user to your redirect_uri with the authorization code:

https://your_callback_url?code={authorization_code}

Using the code received in Step 1 and the code verifier, request an access token.

API Endpoint:

https://<siteurl>/api/oauth/{OauthAppName}/token

API Method: POST

Request Body:

{
  "client_id": "your_client_id",
  "redirect_uri": "https://your_callback_url",
  "grant_type": "authorization_code",
  "code": "authorization_code",
  "code_verifier": "generated_code_verifier"
}

Request Body Parameters:

Parameter	Requirement	Description
client_id	Required	OAuth Client ID.
redirect_uri	Required	Callback URL used during authorization.
grant_type	Required	It must be set to authorization_code.
code	Required	Authorization code received in Step 1.
code_verifier	Required (if no client secret)	Original random string used to generate the code challenge.
client_secret	Optional (if using code verifier)	OAuth Client Secret (for confidential clients).

API Response:
If the code_verifier matches the code_challenge, the server responds with the access token:

{
  "access_token": "c5a****b-****-4*7f-a********e4a",
  "token_type": "Bearer",
  "refresh_token": "5*****82-b***-**82-8c*1-*******7ce",
  "expires_in": 11972
}

Summary

• PKCE ensures additional security for public clients by requiring the use of code_verifier and code_challenge.
• Key Steps:
  1. Generate the code_verifier and code_challenge.
  2. Include them in the authorization request.
  3. Use the code_verifier during the token exchange process.

By following these steps, you’ve successfully implemented the OAuth 2.0 PKCE flow in your application.