Configure API scopes

This topic explains how to add scopes for CyberArk Identity APIs and then generate access tokens using these scopes.

The scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account.

Scopes specify which access privileges are being requested for access tokens. The scopes associated with access tokens determine which resources will be available when they are used to access OAuth 2.0-protected endpoints. Protected resource endpoints may perform different actions and return information based on the scope values and other parameters when requesting the presented access token.

Add scopes and generate access tokens for CyberArk Identity APIs

You can add scopes for CyberArk Identity APIs, and generate access tokens using these scopes to access the corresponding APIs.

To request an access token for CyberArk Identity APIs, add a list of authorized scopes on the Admin Portal:

Once the scopes are added, the client application can send an authorization request as shown below:

POST {{tenant_url}}/oauth2/authorize/{{application_id}}?debug={{debug}}&scope=ReadUserProfile&response_type={{response_type}}&redirect_uri={{redirect_uri}}&client_id={{client_id}}&client_secret={{client_secret}}&nonce=abc

The access token generated is as shown below:

{

"auth_time": 1661784509,

"iss": "{tenant_url}/{application_id}/",

"iat": 1661784889,

"aud": "{client_id}",

"unique_name": "monika.a",

"exp": 1661802889,

"sub": "{user_uuid}",

"nonce": "abc",

"scope": "ReadUserProfile openid"

}

Generate access tokens for custom applications

You can also generate access tokens for custom apps, and then the client application can access the APIs of the custom apps on behalf of the user using the access tokens. In this scenario, the custom app acts as the resource server and CyberArk Identity acts as the authorization server.

For example:

Consider a company called Bank, which is a net banking company. It has a partnership with a tax e-filing company called Tax eFile. Bank uses CyberArk Identity as its identity provider and authorization server. A user of Acme tries to log in to Tax eFile.

The flow would be as below:

  1. The admin of the bank defines the set of authorized scopes on the Open ID Connect app on the Admin Portal as shown below:

  1. The bank shares the metadata URL of the Open ID Connect app with Tax eFile.

  2. Tax eFile sends the authorization and token request to CyberArk Identity.

  3. CyberArk Identity authenticates the user and sends the access token to Tax eFile with the corresponding scopes.

  4. Tax eFile exchanges this token with the bank.

  5. The bank validates this token and, in return, gives the access to the required APIs.