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 the About OpenID Connect topic in the Developer Documentation.
To add and configure a generic OpenID Connect application:
In the Identity Administration portal, select Apps > Web Apps, then click Add Web Apps.
The Add Web Apps screen appears.
- On the Custom tab, next to the OpenID Connect application, click Add.
- In the Add Web Apps screen, click Yes to add the application.
Click Close to exit the Application Catalog.
The application that you just added opens to the Settings page.
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.
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.
(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.
Configure fields on the Trust page.
For the following, copy the content from the application website to the Trust page.
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.
Open ID Client Secret
Enter the Client Secret established between CyberArk Identity and the application.
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.
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.
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 OpenID Connect tokens.
On the Scope page, add any desired scopes and select from the following options:
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.
The OpenID Connect scopes are categorized into the following two types:
Used to define the scopes to access APIs.
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.
Deploy the application by setting permissions on the application.
On the Permissions page, click Add.
Select the user(s), group(s), or role(s) that you want to grant permissions to, then click Add.
The added object appears on the Permissions page with View, Run, and Automatically Deploy permissions selected by default.
Select the permissions you want and click Save.
Default permissions automatically deploy the application to the User Portal if the Show in user app list option is selected on the Settings page. Do not select this option if you intend to use only SP-initiated SSO.
Change the permissions if you want to add additional control or if you prefer not to automatically deploy the application.
(Optional) On the Policy page, specify additional authentication controls for this application.
Click Add Rule.
The Authentication Rule window displays.
- Click Add Filter on the Authentication Rule window.
Define the filter and condition using the drop-down boxes.
For example, you can create a rule that requires a specific authentication method when users access the CyberArk Identity from an IP address that is outside of your corporate IP range. Supported filters are:
Filter Description Conditions available Identity Cookie
The cookie that is embedded in the current browser by CyberArk Identity after the user has successfully logged in.
- Is present
- Is not present
The operating system of the device a user is logging in from.
- equal to
- not equal to
The browser used for opening the CyberArk Identity portal.
- equal to
- not equal to
CyberArk Identity roles that a user belongs to. If a user belongs to multiple roles, the authentication rule that comes first (highest priority on top) is honored.
If a role is renamed following the creation of an authentication rule using Role as a filter, the authentication rule will automatically update with the new role name. If a role is deleted, the portion of the any authentication rule using that role as a filter will also be deleted.
This filter is only applicable to managing web application access.Contact support if Role does not display in your menu. This filter requires tenant configuration.
- equal to
- not equal to
The country based on the IP address of the user computer.
- equal to
- not equal to
Risk Level: The authentication factor is the risk level of the user logging on to the User Portal. For example, a user attempting to log in to CyberArk Identity from an unfamiliar location can be prompted to enter a password and text message (SMS) confirmation code because the external firewall condition correlates with a medium risk level. This Risk Level filter requires additional licenses. If you do not see this filter, contact CyberArk support. The supported risk levels are:
Additional licenses might be required to enable this feature. Contact your CyberArk account representative for more information.
- Non Detected -- No unexpected activities are detected.
- Low -- Some aspects of the requested identity activity are unexpected. Remediation action or simple warning notification can be raised depending on the policy setup.
- Medium -- Many aspects of the requested identity activity are unexpected. Remediation action or simple warning notification can be raised depending on the policy setup.
- High -- Strong indicators that the requested identity activity is an anomaly and the user's identity has been compromised. Immediate remediation action, such as MFA, should be enforced.
- Undetermined -- Not enough user behavior activities (frequency of system use by the user and length of time user has been in the system) have been collected.
The following video illustrates how to create an authentication rule based on risk level.
- equal to
- not equal to
Your device is considered managed under the following circumstances:
It is enrolled to CyberArk Identity for device management.
A device that is enrolled for only single sign-on or endpoint authentication is not considered a managed device. For more information about the difference, see Mobile Device Management or single sign-on only.
It is enrolled to a supported Unified Endpoint Manager (UEM).
It is compliant with policies defined by a UEM. Compliance means that a UEM is enrolled and conforms to compliance rules defined by a third-party.
For more information, see Configure access based on a third-party UEM trust.
- enrolled to
- not enrolled to
- compliant with
- not compliant with
Whether you use a digital certificate issued by your organization’s trusted certificate authority. You can upload a certificate using the Identity Administration portal > Settings > Authentication > Certificate Authorities. Users can also individually use CyberArk as their trusted certificate authority and automatically install the digital certificate by enrolling their devices.
For example, if you configure an authentication rule to use the Certificate Authentication condition, then CyberArk Identity checks for a digital certificate issued by a trusted certificate authority and enforces the specified authentication profile before allowing access to this application.CyberArk support must enable the Certificate Authentication filter for your company.
- is used
- is not used
- Click the Add button associated with the filter and condition.
Select the profile you want applied if all filters/conditions are met in the Authentication Profile drop-down.
The authentication profile is where you define the authentication methods. If you have not created the necessary authentication profile, select the Add New Profile option. See Create authentication profiles.
- Click OK.
(Optional) In the Default Profile (used if no conditions matched) drop-down, you can select a default profile to be applied if a user does not match any of the configured conditions.
If you have no authentication rules configured and you select Not Allowed in the Default Profile dropdown, users will not be able to log in to the service.
On the Account Mapping page, configure how the login information is mapped to the application’s user accounts.
The options are as follows:
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
LoginUser.Username = LoginUser.Get('mail')+'.ad';
The above script instructs the 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 the CyberArk Identity uses Adele.Darwin@acme.com.ad. For more information about writing a script to map user accounts, see the SAML application scripting.
(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 the App Gateway.The App Gateway feature is a premium feature and is available only in the CyberArk Identity App+ Edition. Please contact your CyberArk representative to have the feature enabled for your account.
(Optional) Click Workflow to set up a request and approval work flow for this application.
See Manage application access requests for more information.
- (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.
- Click Save.
Next, you’re ready to edit the Advanced Script (see Customize the OpenID Connect Custom Logic script ).