Custom OAuth2 Client

CyberArk Identity supports OAuth 2.0, enabling custom client applications access to online resources needed by those applications.

OAuth 2.0 is an open-standard framework and specification for authorizing client applications to access online resources. Authorization works by requiring a client to obtain an access token from a server that in turn grants the client access to specific protected resources. The client then sends the access token to the resource whenever it invokes the resource's endpoints.

This topic covers how to add the custom OAuth2 Client application to the Identity Administration portal and describes the available configuration fields and options.

Use the custom OAuth2 Client application if the resulting access token is used to call CyberArk Identity APIs.

Refer to for more information about using OAuth 2.0.with CyberArk.

PKCE with custom OAuth2 Client applications

The OAuth2 custom application template supports the Proof Key for Code Exchange (PKCE) when configuring public applications, such as mobile apps or single-page apps, where the client secret is not secure. The PKCE OAuth2 flow for public applications requires that you do not use a client secret when configuring the application template. The steps for configuring the PKCE authorization code flow are similar to the regular authentication flow except for the use of code_verifier and code_challenge parameters instead of the client secret in the authorization request. The following details the authorization flow for PKCE configurations:

  • The client application sends an authorization request with the code_challenge to the authorization server.

  • The authorization server acknowledges receiving the code_challenge and sends a code to the client application.

  • The client application sends a token request along with the code and the code_verifier.

  • The authorization server validates the code_verifier with the code_challenge it already received and then issues the access token so the user can log in to the application.

To configure the custom OAuth2 template for a PKCE flow, you need to configure the Client ID type in the Identity Administration portal > Apps > Web App > General Usage page for List (instead of Confidential).

For more information on PKCE, see

To add and configure a custom OAuth 2.0 client

  1. In the Identity Administration portal, select Apps > Web Apps, then click Add Web Apps.

    The Add Web Apps screen appears.

  2. Click Custom.

  3. On the Custom tab, next to the OAuth2 Client application, click Add.

  4. In the Add Web App screen, click Yes to add the application.

    The Identity Administration portal adds the application.

  5. Click Close to exit the Application Catalog.

    The application that you just added opens to the Settings page.

  6. On the Settings page, complete the following fields:

    Field Description

    Application ID

    A unique key used to build the OAuth2 endpoint URL (URL format is either or

    Customize Name and Description for each language

    Not relevant, as this is not an app that will appear in a user's User Portal.

    Application Name

    A descriptive name for the application (not seen by users).

    Application Description

    A description for the application (not seen by users).


    Not relevant, as this is not an app that will appear in a user's User Portal.


    You can optionally provide a logo to identify your app.

  7. On the General Usage page, complete the following fields to specify the types of credentials that can be used to authorize with this server:

    Client ID Type: choose one of these options:

    Option Description


    Allows for authorization in any client where authorization is granted by the user (for example, in a popup screen). Select this setting when using the Authorization Code flow.


    Specifies a list of clients who are allowed access. Click Add and then enter the application name of your client. Select this option if you are configuring public applications, such as mobile or single-page applications, where the client secret is not secure (for PKCE OAuth2 flows). It can also be used when the application uses the Authorization Code flow.


    Requires an OAuth2 client to send a client ID and a client secret. Selecting Confidential is recommended for all flows in which the user provides their username and password and the client sends a client ID and a client secret.


    The URL of the server issuing access tokens. Can be left as default.

    Allowed Redirects

    Specifies the redirects that should be trusted when redirection occurs during the Authorization Code and Implicit flows. Not applicable for the Client Credential and Resource Owner flows.

  8. On the Tokens page, complete the following fields:

    Field Description

    Token Type

    Specifies the type of token to issue (JwtRS256 or opaque).

    JwtRS256 is a JSON Web Token (JWT) composed of Base64 encoded user and claim information. An opaque token contains no information about the user. To obtain user and claim information for an opaque token an introspection URL must be used by passing the token. The format of the introspection URL is either or

    Auth Methods

    Specifies the authentication flow(s) for which the specified token type should be issued.

    Token Lifespan

    Specifies the token’s lifespan.

    Set Token Lifespan to more than 10 minutes. If the Token Lifespan is less than or equal to 10 minutes, some APIs might not work as desired.

    Issue refresh tokens

    When enabled, allows clients to request a refresh token that can be exchanged for a new access token. Not applicable for the Resource Owner or Client Credentials flows.

  9. On the Scope page, add any desired scopes and select from the following options:

    Scope Description
    User must confirm authorization request

    Select this option if you want to the user to confirm the authorization request before receiving a token.

    Allow scope selection

    Select this to give users the option of choosing from the scopes that you added.

    The scopes are categorized into the following two types:

    Scope Description

    API scope

    Used to define the scopes to access APIs.

    Custom claims scope

    Used to define the scopes to retrieve custom claims which are part of ID Token.

    You can use a regular expression (regex) to define scopes. To add a scope for all APIs, enter .* as the REST Regex value. For example, use /UserMgmt/.* to match the User Management APIs only.

  10. On the Permissions page, select the role(s) that the user must be in, in order to authorize against the server.

  11. (Optional) On the Changelog page, you can see recent changes that have been made to the application settings, by date, user, and the type of change that was made.

  12. Click Save.