Configuring single sign-on with Okta

Okta can be configured as the authentication provider for the system.

Note: To configure single sign-on with Okta, you must upgrade the system to 8.5.3 or later release.

Note: Ensure that the prerequisite tasks are completed on the system before you configure single sign-on. For more information, see the Prerequisites section in Configuring single sign-on.

Prerequisites

The following prerequisite steps on Okta must be completed before you can configure single sign-on on the system:

Create a subscription for Okta. A free trial subscription is also available. For more information, see Okta . During subscription creation, you specify a tenant that is used to create a URL to access the Okta dashboard.
Access the Okta administrator dashboard by entering the following URL in a web browser:
```
https://tenant.okta.com/admin/dashboard
```
Where tenant is the name of the tenant that you specified when you created your subscription. Usually this tenant name is associated with your company or organization.
In the Okta interface, from the menu select Applications > Applications > Create App Integration.

For the Sign-in method, select OIDC – OpenID Connect. For the Application type, select Web Application. Click Next.

Note: Each system must be added as a separate application.

The following table shows the required fields and actions for the General Settings page in the Okta interface

Table 1. General settings on the app integration page
Field	Action
App integration name	Enter a name to identify the system on Okta. If you are adding multiple systems, enter a unique.
Grant type	Ensure Authorization Code is selected.
Sign-in redirect URIs	Multiple redirect URIs can be specified for the management GUI. The redirect URI is consisted of the management IP address or hostname followed by `/sso`. For example, https://hostname.com/sso.

The following table shows the required fields and actions for the Assignments page in the Okta interface.

Table 2. Assignments settings on the app integration page
Field	Action
Controlled access	Select which users or groups can access the app. If you are unsure, select Allow everyone .
Enable immediate access	Ensure Enable immediate access with Federation Broker Mode is disabled

Click Save. After the system is saved as a new app integration, the application reloads with the General page selected.

On the General page, copy the Client ID. This value must be specified as the Client ID on the Single sign-on page in the management GUI.
On the General page, ensure Client authentication is set to Client secret.
On the General page, ensure Proof Key for Code Exchange (PKCE) is disabled. The system does not support PKCE.
On the General page, copy the Client Secret or create a new one. This value must be specified as the Client ID on the Single sign-on page in the management GUI.
Ensure the authentication provider is configured to send back the group claim in the ID Token sent to the system. The group claim identifies which groups the authenticating user belongs to. Some authentication providers do not send the group claim by default, so this typically requires some configuration on the authentication provider. From the menu, select Security > API > Authorization Servers. Edit the default authorization server. Under the Claims tab, edit the claim type ID. Add a new claim called groups with Include in token type set to ID Token / Always, a Value type of Groups, a Filter of Matches regex with value .* and an Include in of Any scope.
Click Save.

Using the management GUI

To configure single sign-on with Okta, complete these steps:

Select Settings > Security > Single Sign-on.
2. Enter the OpenID Configuration Endpoint URL of the authentication server. For Okta, enter the following:
```
https://tenant.okta.com/oauth2/default/.well-known/openid-configuration
```
where tenant is the hostname of the tenant.
For the OpenID Credentials, add the Client ID and Client Secret that you copied on from the Overview page in the Okta interface.
For the User claim, the value to enter depends on how your authentication provider is configured. The User claim must match the name that the authentication service uses to specify the username attribute in the ID Token it sends to the system. Typically this value is preferred_username, but can be customized on the authentication provider.
For the Group claim, the value to enter depends on how your authentication provider is configured. The Group claim must match the name that the authentication service uses to specify the group attribute in the ID Token it sends to the system. Typically this value is groups, but can be customized on the authentication provider.
For Proxy server, consider how the system accesses the authentication provider. For an authentication provider within your network, a proxy server usually is not needed. If you connect to the authentication provider through the internet, check the box and ensure a proxy server is defined on the system.
Click Save. On the confirmation page, click Confirm to enable single sign-on for the system.

Single sign-on is enabled for the system. You can configure user groups to use single sign-on. Click Navigate to launch the User Groups page.

Using the command line interface

To enable single sign-on, enter the following command:

chauthsinglesignon -oidcconfigurationendpoint https://tenant.okta.com/oauth2/default/.well-known/openid-configuration-clientid xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -clientsecret xxxxxxxx -userclaim preferred_username -groupclaim groups -enable

In the example, tenant is the tenant name that is associated with your subscription. The values for the -clientid and the -clientsecret are the Open ID Client and Open ID Secret that are automatically generated when you created your system as an app integration in Okta can be obtained from the General page in the Okta. The values for the -userclaim and the -groupclaim should match the name of the claims configured for the ID Token on the authentication provider.