Add and configure the custom OpenID Connect application

This topic covers how to add the custom OpenID Connect application to the Identity Administration portal and configure trust. For information on OpenID connect, see Use OpenID Connect.

To add and configure a generic OpenID Connect application:

  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 OpenID Connect application, click Add.
  4. In the Add Web Apps screen, click Yes to add the application.
  5. Click Close to exit the Application Catalog.

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

  6. Enter the application ID.

    The application ID is used by the client application to send authorization and token requests to the custom application. The application ID identifies the custom application uniquely to make the API requests.

    The app key is used to integrate the custom application with widgets and client applications.
  7. Update the name, description, category, and logo fields as needed.

    Because this is a custom application, CyberArk recommends giving this application a unique name. You can also provide a custom application logo.

    The Category field specifies the default grouping for the application in the user portal. Users have the option to create a tag that overrides the default grouping in the user portal.

    You can customize the name and description for each supported language.

  8. (Optional) Click On enrolled mobile devices, open this application in the built-in browser (required for Derived Credential login) to authenticate with this application.

    See CyberArk-issued derived credentials for more information.

  9. Configure fields on the Trust page.

    For the following, copy the content from the application website to the Trust page.

    Option

    Description

    Resource application URL

    Enter the URL of your OpenID Connect application.

    This field is visible when you select one of the following options under Service Provider Configuration section:

    Login initiated by the app only - Enable this option only for an RP-initiated login where the relying party sends a login request to the authorization server.

    Login initiated by CyberArk Identity or the app - Enable this option for an OP-initiated login where the open ID provider authenticates the user and redirects to the resource URL.

    You can select or deselect the Show in user app list option to enable or restrict the user to launch the application in User Portal.

    Authorized Redirect URIs

    Enter all desired redirect URIs registered with CyberArk Identity. At least one redirect URI is required. The user is redirected to this URI on successful authentication and authorization.

    Enable full URI match

    Select to enable exact string matching when validating the redirect URI for authorization.

    The default is selected for new apps.

    Open ID Client Secret

    Enter the Client Secret established between CyberArk Identity and the application.

    Authorized Post Logout URIs

    Enter the Post Logout Redirect URIs. The user is navigated to this URI post logout from CyberArk Identity.

    For the following, copy the content from the Trust page to the application website.

    Option

    Description

    OpenID Connect Client ID

    Copy the Client ID and paste it into the appropriate field on the application website.

    OpenID Connect Metadata URL

    Copy the metadata URL and paste it into the appropriate field on the application website.

    OpenID Connect Issuer URL

    A URL unique to this application profile. This value is the entity ID used in the assertion to identify the identity provider attempting to authenticate. The web application doesn’t contact this URL so it doesn’t need to be functional.

  10. On the Tokens page, set the token lifetime for ID tokens, access tokens, and refresh tokens (if you choose to issue refresh tokens).

    The default ID and access token lifetime is five hours.

    If you issue refresh tokens, the default lifetime for a refresh token is 365 days. Refresh tokens are exchanged for new access tokens, allowing your application to have a valid access token without additional user interaction.

    For existing custom OpenID Connect applications, select the Generate access and ID tokens with new structure (recommended) checkbox to exclude claim information from the access token, and scope information from the ID token. The new access and ID token structure is based on the OIDC standards. For more information, see OpenID specifications. For a detailed description of the old and new structure for the access and ID tokens, see Overview of OpenID Connect tokens.
  11. On the Scope page, add any desired scopes and select from the following options:

    Scope Description

    Prompt the user for consent to authorization request

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

    Allow scope selection

    Select this option to allow users to choose the scopes on the consent pop-up and give consent to the selected scopes.

    Validate scopes received at the authorization server

    Select this option to validate scopes received at the authorization server. This option is available for existing apps which enables you to validate scopes sent by the OIDC client based on a set of authorized scopes added in the Identity Administration portal.

    For example, when the OIDC client sends a scope called 'transaction', you must it to the authorized scope list to successfully validate the authorization request.

  12. The OpenID Connect 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 that are part of the ID token.

    Click Add under Scope Definitions to add an API scope or a custom claims scope. 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.

  13. On the Account Mapping page, configure how the login information is mapped to the application’s user accounts.

    The options are as follows:

    Option Description

    Use the following Directory Service field to supply the user name

    Use this option if the user accounts are based on user attributes. For example, specify an Active Directory field such as mail or userPrincipalName or a similar field from the CyberArk Cloud Directory.

    Everybody shares a single user name

    Use this option if you want to share access to an account but not share the user name and password. For example, some people share an application developer account.

    Use Account Mapping Script

    You can customize the user account mapping here by supplying a custom JavaScript script. For example, you could use the following line as a script:

    LoginUser.Username = LoginUser.Get('mail')+'.ad';

    The above script instructs CyberArk Identity to set the login user name to the user’s mail attribute value in Active Directory and add ‘.ad’ to the end. So, if the user’s mail attribute value is Adele.Darwin@acme.com then CyberArk Identity uses Adele.Darwin@acme.com.ad. For more information about writing a script to map user accounts, see the SAML application scripting.

  14. (Optional) Click App Gateway to allow users to securely access this application outside of your corporate network.

    For detailed configuration instructions, see Configure an application to use App Gateway.

  15. (Optional) Click Workflow to set up a request and approval work flow for this application.

    See Manage application access requests for more information.

  16. (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.
  17. Click Save.

Next, you’re ready to edit the Advanced Script (see Customize the OpenID Connect Custom Logic script ).