Configure SSO for Okta and OpenID Connect

Overview

Okta SSO makes authentication seamless for your organization’s users. Configure Okta for APEX AIOps Incident Management to allow users to log in without maintaining a separate set of user credentials.

Add the Issuer URL

In the Incident Management UI, go to Settings > Single Sign-On (SSO), and then click Configure in the OpenID Connect (OIDC) box.
Locate the Issuer URL in Okta:
Use the information in this Okta documentation to define the Issuer URL.
If you are using a developer account, you can use these steps to locate the information:
1. In an Admin account in Okta, Navigate to Security > API.
2. On the Settings tab, click the linked name of your authorization server under Name.
3. Copy the issuer URL from the Metadata URI field.
  If your Okta application is using:
  - OIDC
    The URL appears in this format: https://<yourOktaDomain>/oauth2/default/.well-known/openid-configuration
  - OAuth
    The URL appears in this format: https://<yourOktaDomain>/oauth2/default/.well-known/oauth-authorization-server
  NOTE: Okta may change the issuer URL format without notice. Refer to the Okta developer documentation for updated endpoint information if you have questions.
In Incident Management, paste the information in the Issuer URL field.

Add the web application Client ID and Client Secret

In an Admin account in Okta, navigate to Applications > Applications and then click Create App Integration.
For the Sign-in method, select OIDC - OpenID Connect.
For the Application type, select Web Application, and click Next.
In the Incident Management User Interface (UI), copy the Sign-in redirect URL.
Go back to Okta and paste it in the Sign-in Redirect URI field in the new web app page.
In the Assignments section, under Controlled access, select either Limit access to selected groups or Allow everyone in your organization access.
Click Save to create the application.
On the new application page, a Client ID and Client Secret display.
In Okta, copy the Client ID and then paste it in the Incident Management Client ID field on the Single Sign On (SSO) page.
In Okta, copy the Client Secret and then paste it in the Incident Management Client Secret field on the Single Sign On (SSO) page.
In Incident Management, enter the Login Domain on the Single Sign On (SSO) page, and then click Add Domain.
The login domain is the domain users log into via Okta. For a developer Okta instance, it may look like this: dev-73815735.okta.com

Map roles and groups in Okta

In Okta, navigate to Security > API and click the linked name of your authorization server under Name.
Click the Scopes tab and then click Add Scope.
In the Name field, enter a name for the scope, making sure you take note of it.
Under Metadata, select Include in public metadata.
Click Create.
Click the Claims tab and click Add Claim.

Set the following values:

Setting	Value
Name	any name you prefer
Include in token type	Select ID Token Select Always
Value type	Select Expression.
Value	You can reference multiple user values via the `user.$attribute` variable. Use a value similar to `user.department` for the actual value. See Okta Expression Language overview for more information on the Okta User Profile. NOTE: Value depends on the field in the User record you use for mappings. To use Okta groups to map roles in Incident Management, the Value Type must be Groups, and the Filter Type should be Matches regex and value of `.*`
Disable claim	Leave deselected
Include in	Select The following scopes, and include the name of the scope you created earlier.

In Incident Management, click the Configuration tab on the Single Sign On (SSO) page and complete the optional setup sections:
Note
It is a best practice to complete the rest of your SSO configuration first, test your setup, and then add scopes and mappings after you have confirmed SSO is working correctly.
1. Additional Scope
  Enter a space-separated list of scopes that Incident Management can request from the external authentication system. This list must include the scopes the system will use for group mapping and any scopes used for other purposes. For example: preferred_contact location department.
  Incident Management automatically adds openid email profile if these scopes are not provided.
  Important
  After adding additional scopes, click Test at the top of the page to ensure that your SSO configuration still works. If it does not, then there is an issue with your scopes.
2. Role Mappings
  Map each claim value to the corresponding Incident Management role.
  NOTE: You can create custom roles in Incident Management to map to your SSO roles. See Add a custom role for details.
  1. Click Add Role Mapping.
  2. In the Add Role Mapping dialog, enter the Role Claim Key and the Role Claim Value in the indicated fields.
    NOTE: In Okta, the Role Claim Key is the same as the name of the Claim which points to the user fields you want to use for role mapping.
  3. Click Select Role and, from the list that opens, select the Incident Management role to map to the selected Claim Value.
  4. Click Add Mapping.
  Tip
  By default, users with no role are assigned the Admin role. You can select a different default role, and even create a custom role for this purpose.
  Enter the claim key in the Role Claim Key field.
  Enter default for the Role Claim Value.
  Click Select Role and select the role to use as the default from the list.
  When users are added that do not have a role assignment, they will now be assigned this default role.
3. Group Mappings
  Under Group Mappings, map your group claim values to Incident Management groups. To map an SSO group to an Incident Management group, you must first create the target group in Incident Management. For information on creating user groups for SSO, see Add groups to use with SSO.
  1. Click Add Group Mapping.
  2. In the Add User Group Mapping dialog, enter the Group Claim Key, and the Group Claim Value in the indicated fields.
    NOTE: In Okta, the Group Claim Key is the same as the name of the Claim which points to the group information.
  3. Click Select User Group and, from the list that opens, select the Incident Management group to map to the selected Claim Value.
  4. Click Add Mapping.

For more information, see:

Configure SSO to support multiple tenants

If you have multiple Incident Management instances and want to use the same SSO configuration with all of them, you must complete an additional procedure for supporting multiple tenants.

In this section: