Qodex.ai

Configure a PKCE Authorization Workflow

Number of APIs: 6

In some cases, as with applications on native devices, the use of an authorization code grant can be compromised by authorization code interception attacks. The attacking application gains access to the client secret, intercepts the authorization code, and is able to exchange the intercepted authorization code for an access token.

Proof Key for Code Exchange (PKCE) authorization requests specify additional parameters in the request to prevent malicious apps from intercepting the authorization code. PKCE uses a random key, a code_verifier, that is used to compute a code_challenge parameter, which functions like a temporary application secret (unique to a single token request). PKCE works as follows:

  1. The client creates and records a code_verifier secret, which is a random value between 43 and 128 characters in length.

  2. The client uses the code_verifier value to compute the code_challenge value. The code_challenge_method is the transformation method that creates the code_challenge value. This parameter value is also recorded.

  3. The authorization request includes the code_challenge and in some cases the code_challenge_method parameter values in the request. The code_challenge_method is an optional parameter. It defaults to plain if not specified (which generates an error when the S256_REQUIRED PKCE enforcement option is specified by the application).

  4. The authorization server records the code_challenge and the code_challenge_method parameter values, and responds by issuing the authorization code.

  5. The client sends the authorization code to the /{{envID}}/as/token endpoint. The token request requires the code_verifier secret created in step 1.

  6. The authorization server uses the code_challenge_method to transform the code_verifier value and compare it to the code_challenge value submitted and recorded in the authorize request.

  7. If these values are equal, an access token is granted. If they are not equal, access is denied.

Workflow tasks

This scenario illustrates the following operations supported by the PingOne APIs:

  • Create an application and set its pkceEnforcement property.

  • Create an authorization request that includes code_challenge and code_challenge_method parameter values.

  • Create a token request that includes the code_verifier secret.

Prerequisites

Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.

Workflow order of operations

To enable a PKCE authorization workflow, the following tasks must be completed successfully:

  1. Make a POST request to /environments/{{envID}}/applications to define an OpenID Connect native app type that uses an authorization code grant.

  2. Make a GET request to /{{envID}}/as/authorize to initiate authorization and submit the code_challenge and code_challenge_method values to the authorization server.

  3. Make a GET request to /{{envID}}/flows/{{flowID}} to verify the flow initialization.

  4. Make a POST request to /{{envID}}/flows/{{flowID}} with the application/vnd.pingidentity.usernamePassword.check+json content type to submit the username and password.

  5. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the authorize resume endpoint.

  6. Make a POST request to /{{envID}}/as/token to exchange the authorization code returned by the resume endpoint for an access token.

Note: Before you begin this activity, you must create the code_verifier value and use it to compute the code_challenge value. The Qodex collection uses a script to create these values and write them to your Qodex environment. If you choose to create these values manually, you can use the PingOne PKCE Code Generator and record your values as variables in your Qodex environment. This scenario uses the S256_REQUIRED PKCE enforcement option for illustrative purposes only. You can also use the REQUIRED option, which specifies that a PKCE code_challenge is required and any code challenge method is acceptable. For more information, see RFC7636.

  1. Step 4: Submit username and password POST {{authPath}}/{{envID}}/flows/{{flowID}}

  2. Step 6: Get the token POST {{authPath}}/{{envID}}/as/token

  3. Step 1: Create the application connection POST {{apiPath}}/environments/{{envID}}/applications

  4. Step 2: Submit the authorize request GET {{authPath}}/{{envID}}/as/authorize?response_type=code&client_id={{PKCEAppID}}&redirect_uri=https://www.example.com&scope=openid&code_challenge={{codeChallenge}}&code_challenge_method=S256

  5. Step 3: Verify flow initialization GET {{authPath}}/{{envID}}/flows/{{flowID}}

  6. Step 5: Call the resume endpoint GET {{authPath}}/{{envID}}/as/resume?flowId={{flowID}}