PKCE flow

Proof Key for Code Exchange (PKCE, pronounced "pixie") is an extension of the OIDC authorization code flow. It enhances security by mitigating the risk of authorization code interception attacks, particularly in public clients like mobile or single-page applications (SPAs) that cannot securely store client secrets.

PKCE achieves this by introducing an additional verification step during the authorization process. This step ensures that only the client that initiated the authorization request can use the received authorization code to retrieve tokens.

What is the PKCE flow used for?

The PKCE flow is used to:

• Prevent authorization code interception attacks:
  In a traditional OIDC authorization code flow, if an attacker intercepts the authorization code, they could potentially exchange it for tokens. The PKCE flow mitigates this risk by requiring a code verifier during the token exchange, which only the legitimate client knows.
• Enable secure authentication for public clients:
  The PKCE flow is designed for applications that cannot securely store a client secret, such as:
  • Mobile applications
  • Single-page applications (SPAs)
• Support OAuth 2.0 compliance:
  The PKCE flow ensures compliance with modern security standards and best practices, making it a preferred flow for securing sensitive data.

Setting up the PKCE flow on Strivacity

Pre-requisites

• Access to the Strivacity Admin Console.
• An existing OpenID Connect (OIDC) client is set up within the platform.
• Familiarity with Strivacity’s OIDC settings and endpoints.

Configure the PKCE flow

1. Configure the OIDC Client in the Admin Console
   1. In the left-hand menu, select Applications and choose an application from the list.
   2. When editing your application, go to the Clients tab and select an OAuth2 client. Navigate to the OAuth2/OIDC tab.
   3. Set the Token endpoint authentication method to: None (applications with no secret).

Execute the PKCE flow

1. Generate the Code Verifier

   1. The Code Verifier is a randomized cryptographic string that:
      1. Includes alphanumeric characters (A-Z, a-z, 0-9) and punctuation (hyphen, period, underscore, tilde).
      2. Is between 43 and 128 characters long.
   2. Use an online tool like PKCE Tools or generate it programmatically.

2. Generate the Code Challenge

   1. The Code Challenge is derived from the Code Verifier by:
      1. Hashing the Code Verifier using SHA-256.
      2. Encoding the hashed value in Base64 URL format.
   2. Example code for generating the Code Challenge:

      base64urlencode(sha256(code_verifier))
      

3. Construct the authorization URL

   1. Use the following template to create the authorization URL:

      https://BRAND_DOMAIN.strivacity.com/oauth2/auth?
      response_type=code&
      client_id=CLIENT_ID&
      state=<random_string>&
      scope=<openid_and_additional_scopes>&
      redirect_uri=REDIRECTION_URI&
      code_challenge=<code_challenge>&
      code_challenge_method=S256
      

   2. Replace placeholders (e.g., CLIENT_ID, REDIRECTION_URI) with appropriate values.

4. Handle the authorization response

   1. After the customer authenticates, the authorization endpoint redirects to the specified REDIRECTION_URI with the following parameters:

      https://<REDIRECTION_URI>?
      code=GENERATED_AUTHORIZATION_CODE&
      scope=<scopes>&
      state=<random_string>
      

5. Exchange authorization code for tokens

   1. Send a POST request to the token endpoint with:

      1. Request body
         When making the token request, the request body must be sent as application/x-www-form-urlencoded content type. The parameters should be URL-encoded and concatenated using the & character.
         Example request body:
         Text

         grant_type=authorization_code&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Foidc-callback&code=6weGDiA5xztjCbGN4KNItfBfP2mlpoQ5nQI3uLG3IOI.XGCc1gGolU3zVnWrnmctae3dDy0L4ORfCwmtgYonaec&code_verifier=e8285a085183407db7dab1e75a94f47fad21fa1c23fa4916b81e26d6ba0da436b5b84563a88d4182839af81952affbf9&client_id=2f9d832ff70744bcb93df958a74a570c
         

         Make sure the request includes the following parameters:
         1. grant_type: Set to authorization_code.
         2. redirect_uri: The redirect URI that was used in the authorization request, URL-encoded.
         3. code: The authorization code received from the authorization response.
         4. code_verifier: The original Code Verifier value used when generating the Code Challenge.
         5. client_id: The client ID of the application.

   2. The token endpoint responds with:

      1. Access token
      2. ID token
      3. Refresh token (if requested via scopes)

Differences between PKCE and non-PKCE authorization code flow

PKCE flow:

• Includes code_challenge and code_challenge_method parameters in the authorization URL.
• Token endpoint authentication method: None (applications with no secret).
• Requires the Code Verifier during the token exchange.

Non-PKCE flow:

• Does not include code_challenge parameters in the authorization URL.
• Token endpoint authentication method: Basic (client ID and secret sent in the authorization header), Post (client ID and secret sent in the request body), or JWT (JWT is signed with the client's private key and sent in the request body).
• Uses both client ID and client secret for token exchange.

By following this guide, you can securely implement the PKCE flow, ensuring that your applications are compliant with modern security standards and resilient against common threats like code interception.