Securing Access Token Calls with PKCE

PKCE (Proof Key for Code Exchange - RFC 7636) is supported to enhance the security of the OAuth 2.0 authorization code grant. PKCE is applicable only for public OAuth clients that use the authorization code grant, which are vulnerable to the Man In The Middle (MITM) attack. In such cases, the client application should enforce PKCE by giving proof to the authorization server that the authorization code belongs to the client application. Only then the authorization server issues an access token for the client application. For more information about PKCE specification, see https://datatracker.ietf.org/doc/html/rfc7636.

By default, API Gateway does not enforce PKCE. API Gateway provides backward compatibility support for APIs migrated from the 10.1 version or higher.

When an external authorization server is used, API Gateway is not involved or remains out of scope with regards to how the consumer application retrieves a token from the external authorization server or its security arrangements. In such scenarios, API Gateway is involved only when validating the token before giving an application access to the API(s).

The PKCE flow works with these parameters:

Code Verifier. The code verifier should be a high-entropy cryptographic random string with a minimum of 43 characters and a maximum of 128 characters.

Code Challenge. The code challenge is created by SHA256 hashing the code verifier and then applying base64 URL encoding of the resulting hash. If the client cannot do the hashing and encoding transformation, it can use the code challenge method as plain where the code challenge is same as code verifier.

Code Challenge Method. This is an optional parameter. If the client uses SHA256 hashing the code challenge method value must be S256. If no hashing is done, then the code challenge method value must be plain. When code challenge method is plain , the code challenge value is the same as the code verifier. If the code challenge method value is not passed in the client request then plain would be considered as default value.

When you enforce PKCE, the public OAuth client creates a secret called the code verifier. The client also generates the code challenge for the corresponding code verifier. The PKCE flow is explained as follows:

1. When the client invokes the authorization endpoint (http(s)://hostname:port/invoke/pub.apigateway.oauth2/authorize) on the authorization server, the client sends the code challenge and code challenge method to the authorization server.

2. The authorization server validates the request. If the request is valid, the authorization server generates the authorization code and saves the supplied code challenge and code challenge method in the OAuthPKCE cache.

3. The client invokes the token endpoint (http(s)://hostname:port/invoke/pub.apigateway.oauth2/getAcessToken) on authorization server to exchange the authorization code for an access token. The client also supplies the additional input parameter code verifier.

4. Authorization server applies the code challenge method to the supplied code verifier and generates the code challenge. If the generated code challenge value matches with the code challenge value supplied to the authorization endpoint service (in step 1), then the token endpoint service issues the access token to the client.

The following diagram summarizes the PKCE flow:

In API Gateway, you can enforce PKCE at the following levels:

Global level. Using a platform-level global setting, you can enforce PKCE for all the applications. For more information about how to enforce PKCE at global level, see How do I enforce PKCE globally?

Application level. On a need to have basis, you can also enforce PKCE for a specific application. For more information about how to enforce PKCE at application level, see How do I enforce PKCE at application level?