Authorization Code Flow: Obtain Access Token
Authorize and authenticate client applications using the OAuth Authorization Code Flow. Get access tokens for Connect API access.
Raidiam recommends reading the Obtaining Access Tokens article first to learn about used specifications, all available access scopes and what they enable, and more.
For a Sample Postman collection, see the Sample Postman Collections for Authorization Code Flow section.
- Active and valid Application (Software Statement) with the scope directory:website granted If not yet added, Add Application. Make sure your organisation has a Role assigned that enables the organisation resources to request the directory:website scope and add this role to the application.
- Active Transport Certificate If not yet added, request Transport 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, request Signing Certificate for organisation.
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 Server 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 -- for clients authenticating themselves using the private_key_jwt method: "token_endpoint": "https://auth.sandbox.raidiam.io/token"
- mTLS Endpoint Aliases - for clients authenticating themselves using the tls_client_auth method:
Download Transport Certificate for your organisation 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.
If you are using cURLs to test the integration, you can disable checking the server's certificate using the -k flag or --insecure option.
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.
To sign the JWT, utilize JSON Web Signature (JWS RFC7515) and a signing key added within your organisation.
Push the contents of the authorization request to the Raidiam's Pushed Authorization Request (PAR) /requests endpoint.
Pushed Authorization Requests, defined by the RFC9126 specification, 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.
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 Connect, 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
As a response to your request, you receive a request_uri you can use in the subsequent call to the authorization endpoint.
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}
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.
Extract the authorization code from the redirect URL.
Call the Raidiam's OAuth /token endpoint to authenticate your client.
Utilize the client authentication method configured for your client:
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 the Connect API using the access token you got from the authorisation server.
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.
You can utilize the below Postman Collections to quickly test client authentication for Read/Write Access Tokens:
- With PAR, PKCE, mTLS-client authentication, and when Signed Request Objects are required
- When Signed Request Objects are not required
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.