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:
-
In the Identity Administration portal, select Apps > Web Apps, then click Add Web Apps.
The Add Web Apps screen appears.
-
Click Custom.
- 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.
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.
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.
-
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. -
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.
-
The OpenID Connect scopes are categorized into the following two types:
Scope Description 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 CyberArk Identity from an IP address that is outside of your corporate IP range.
For more information on defining the filters and conditions, see Create authentication rules.
- 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.
-
Click Save.
If you have more than one authentication rule, you can prioritize them on the Policy page. You can also include JavaScript code to identify specific circumstances when you want to block an application or you want to require additional authentication methods. For details, see Application access policies with JavaScript.
If you left the Apps section of the Identity Administration portal to specify additional authentication control, you will need to return to the Apps section before continuing by clicking Apps at the top of the page in the Identity Administration portal.
-
-
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.
-
-
(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 ).
