Authorization (Auth) Code Flow with PKCE

Describes CyberArk Identity support for PKCE (Proof Key for Code Exchange) with the Authorization Code flow.

Introduction

CyberArk Identity OAuth2 custom application templates support the Proof Key for Code Exchange (PKCE) when configuring public applications, such as mobile apps or single-page apps, where the client secret is not secure. The PKCE OAuth2 flow for public applications requires that you do not use a client secret when configuring the application template. The steps for configuring the PKCE authorization code flow are similar to the regular authorization code flow except your application needs to use code_verifier, code_challenge, and code_challenge_method parameters instead of the client secret in the authorization request. The following is a general overview of the authorization flow for PKCE configurations:

  • The client application sends an authorization request with the code_challenge and the code_challenge_method to the authorization server.
  • The authorization server acknowledges receiving the code_challenge and the code_challenge_method, and then sends an authorization code to the client application.
  • The client application sends a token request along with the authorization code and the code_verifier.
  • The authorization server validates the code_verifier with the code_challenge it already received and then issues the access token so the user can log in to the application.

For more information on PKCE and terminology, see https://tools.ietf.org/html/rfc7636.

Configure the application in the Admin Portal

The steps to configure your application in the Admin Portal for PKCE are generally the same as the steps required for the regular OAuth2 Code Flow configurations, except PKCE configurations require that you configure the Client ID Type as List. See Authorization (Auth) Code Flow for details on adding the application and configuring it in the Admin Portal.

You do not configure the OpenID Connect custom application in the Admin Portal for OpenID Connect PKCE implementations.

Develop a Client using PKCE

The following is an example of the PKCE authentication process with your OAuth provider. For additional details, see Authorization (Auth) Code Flow.

📘

Note:

You need to have the following parameters before you start the token exchange process shown below:

  • code_verifier
  • code_challenge
  • code_challenge_method

The client generates these parameters using algorithms defined in the Internet Engineering Task Force (IETF) Specification.

  1. An authorize request is sent from a user's browser (the client application) with the code_challenge and code_challenge_method to the authorization server.
GET https://mytenant.idaptive.app/oauth2/authorize/myapplication?redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fcallback&client_id=my_service_user&response_type=code&code_challenge=1XnNCHd73dNHQcmyzG...QY&code_challenge_method=S256
GET https://mytenant.idaptive.app/oauth2/authorize/myapplication?redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fcallback&client_id=my_service_user&response_type=code&code_challenge=1XnNCHd73dNHQcmyzG...QY&code_challenge_method=S256&scope=openid
  1. The authorization server redirects users to the callback URL with the following code:
GET http://localhost:5000/callback?responseType=code&code=vXUU1U8L_ZsySpxOBH_isI0B...
  1. The client application sends the token request with the code_verifier to the authorization server.
POST https://mytenant.idaptive.app/oauth2/token/myapplication
{
    'grant_type': 'authorization_code',
    'code': 'gJeB-8RjMu9q6n5zJIN7SvAf...',
    'redirect_uri': 'http://localhost:5000/callback',
    'client_id': 'my_service_user',
    'code_verifier': 'NkTkDHFz.Dos5qUi...'
}
  1. The authorization server responds to the client application with an access_token and then the user is logged in to the client application.
{
    'access_token': 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsMN0Y5NkVERjc5MEYx...',
     'token_type': 'Bearer',
    'expires_in': 18000,
    'scope': ''
}