OIDC Authorization Flow requesting an Authorization Code with PKCE

The PKCE Flow makes it possible to generate an access token from a non-secure client like a browser or a mobile app without the risk of leaking the client secret.

❗

Not all API endpoints can be used to make calls on behalf of the user.

How it works

This flow requires the response_type=code parameter to indicate that you request an authorization code.

Code Verifier and Challenge

In addition to the normal OIDC flow, this variant uses a code_verifier and code_challenge to make sending the client secret obsolete.

Allowed characters for the code_verifier are: [A-Z], [a-z], [0-9], "-", ".", "_" and "~", with a minimum length of 43 characters and a maximum length of 128 characters. The code_challenge is the SHA256 Hash value of the code_verifier URL safe base64 encoded without any trailing "=" character. The are several libraries and snippets to support you with the generation:

Python

JavaScript

Rust

Example

We are using a minimal verifier aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

to generate a challenge like so:

echo -n "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" | shasum -a 256
> 66d34fba71f8f450f7e45598853e53bfc23bbd129027cbb131a2f4ffd7878cd0

Authentication Request

https://demo.unidy.de/oauth/authorize?response_type=code&client_id=ileuI8NDtt1WXEdp6xzekX7o7Sjp-m0lnQbWetmR4iQ&redirect_uri=https://docs.unidy.io&scope=tickets:read tickets:write&code_challenge=66d34fba71f8f450f7e45598853e53bfc23bbd129027cbb131a2f4ffd7878cd0&code_challenge_method=S256

The parameters in detail:

Parameter	Description
`client_id`	You will receive the client id from the Unidy team.
`redirect_uri`	This is where the browser is redirected after a successful login.
`response_type`	`code` indicates, that an authorization code is requested.
`scope`	The access token will have those API rights.
`code_challenge`	The hashed code verifier is the code challenge.
`code_challenge_method`	`S256` indicates that we used sha256 to hash the code verifier.

The response will be a redirect to an URL containing the authorization code:

https://docs.unidy.io/?code=N0cEGsK3ccR9pb5GtyEw0ISVUkWGunAYJpCkvG_yLwY

Token Request

Request an access token in exchange for the authorization code

curl -X 'POST' \
  'https://demo.unidy.de/oauth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "ileuI8NDtt1WXEdp6xzekX7o7Sjp-m0lnQbWetmR4iQ",
  "code_verifier": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "code": "N0cEGsK3ccR9pb5GtyEw0ISVUkWGunAYJpCkvG_yLwY",
  "grant_type": "authorization_code",
  "redirect_uri": "https://docs.unidy.io"
}'

The response from the server has the following JSON format

{
  "access_token":"<ACCESS_TOKEN>",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"<REFRESH_TOKEN>",
  "scope":"tickets:read tickets:write",
  "created_at":1234567890
}

Also check the documentation for OIDC Refresh Token on how to renew the access token.