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

Copy

Copied

CODE_VERIFIER = randomstring()
CODE_CHALLENGE = base64urlencode(sha256(CODE_VERIFIER))

requestresponse

Copy

Copied

GET https://id.aritma.io/connect/authorize?scope=SCOPE&response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://YOUR_APP/callback&code_challenge_method=S256&code_challenge=CODE_CHALLENGE HTTP/1.1

Copy

Copied

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, banking.ais.read). 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

RequestResponse

Copy

Copied

POST https://id.aritma.io/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=YOUR_CLIENT_ID&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri=https://YOUR_APP/callback

Copy

Copied

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token":"eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}

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.