Authorization Code

Authorization Code grant type

The Authorization Code grant type is the most commonly used and most widely supported. It is a popular choice for services that offer APIs to be consumed by 3rd party web applications. The Authorization Code grant type flow requires the use of a browser. For mobile applications, this could be an embedded browser.

In this flow, the end user authenticates and provides consent directly to the Authorization endpoint of the OAuth Authorization Service. This is a browser endpoint and the method by which the end user is authenticated, and the user experience for user consent, are completely under the control of the Authorization Server.

Once authentication and consent are complete, the Authorization Service generates a short-lived, single-use, Authorization Code to be returned to the application. It is this authorization code that gives this grant type its name.

When the application receives the Authorization Code, it makes a direct connection to the token endpoint of the Authorization Service and exchanges the Authorization Code for an Access Token.

PKCE (Proof Key for Code Exchange)

PKCE (pronounced "pixie") is an extension to the Authorization Code grant type flow which provides mitigation against the authorization code being intercepted when working with public OAuth clients. The PKCE specification is RFC7636.

When using PKCE, the application (OAuth client) generates a long random string (between 43-128 characters) at the start of each flow. The string can contain A-Z, a-z, 0-9, dot (.), dash (-), underscore (_) and tilde (~). This is the code_verifier.

The application performs a SHA256 operation on the code_verifier string and base-64-url encodes the result. This is the code_challenge.

The code_challenge is sent to the authorization endpoint of the Authorization Server as part of the request that initiates the Authorization Code flow. The Authorization Server stores the code_challenge (indexed by the authorization code).

When the application calls the token endpoint of the Authorization Server (to request a token) it sends the code_verifier along with the authorization code. As part of its validation of the request, the Authorization Server performs its own SHA256 operation on the code_verifier and checks that it matches the code_challenge associated with the code.

📘

What if my application can't implement SHA256?

The PKCE specification provides an option for clients that can't implement a SHA256 hash operation. In this case the code_challenge is the same as the code_verifier. This provides mitigation against the authorization code being intercepted but is broken if an attacker can also intercept the request to the authorization endpoint.

💎

Jon Harry, IBM Security