Authorization Code + PKCE

With Hosted Login’s implementation of OpenID Connect (OIDC), the basic workflow for authenticating a user goes something like this:

1. The  user (via an OpenID Connect client) makes an authentication request and is authenticated.
2. The server sends the client an authorization code.
3. The client exchanges the authorization code for an access token.

As a general rule, this is a very secure process, especially when carried out by web applications running over a TLS network connection. However, there is at least one potential problem here, a problem that can be exacerbated if users are connecting by using mobile devices. Let’s take a moment to explain what that problem is, and then we'll detail how Hosted Login deals with that problem.

By default, a client can exchange the authorization code (and get back an access token) without having to prove that they are the rightful owner of that authorization code. For example, suppose Bob successfully logs on to a website and, as a result, the server sends him an authorization code. That’s good: that’s the way things are supposed to work.

However, suppose Toni somehow manages to hijack that authorization code and present it to the token endpoint (something known as an Authorization Code Interception Attack). The token endpoint won’t question this request: as long as the authorization code is valid the server exchanges that code for an access token. That means that Toni now has access to all the resources that Bob has access to. And she has that access for as long as the token remains valid (typically one hour).

Fortunately there’s a way to to help avoid code interceptions attacks: the Proof Key for Code Exchange (PKCE, pronounced “pixie”) extension. This extension enables clients to assure the token exchange server that the authorization code they want to exchange really does belong to them. Best of all, the client can do that without having to exchange a client secret with the server. That's the value of using PKCE, and that's why Akamai recommends that you use PKCE, a public clients (OIDC clients that don't even have client secrets) for user authentication and authorization.

But what exactly does PKCE do and how does it differ from the standard OIDC authorization flow? Here’s a brief explanation of how the process works.

PKCE Setup and Configuration

Back to top

Before a PKCE client makes an authentication request it creates a code verifier, a random string of 43 to 128 characters. For example:

After the client creates the code verifier, if takes that value and “hashes” it using the S256 hashing function. That turns the code verifier into a value similar to this:

The client then base64-url encodes the hashed string to create a code challenge string. For example:

Note. Hosted login requires the use of S256 to hash code verifiers. Although the PKCE standard allows for the use of plain-text code challenges, plain text is not supported by hosted login. You can verify this by looking at the discovery document to see which code challenge methods are supported.

As soon as you have the code verifier and code challenge string you're right to make an authorization request.

The Initial Authorization Request

Back to top

To make an authorization request using PKCE, two pieces of information must be included in that request: the code challenge string and the hashing method (S256) used to generate that string. This information is specified in the request as the code_challenge and code_challenge_method parameters, respectively. For example:

The following table summarizes the parameters used in the request, and also details the optional parameters available for use with Hosted Login:

cliient_id=22c9604-7b27-464f-bff5-83ba229323af

scope=openid email profile

redirect_uri=https://identitydocs.akamai.com/redirect

code_challenge= RTg4QjMyRUJCNzdBRTQ1MkM2NTAzRTVDOEQ5OTg
3QjIwMjVBNTcxQTU5RTJFNDYwMzJBQjYxRkM4NjQ0QzdBNw

code_challenge_method=S256

state=GA-ISU_6CwFn0tQTFiYD_-Gvy39Nb6iTdugdGIzTUng

https://identitydocs.akamai.com/redirect_uri?code=AH6S2WG_
XchALC-p&state=GA-ISU_6CwFn0tQTFiYD_-Gvy39Nb6iTdugdGIzTUng

prompt=login

ui_locales= fr-FR es-ES

&claims={"userinfo":{"birthdate":null}}

&claims={"id_token":{"organization":null}}

&claims={"userinfo":{"organization":null}, 
"id_token":{"organization":null}} 

display=page

As noted, for a Hosted Login end user, the preceding activities are carried out by clicking a Login button that takes them to the login page. Once there, the user is asked to log on to their existing account, either by logging on to a social login identity provider (social login) or by supplying a username and password (traditional login):

After supplying their email address and password (in the case of a traditional login) the user clicks Sign In and authentication takes place. To the end user, nothing has changed: they still log on to your website the way they log on to most websites.

Meanwhile, the authorization server uses the supplied credentials (or the social login token received from the social identity provider) and attempts to log the user on.

The Redirect URI and Authorization Code

Back to top

When the authorization server receives the PKCE request, the server saves a copy of the code challenge and the code challenge method before authenticating the user. If authentication is successful, the server returns the standard authorization response:

Note that the response includes the authorization code (highlighted in red), but it does notinclude either the code challenge or the code challenge method. You’ll see why in just a moment.

Exchanging the Authorization Code for an Access Token

Back to top

Let’s assume that Bob made the authorization request and that, after successfully logging on, he received his authorization code. It’s now time for the Open ID Connect client  to exchange that code for an access token. When he presents the code to the token exchange server, he must also present the code verifier (the original string value AdleUo9ZVcn0J7HkXOdzeqN6pWrW36K3JgVRwMW8BBQazEPV3kFnHyWIZi2jt9gA).

For example, a curl command for exchanging an authorization code for a set of tokens might look similar to this:

Two things to note here. First, no authentication is required. That's because this is a PKCE flow. Instead of configuring, say, Basic authentication, just be sure and include the code_verifier parameter. Second, remember that code_verifier, and all the other parameters, must be passed as an xxx-www-urlencoded body parameter. 

As you no doubt recall, when Bob made his initial authorization request the server took note of the code challenge and the hashing method associated with that request. Because of that, the server can now take the code verifier, hash the verifier using SHA 256, then base64url-encode the hashed string. If the value derived by the server matches the code challenge included in the original request, then the exchange will be approved and Bob will be sent his tokens. Why? That’s right: if Bob’s original code challenge and the code challenge calculated by the server match, the authorization server can be confident that it is communicating with the correct client.

To use a simple (and, admittedly, unrealistic) example, suppose Bob’s original code challenge was 1234ABCD. Bob submits his token exchange request, and the server calculates it’s version of the code challenger. Let’s see if they match:

Looks like we have a winner!

But suppose that, somewhere along the way, Toni intercepted Bob’s authorization code in the hopes of also snagging Bob’s access token. That’s going to be tough: after all, the authorization response does not include the code verifier, the code challenge, or the code challenge method. Toni can try including a code verifier but if it’s not the right code verifier (and the right algorithm) then the server won’t be able to recreate the code challenge. For example:

Those two values don’t match. And that’s because, even though Toni was able to hijack the authorization code, she does not have possession of the code verifier. In turn, that means that server will not honor her exchange request. 

Period.

If the authorization code is accepted, the token exchange endpoint returns an API response similar to this:

{
   "access_token": "03v-eeodppPrrHXXIx56pRLyDBaOldDxqEwI59MFCFGVuSkLRapzgmfwmEHyKWle",
   "refresh_token": "uHs1rLqRSpSyBpRpfplTI44Oh3gdkjJAa8Gzs3C5uDulN2yOnxU9mg1L6CaUAqz5",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "address email openid phone profile",
   "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE5NjRhNjE3YTc0YjZjZWNlMDM4NTdkYWExZThlMTQ0ZDExMTMyYTkiLCJ0e
XAiOiJKV1QifQ.eyJhdF9oYXNoIjoibklpWVRQaG9TaWs4Rmt0ZFl5cktZZyIsImF1ZCI6WyJhMjJjOTYwNC03YjI3LTQ2NGYtYmZm
NS04M2JhMjI5MzIzYWYiLCJodHRwczovL29wZW5pZGNvbm5lY3QubmV0L2NhbGxiYWNrIl0sImF1dGhfdGltZSI6MTU1MjU5
OTgyOCwiYXpwIjoiYTIyYzk2MDQtN2IyNy00NjRmLWJmZjUtODNiYTIyOTMyM2FmIiwiZXhwIjoxNTUyNjAzNDQyLCJnbG9iYW
xfc3ViIjoiY2FwdHVyZS12MTovL2NhcHR1cmUtYWxiLWJvcmRlci5tdWx0aS5kZXYub3IuamFucmFpbi5jb20veDNnbW5uamV5
enlycnQybm01ZHJmNW5rbjgvdXNlci8yZWRkMmYzMi0xZTQ5LTRiZjItYjE2NC03NjM3ODE3NjFiNTIiLCJpYXQiOjE1NTI1OTk4
NDIsImlzcyI6Imh0dHBzOi8vYXBpLm11bHRpLmRldi5vci5qYW5yYWluLmNvbS8wMDAwMDAwMC0wMDAwLTMwMDAtOD
AwMC0wMDAwMDAwMDAwMDAvbG9naW4iLCJzdWIiOiIyZWRkMmYzMi0xZTQ5LTRiZjItYjE2NC03NjM3ODE3NjFiNTIifQ.k
KPbex5j3ADyxZ_t8B8wiWUoDB7o8tamMjswCxMQKaTEJBpJBiYVATMdLvnd5HpZ5Hj_I0omt7Zq3svPFLvdy1xHC95KWyJu3
HK65ZP8Hc0tM3oLFjWhLYcRoJZVi5ButzP4RZr6QJgfUyKF3QT-GECFLXgOyRy1DP4j4Xev7F_MJ_nX4xdAutNsDvu6PGyI752
nS4cJ13kAbyD0puaoLwg1aAoMSa4wm1limPvv5HcnRAAZcyMQhaC13vHMnvCCRWzuHl94oNl2_ZblEtDQv_q_GfCvhXLrd1
VH7azarkeOtCNrD1aTyQ9owXJDxYJrcs2UTaop9tyA7_HgctWQ"
}

Here's what the different name-value pairs in that response represent:

If you’re curious about the actual contents of a token, see the article Hosted Login Token Reference. In addition to that, you can decode an access token or a refresh token by using the introspection endpoint, and you can use any of a number of different JSON Web Token (JWT) decoders in order to view the contents of an identity token.