Proof Key for Code Exchange support

You can configure support for Proof Key for Code Exchange for OAuth clients.

Proof Key for Code Exchange (PKCE) support is a capability (defined in RFC 7636) that adds security when performing the authorization code flow on a mobile device. It addresses a possible security problem that can occur when the following conditions are true:

  • There is no client secret.
  • The browser or operating system is being used to perform the authentication request.
  • A native mobile application is consuming the redirect from the authentication request, and performing an exchange of code for access tokens at the token endpoint.

PKCE support aims to mitigate the risk of a bad actor on the mobile device intercepting the redirect back to native app, and maliciously using the authorization code and the returned access tokens. For a detailed explanation of the scenario, see the Internet Engineering Task Force (IETF) Request for Comments (RFC) 7636: https://tools.ietf.org/html/rfc7636

PKCE requires the OAuth client to generate a random string and perform a hash (SHA256 + BASE64URL) on this string. The initial string must be persisted for use at /token, and both the hash and the hash method are presented at /authorize. The authorization server, upon receiving the hash and the method, persists this value against the issued authorization code. When the authorization code is presented at /token, along with the initially generated string, the hash method is applied to the presented string and checked against the string presented at /authorize. If the two match, the request to /token is successful. If they do not match, the request is rejected.

The processing flow is as follows:

  1. Client generates a code_verifier, and computes code_challenge using code_challenge_method.
  2. Client makes request to /authorize.
  3. Authorization server performs standard OAuth request validation for /authorize.
  4. Authorization server checks for presence of code_challenge and code_challenge_method.
  5. Authorization server stores code_challenge and code_challenge_method against authorization code.
  6. Authorization server returns authorization code response.
  7. Client presents authorization code to /token including the additional code_verifier.
  8. Authorization server performs standard OAuth request validation for /token.
  9. Authorization server generates its own code_challenge, using the presented code_verifier, and the stored code_challenge_method.
  10. Authorization server compares its generated code_challenge, to the value which was presented in the initial request to /authorize(and stored against the authorization code).
  11. If the two match, then an access_token is issued. If the two do not, the request is rejected.
Note: The IETF specification contains a diagram of the above flow. See https://tools.ietf.org/html/rfc7636#section-1.1.

To use the IBM Security Verify Access support for PKCE, you must configure the OAuth client to set the requirePkce property to true. When this property of the OAuth client is set to true, the following conditions apply:

  • A new parameter is required in the request to /token.
    code verifier
    A cryptographic string of sufficient entropy such that an attacker cannot predict or guess its value, as specified in section 4.1 of the RFC. This value is used with the code_challenge_method presented in the /authorize request, to produce the value to check against the code_challenge, which is also presented at /authorize.
  • Two new parameters are required in the request to /authorize.
    code_challenge

    The product of the code_verifier and the code_challenge_method. Must be the product of the SHA256 + BASE64URL encode, as specified in section 4.2 of the RFC.

    code_challenge_method

    The method applied to the code_verifier as presented at /token, which is used to check the value of code_challenge. The value of code_challenge_method must be S256, as specified in section 4.2 of the RFC.