# 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](/apis/platform/ids/flows/authorization-code#authorize-request).
The difference is that, since you cannot supply a `client_secret` in the
[token request](#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](#token-request).
Always set the `code_challenge_method` to `S256`.

### GET /connect/authorize


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


```HTTP request
GET https://id.aritma.io/{tenant}/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
```


```HTTP response
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](/apis/platform/ids/acr_values) |


## 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


```HTTP
POST https://id.aritma.io/{tenant}/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
```


```HTTP Response
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](#get-connectauthorize). |