Configuring Clients for ADSP API access

Although most of the keycloak configuration is done when a tenant is set up, you will still need to create new clients for you applications. Clients are used to obtain access tokens for authentication and authorization, and the ADSP API requires that your client is authorized to access its resources. To configure your clients, log in to ADSP’s Tenant Admin Webapp and select the access service tab:

Then click on the Keycloak admin portal link, which will bring you to the Keycloak admin page:

Now, create a new client in Keycloak, giving it an appropriate name for your application. Be sure to give your client a confidential access type, and enable service accounts:

when service accounts are enabled you will see a new tab on the client page - Service Account Roles:

Service accounts provide programmatic access to Keycloak’s APIs. In particular, the service account for the client is used when your applications logs in to keycloak and requests an access token. Based on the roles configured in the account, the token will grant access (or not) to the requested resources when you call an ADSP Service API.

As an example, suppose you want to use ADSP’s PDF Service. You will need to give your new client the pdf-generator role as follows. Click on the Service Account Roles tab and select the urn:ads:platform:pdf-service client:

In this example, there is only one role for the service, the pdf-generator. Other services may have more than one role needed to access all of its resources. Click on the role, then Add Selected, and your client will now be able to effectively make use of the PDF Service.

Fetching access tokens

Once you have a client set up you can us it to obtain the access tokens you need to call the ADSP API’s. You will need:

• the client ID,
• the client secret, and
• the realm (or tenant) ID

You can grab an access token as follows:

const accessUrl = `https://access.alberta.ca/auth/realms/${realmID}/protocol/openid-connect/token`;
const response = await fetch(accessUrl, {
  method: 'POST',
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: clientId,
    client_secret: clientSecret,
  }),
});

const { access_token, expires_in } = await response.json();

Access tokens returned by the fetch are valid for about 5 minutes and can be used in API calls until they expire. You can, however, refresh them if needed, or just grab new ones.