API scopes

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

Scopes specify what access privileges are being requested for Access Tokens. The scopes associated with access tokens determine what 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.

Scopes for CyberArk Identity APIs

Scopes can be added for CyberArk Identity APIs, and access tokens can be generated 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 the authorization request as 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 will be as 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"
}

Scopes for custom applications

Access tokens can also be generated for custom apps, and 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 uses tries to log in to tax eFile

The flow would be as below:

The admin of the bank has to define the set of authorized scopes on the Open ID Connect app on the admin portal as below:

The bank then shares the metadata URL of the Open ID Connect app with Tax eFile. Tax eFile sends the authorization & token request to CyberArk Identity. CyberArk Identity authenticates the user and sends the access token to Tax eFile with the corresponding scopes.

Tax eFile then exchanges this token with the bank. Bank validates this token and, in return, gives the access to the required APIs.