Skip to content

Enhance the OAuth authorization with PKCE

Published   18 February 2020     Less than to read

HOORAY!! To enhance the security, the API now supports PKCE authorization. 🎉🎊

Proof Key for Code Exchange is an extension of the OAuth 2.0 Authorization Code Flow and Access Token Request by adding additional parameters. The usage of PKCE is completely optional and it is defined in RFC 7636. PKCE is particularly useful in insecure environments where decompiling the application reveals sensitive information like the Client Secret. Insecure environments can be e.g. Single Page Applications or Mobile Apps.

The code_verifier is a random generated string with a length between 43 and 128, so it is protected against decompiling. In the Authorization Code Flow the client sends a hashed version of the code_verifier (now called code_challenge) and the used hash method (called code_challenge_method) along with the required OAuth parameters to the token endpoint. When the client requests an access token, the code_verifier and the OAuth required parameters will be send to the token_endpoint. The token endpoint hashes the reviewed code_verifier and compares it with the stored code_challenge from the Authorization Code Flow. If both are equal, the PKCE check is passed. An overview about the all used OAuth 2.0 parameter is given in the Authentication section.

The new PKCE authorization comes with new error messages.

PKCE errors while requesting the autorization code
  • invalid_request: Incomplete PKCE code_challenge. When the code_challenge_method is not given, the code_challenge from the client needs to be base64 url encoded. The error means that the code_challenge cannot be base64 url decoded.
  • invalid_request: Error while Base64 decoding of PKCE code_challenge. This will be shown if the code_challenge_method is set to S256 but the code_challenge is no valid SHA-256 hash.
PKCE errors while requesting the access token
  • invalid_grant: Invalid PKCE code_verifier. There was an error at comparing the received code_verfier and the stored code_challenge.