How do I acquire an access token for Identity Cloud API calls in a Scripted Decision node?

Overview

This article demonstrates how you can acquire an access token for subsequent API calls in a Scripted Decision node using a service account. This is a simple example that just provides success and error outcomes to prove it works; you would need to incorporate this logic into your own journeys and extend the script as needed.

The example script in this article utilizes the fr:idm:* scope for access to /openidm/* API endpoints. If you want to get an access token for other API endpoints, you will need to ensure your service account is set up for the appropriate scopes and change the scope referenced in the script to match. See Service account scopes for further information.

Service accounts are only for use with Identity Cloud API endpoints; if you want to communicate with a third-party API, you will need to use a standard OAuth 2.0/OIDC client credential flow.

Steps involved:

1. Create a script to acquire an access token
2. Create a simple journey to acquire an access token
3. Test the journey

Prerequisites

• You have a working Identity Cloud tenant.
• You have a service account set up that allows you to obtain an access token using the JWT profile authorization grant. See Get an access token for further information. In particular, ensure you have completed steps 1 to 3.

For the purposes of this example, you should choose the fr:idm:* scope when creating your service account.

• You have created the following ESVs:

If you use different ESV names, you will need to update the script accordingly.

Creating a script to acquire an access token

A sample script is provided to get you started. You can use this script as is (with the updated variables) to prove you can get an access token and then update it as needed to make it suitable for your use cases.

1. Download the attached script: getAccessToken.js (8 kB)
2. Check the variables defined in the script and update as required:var nodeConfig = {  nodeName: "GetAccessTokenDemo",   tenantFqdnEsv: "esv.tenant.env.fqdn",   accountIdEsv: "esv.service.account.id",   privateKeyEsv: "esv.service.account.privatekey",   accessTokenStateField: "idmAccessToken",   maxAttempts: 3,   scope: "fr:idm:*",   serviceAccountClientId: "service-account",   jwtValiditySeconds: 10, };The key ones to check are:

• nodeName - the name of your journey for debug purposes.
• tenantFqdnEsv - the name of the ESV variable used for the tenant FQDN.
• accountIdEsv - the name of the ESV secret used for the ID of the service account.
• privateKeyEsv - the name of the ESV secret used for the private key of the service account.
• scope - the scope you chose when you set up your service account; this determines which API endpoints you can get an access token for.

Creating a simple journey to acquire an access token

1. In the Identity Cloud admin UI, go to Journeys and click New Journey.
2. Enter a name for your journey, select which identities will authenticate using this journey, and click Save.
3. Create a journey similar to the following:

Where:

• Get Access Token node is a Scripted Decision node containing the script you created in the previous section with two outcomes: success and error. 
• Success Message node is a Message node that demonstrates a successful outcome. This node is set to display the message: "Access Token successfully acquired".
• Error Message node is a Message node that demonstrates an unsuccessful outcome. This node is set to display the message: "Access Token acquisition failed".

Testing the journey

1. In the Identity Cloud admin UI, navigate to Journeys.
2. Click the journey that you want to test.
3. Copy the Preview URL.
4. Paste the preview URL into a browser using Incognito or Browsing mode.

The journey will execute the script and acquire an access token using the service account and ESVs you set up. If this is successful, you will see the following message displayed:

The Yes and No buttons shown here are just default outcomes for a Message node and because they are not relevant to this example, they don't do anything further.

If unsuccessful, you will see the message you set in the error outcome instead ("Access Token acquisition failed") and you will need to troubleshoot the journey to determine what failed. 

Debug step (Development environment only)

If you want to view the actual token created during testing, you can enable debug mode in your development environment and select Enable Debug Popup. When you test the journey as above, you will get a popup (provided you are not blocking them in your browser) with the access token, for example:

If you are using a staging or production environment, debug mode is not available and you will need to include a Scripted Decision node for debugging as explained in FAQ: Journeys in Identity Cloud (How do I debug an end user journey?)

Troubleshooting

If your journey does not successfully acquire an access token, you should:

• Check you have a working service account that can get an access token successfully outside of this journey.
  • If you chose a scope other than fr:idm:*  when you set your service account up, ensure you have changed the scope in the script.
• Check you have set the ESVs up correctly as outlined in the Prerequisites section.
  • If you used different names for your ESVs than the ones indicated in the Prerequisites, ensure you have changed them in the script.
• Debug the journey. The example script does include some error handling. See FAQ: Journeys in Identity Cloud (How do I debug an end user journey?) for further information.

See Also

Service accounts

Introduction to ESVs

Authenticate to Identity Cloud REST API with access token

Debug Identity Cloud end-user journeys

Journeys