Welcome to the OAuth server

This server implements OAuth 2.0:

Getting started

To use this OAuth server, please contact us to request an OAuth application.

Please provide a short description of the application you are creating, along with the details below. No worries if you are unsure - we can use the description you provide to help.

  1. The client type: public or confidential?
  2. The grant type: authorization, client-credentials or device?
  3. The allowed redirect URIs.
  4. The resources you would like to access. Please explore our API documentation, and our GraphQL API.

Example (authorization)

1. Generate PKCE code verifier and challenge

// Generate a code verifier (random string)
const codeVerifier = crypto.randomUUID().replace(/-/g, '');

// Create a code challenge (SHA-256 hash of verifier)
const encoder = new TextEncoder();
const data = encoder.encode(codeVerifier);
const digest = await crypto.subtle.digest('SHA-256', data);
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

2. Request authorization

Redirect the user to the following URL:
https://auth.edfgb-kraken.energy/authorize/?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=YOUR_REDIRECT_URI&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256
NEVER include a secret in this URL because it is visible in the browser address bar.
At this step, the user is presented with the choice to approve or deny access. If the user approves, the browser redirects to YOUR_REDIRECT_URI and includes the AUTH_CODE in the URL query params.

3. Exchange authorization code for access token

Your handler at YOUR_REDIRECT_URI needs to perform the following call:
POST https://auth.edfgb-kraken.energy/token/
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&
client_secret=CLIENT_SECRET& # omit for public clients
grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=YOUR_REDIRECT_URI&
code_verifier=YOUR_CODE_VERIFIER
If you intend to make this call from the frontend, the OAuth application should be public and the secret omitted from the request.
If you intend to make this call from the backend, the OAuth application should be confidential and the secret included in the request.

4. Access protected resource

GET https://api.edfgb-kraken.energy/resource/
Authorization: YOUR_ACCESS_TOKEN

Example (client credentials)

1. Exchange credentials for an access token

POST https://auth.edfgb-kraken.energy/token/
Authorization: Basic BASE64_ENCODED(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

2. Access protected resource

GET https://api.edfgb-kraken.energy/resource/
Authorization: YOUR_ACCESS_TOKEN

Example (device)

1. Authorize device

POST https://auth.edfgb-kraken.energy/device-authorization/
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID

The device should use the response to display or communicate the user_code and the verification_uri to the end user. Devices with screens can display this information visually, while devices without screens may use alternatives like audio or Bluetooth.

         +-----------------------------------------------+
         |                                               |
         |  Using a browser on another device, visit:    |
         |  https://auth.example.com/device              |
         |                                               |
         |  And enter the code:                          |
         |  ETE39050                                     |
         |                                               |
         +-----------------------------------------------+

The user visits the verification_uri to authenticate, inputs the user_code and authorizes the device.

2. Exchange device code for access token

While the user is authorising, the device should periodically attempt to acquire an access token (at a rate specified by the interval seconds):

POST https://auth.edfgb-kraken.energy/token/
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&device_code=DEVICE_CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code

3. Access protected resource

GET https://api.edfgb-kraken.energy/resource/
Authorization: YOUR_ACCESS_TOKEN

Example (token exchange)

RFC 8693 delegation semantics are supported. This means that you will use the client credentials token in both the Authorization header and the actor_token, as shown below.

1. Retrieve an access token for your client credentials app, as described in Example (client credentials).

2. Assuming EXTERNAL_IDP_USER_ACCESS_TOKEN has been issued by your external IdP, perform the token exchange call:

POST https://auth.edfgb-kraken.energy/token
Authorization: YOUR_CLIENT_CREDENTIALS_ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded

grant_type="urn:ietf:params:oauth:grant-type:token-exchange"&
actor_token_type="urn:ietf:params:oauth:token-type:access_token"&
actor_token=YOUR_CLIENT_CREDENTIALS_ACCESS_TOKEN&
subject_token_type="urn:ietf:params:oauth:token-type:access_token"&
subject_token=EXTERNAL_IDP_USER_ACCESS_TOKEN

3. Access protected resource

GET https://api.edfgb-kraken.energy/resource/
Authorization: YOUR_ACCESS_TOKEN

Resources