Authorization Code Flow with PKCE

We recommend Authorization Code Flow with PKCE for retrieving user tokens in native and client side applications, this ensures that no access tokens are sent to the browser and there is no need to keep a client_secret in your application.

Authorization Code with PKCE is a flow that requires the client application send a sha256 hash of a cryptograpic random key along with the authorize request, this key then need to be supplied along with the code when retrieving the access token. It is mainly identical with Authorization Code but requires the extra code_challenge_method and code_challenge parameters. This method is primarily used in client side applications that cannot securely store a client_secret.

Authorize request

Initiating an authorization code flow with PKCE is similar to a regular authorization code request. The difference is that, since you cannot supply a client_secret in the token request, you need to specify a code_challenge_method and a code_challenge which is later used to verify that your application is allowed to extract the authorization_code in the token request.

The code_challenge is a base64 encoded sha256 hash of a cryptograpic random key (the code verifier) that you generate for your authorization and token requests. You will use the unhashed key in the following token request. Always set the code_challenge_method to S256.

GET /connect/authorize

CODE_VERIFIER = randomstring()
CODE_CHALLENGE = base64urlencode(sha256(CODE_VERIFIER))
HTTP/1.1 302 Found
Location: https://YOUR_APP/callback?code=AUTHORIZATION_CODE
Parameter Description
scope (required) The scopes which you want to request authorization for. These must be separated by a space. You can request any of the standard OpenID Connect (OIDC) scopes about users, such as profile and email, or any scopes supported by the target API (for example, Include offline_access to get a Refresh Token.
response_type (required) Indicates to Aritma ID which OAuth 2.0 Flow you want to perform. Use code for Authorization Code Grant (PKCE) Flow.
client_id (required) Your application's Client ID.
state (recommended) An opaque value the clients adds to the initial request that Aritma ID includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.
redirect_uri The URL to which Aritma ID will redirect the browser after authorization has been granted by the user.
code_challenge_method (required) Method used to generate the challenge. The PKCE spec defines two methods, S256 and plain, however, Aritma ID supports only S256 since the latter is discouraged.
code_challenge (required) Generated challenge from the code_verifier.
prompt To initiate a silent authentication request, use prompt=none, to force user interaction use prompt=login.
acr_values One or more values that controls how the authentication process is, use mfa to force a user with an active session to re-enter his/her/their mfa token (must be used together with prompt=login). See Authentication Context Class References

Token request

Once you have received your authorization code it's time to translate it into a usable access token. This is done using the /connect/token endpoint. In short you send a token request with grant_type=authorization_code together with the supplied code, your client_id and code_verifier (the same string generated for the authorize call), and the redirect_uri you provided in the authorization request.

POST /connect/token

Content-Type: application/x-www-form-urlencoded

HTTP/1.1 200 OK
Content-Type: application/json
Parameter Description
grant_type (required) Denotes the flow you are using. For Authorization Code (PKCE) use authorization_code.
client_id (required) Your application's Client ID.
code (required) The Authorization Code received from the initial /connect/authorize call.
redirect_uri (required) Must match the redirect_uri sent in the /connect/authorize call.
code_verifier (required) Cryptographically random key that was used to generate the code_challenge passed to GET /connect/authorize.