Skip to main content

Obtaining Access Tokens Using Authorization Code Flow

Authorize and authenticate client applications using the OAuth Authorization Code Flow. Get access tokens for Raidiam API access.

For a Sample Postman collection, see the Authorization Code Flow: Obtain Access Token section.

Prerequisites​

  • Super User or Data Administrator access to the platform or User Type with appropriate permissions

  • Active and valid Applications (Software Statement) with the scope directory:website granted

    If not yet added, Add and Manage Applications.

    Make sure your organisation has a Role that enables the organisation resources to request the directory:website scope and Add Application Roles.

  • Active Transport Certificate

    If not yet added, Add Certificate for organisation (shared between apps) or application (associated with a single app only).

  • Active Signing Certificate along with a Public and Private Keys if your application is required to use Signed Request Objects or uses the private_key_jwt client authentication method.

    If not yet added, Add Certificate for organisation (shared between apps) or application (associated with a single app only).

Add .well-known Endpoint​

Add Raidiam's Authorisation Server /.well-known endpoint to your OAuth library configuration.

Your OAuth library should be able to get the server's configuration.

Sample /.well-known: https://auth.sandbox.raidiam.io/.well-known/openid-configuration

The /.well-known endpoint contains all the information about the Authorisation Servers you need to successfully integrate with the server and get access tokens, for example:

  • Pushed Authorisation Request (PAR) Endpoint: "pushed_authorization_request_endpoint": "https://auth.sandbox.raidiam.io/request"

  • OAuth Authorization Endpoint:"`authorization_endpoint": "https://auth.sandbox.raidiam.io/auth"

  • OAuth Token Endpoint:

    • "token_endpoint": "https://auth.sandbox.raidiam.io/token" - for clients authenticating themselves using the private_key_jwt method.

    • mTLS Endpoint Aliases - for clients authenticating themselves using the tls_client_auth method:

"mtls_endpoint_aliases": {
    "token_endpoint": "https://matls-auth.sandbox.raidiam.io/token",
    "revocation_endpoint": "https://matls-auth.sandbox.raidiam.io/token/revocation",
    "introspection_endpoint": "https://matls-auth.sandbox.raidiam.io/token/introspection",
    "device_authorization_endpoint": "https://matls-auth.sandbox.raidiam.io/device/auth",
    "registration_endpoint": "https://matls-auth.sandbox.raidiam.io/reg",
    "userinfo_endpoint": "https://matls-auth.sandbox.raidiam.io/me",
    "pushed_authorization_request_endpoint": "https://matls-auth.sandbox.raidiam.io/request",
    "backchannel_authentication_endpoint": "https://matls-auth.sandbox.raidiam.io/backchannel"
}

Add Transport Certificate to Application Configuration​

[Add Transport Certificate for your organisation]](/docs/how-tos/certificates) and add it to your OAuth library client's configuration.

The Transport Certificate will be used in mutual Transport Layer Security (mTLS) to establish a secure connection between your client and the authorisation server.

Your OAuth client library should be capable of verifying the authorisation server's certificate.

note

If you are using cURLs to test the integration, you can disable checking the server's certificate using the -k flag or --insecure option.

Scopes in Authorization Code Flow​

In OAuth, scope is a mechanism to limit an application's access to a user's account. An application can request one or more scopes. This information:

  • Must be included in the call to the PAR endpoint, OAuth Authorization Endpoint, and OAuth Token Endpoint.

  • Is presented to the user in the consent screen (after the call to the OAuth Authorization Endpoint)

The access token issued to the application is limited to the scopes granted by the user.

In Raidiam, the scopes your application can request are determined by the application's Role and its associated Metadata.

To request the directory:websitescope, the application needs to have the scope Role Metadata Type assigned with the value set to directory:website.

Note that the application Role is not the value of the scope parameter.

For Read/Write operations, the scope parameter value needs to be directory:website

Prepare Signed Request Object​

If needed, prepare a Signed Request Object (RFC9101) with the authorization request parameters.

This step is not required if the Require Signed Request Object option is disabled in advanced Application configuration.

You can check it in Applications > your application > Advanced Configuration view if you are a Super User and the role attached to the Application is of the directory type.

The parameters are represented as the JSON Web Token (JWT) Claims of the object. Additionally, the JWT should contain the iss (issuer - your client ID) and aud (audience - the authorisation server URL) claims.

{
  "client_id": "19283akf98",
  "aud": "https://auth.sandbox.raidiam.io",
  "iss": "19283akf98",
  "exp": 1723734583,
  "nbf": 1723734283,
  "response_type": "code",
  "code_challenge_method": "S256",
  "nonce": "gXGldLyaatu",
  "scope": "openid trust_framework_profile directory:website",
  "claims": {
      "id_token": {
      "trust_framework_profile": {
          "essential": true
      }
      }
  },
  "redirect_uri": "https://www.example.com",
  "state": "xyaaaABC124",
  "code_challenge": "rV7liRb2IT4NYXNLvqrKoazWf9Gb1O3ekIndA8wQLhA",
  "response_mode": "query.jwt"
}

To sign the JWT, utilize JSON Web Signature (JWS RFC7515) and a signing key added within your organisation.

Request to PAR Endpoint​

Push the contents of the authorization request to the Raidiam's Pushed Authorization Request (PAR) /requests endpoint.

Pushed Authorization Requests, defined by the RFC9126specification, enable client applications to push the payload of the authorization request directly to the OAuth Authorisation Server and receive a request URI in exchange -- as a reference to the authorization request payload data in the subsequent call to the authorization endpoint.

Below you can find example requests to the Raidiam's /request (PAR) endpoint if Signed Request Objects are not required.

curl --location --request POST 'https://{base_url}/request'\ 
--cert /path/to/your/certificate.pem \ 
--key /path/to/your/private.key \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'response_type={response_type}' \ 
--data-urlencode 'client_id={client_id}' \ 
--data-urlencode 'scope=[scopes]' \ 
--data-urlencode 'redirect_uri=[redirect_uris]' \ 
--data-urlencode 'state={state}' \ 
--data-urlencode 'code_challenge_method=S256' \ 
--data-urlencode 'code_challenge={code_challenge}' \ 
--data-urlencode 'response_mode=query.jwt'

As a response to your request, you receive a request_uri you can use in the subsequent call to the authorization endpoint.

Request Authorization​

  1. Redirect the user to the Raidiam's OAuth Authorization /auth endpoint including the received request URI and client identifier in the query parameters.

    Sample URL:

    https://{base_url}/auth?request_uri={request_uri}&client_id={client_id}

  2. The user authenticates and provides their consent.

    Once the user provides their consent, they get redirected back to your application -- to the redirect URL configured for your application.

  3. Extract the authorization code from the redirect URL.

Get Token​

Call the Raidiam's OAuth /token endpoint to authenticate your client.

Utilize the client authentication method configured for your client:

curl --location --request POST 'https://{base_url}/token' \
--cert /path/to/your/certificate.pem \
--key /path/to/your/private.key \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'code={code}' \
--data-urlencode 'redirect_uri={redirect_uri}' \
--data-urlencode 'code_verifier={code_verifier}'

Upon successful validation of the request, the authorisation server issues and returns an access token - in a form of a JWT signed using the algorithm configured for your client (Applications > your application > Advanced Configuration > Token Signed Response Algorithm ID).

Call Raidiam's APIs​

Call Raidiam's APIs using the access token you got from the authorisation server.

warning

By default, applications are configured to receive Certificate Bound Access Tokens where information about the certificate used to get the token is included in the token itself and verified by the Raidiam's Resource Server (APIs).

Make sure to utilize the same certificate across all mTLS connections with the authorisation server and Raidiam's APIs.

Sample Postman Collections for Authorization Code Flow​

You can utilize the below Postman Collections to quickly test client authentication for Read/Write Access Tokens:

Import the JSON with collection configuration into Postman and add your Organisation or an Application Transport Certificate to Postman Configuration.

For more information on how to add a certificate in Postman, see the Add and manage CA and Client Certificates in Postman article.

Open Book IconTABLE OF CONTENT