Proof Key for Code Exchange

The Proof Key for Code Exchange (PKCE) flow is a variant of Authorization Code flow. However, it provides another level of security by requiring the API Client to include a temporary secret (Code Challenge) in the Authentication Request and a secret verifier (Code Verifier) in the Token Request.

This authentication flow is more secured than the Authorization Code flow because it provides the means to ensure the authorization code received from Stems Accounts is verifiable. For this reason, this Authentication Flow is highly-recommended for native mobile applications and desktop applications, as long as these applications are built using native code (as in, not HTML5 applications).

To request an Access Token using the PKCE (pronounced pixie) flow, the API Client should perform the following steps:

1. The API Client generates a code verifier
2. API Client creates a code challenge from the code verifier (See Creating a Code Challenge for more info)
3. The API Client directs the browser to Stems Accounts' Authorization Endpoint along with the generated code challenge
4. Stems Accounts posts (or redirects) back to the API Client with an authorization code
5. Once the Authorization Code has been recieved, the API Client proceeds to verify the code before request a token

Creating a Code Challenge

Before the API Client issues the Authentication Request to Stems Accounts, it needs to generate a code verifier and a code challenge.

The code verifier is simply a random string. The only requirement is that the code verifier needs to be randomly-generated with a minimum length of 43 characters and a maximum length of 128 characters. This will then be used to generate a code challenge and to verify the Authorization Code received from the Authentication Response.

The value of the code challenge can vary based on the code_challenge_method parameter sent in the Authentication Request. If the code_challenge_method parameter can only have one of two values:

• plain: This is the default value. It tells Stems Accounts that no transformation has been applied to the code challenge. Therefore, it matches exactly the code verifier. Not Recommended
• S256: which means that the code challenge has been transformed to a SHA-256 hash of the code verifier. Strongly recommended

When setting the code_challenge_method parameter to S256 in the Authentication Request, you need to first create a hash of the code verifier using the SHA-256 Algorithm and then convert the hash to a Base64Url-encoded string:

BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge

Stems Accounts will associate the code challenge (received from the API Client in the Authentication Request) with the Authorization Code. Then, when the API Client issues the Token Request, Stems Accounts will attempt to match the code verifier with the code challenge received in the Authentication Request.

Authentication Request

When using the PCKE flow, your API Client should open a browser session and redirect the user to Stems Accounts' Authorization Endpoint. The Authentication Request is very similar to that of the Authorization Code flow. The only difference is that the response_type parameter must be set to code. The following parameters MUST be also included:

A typical request to the Authorization Endpoint would look like the following example:

GET /auth/connect/authorize?
client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A9595
&scope=openid+email+profile+roles
&response_mode=form_post
&state=MdNEdpV8mOT0dpzyfEnXklRmTTdWd2ek
&nonce=irr6Jltaqol9sUXwVKz8tlY1JlWQR5Bz
&code_challenge=I6hp0P4knRHxDxcpqPjLzvfhlYRq3CWBPJddasRDsA
&code_challenge_method=S256 HTTP/1.1
Host: accounts.stems.com.au

If the request to the Authorization Endpoint is successful, Stems Accounts will issue a POST request to the url specified in the redirect_uri with the Authorization Code in the body of the request if the response_form was present in the authentication request.

The body of the response from Stems Accounts will include the following form data:

When the response_form is not included in the authentication request, Stems Accounts will redirect back to the redirect_uri with the Authorization Code included in the url query string as in the example below:

GET /?code=85ff37999de045455b6eea8f194235fe
&state=345G2KJHG32JK5G34KLH2F46HK
&session_state=59306c731065bd5bef7d78ec90b4dc5a HTTP/1.1
Host: contoso.com

The Authorization Endpoint could return errors if the API Client is not setup properly or the request had invalid or missing parameters. When an error occurs, the Authorization Endpoint will return to the API Client's redirect_uri with an error parameter containing an error code and an optional error_description fragment parameter with details about the error.

Token Request

Once the Authorization Code has been received from Stems Accounts, the API Client can issue a POST request to the Stems Accounts' Token Endpoint.

The request to the Token Endpoint is similar to that of the Authorization Code flow. The only difference is that the request MUST also include a code_verifier parameter with the Code Verifier. See Creating a Code Challenge for more information about the Code Verifier value.

ID Token Validation

Once the API Client has received the ID Token, it is strongly recommended that it is validated to make sure it hasn't been tampered with. Refer to ID Token Validation of the Authorization Code section to learn how to validate an ID Token.