Okta

To set up a single sign-on through Okta, go to the Okta Admin Console.

Step 1 : Register the cluster

Under Applications > Applications, select Create App Integration.
Choose OIDC - OpenID Connect as the sign-in method and Web Application as the application type, then select Next.
For the App integration name field, enter a name for your cluster.
Keep the Authorization Code grant type.
For the Sign-in redirect URIs field, enter the callback URL of the cluster : Like https://localhost/neos/Northwind/signin-oidc with HttpSys, or https://localhost:5001/signin-oidc with Kestrel, which serves the cluster from the root of its port.
For the Sign-out redirect URIs field, enter the sign-out callback URL of the cluster : Like https://localhost/neos/Northwind/signout-callback-oidc with HttpSys, or https://localhost:5001/signout-callback-oidc with Kestrel.
Under Assignments, choose who can access the cluster (for example Allow everyone in your organization to access).
Select Save.
Copy the Client ID somewhere, you will need it later.
Copy the Client Secret somewhere, you will need it later.

Note

The redirect URIs are case-sensitive and must exactly match the URL of the cluster (scheme, host, port and path).

Step 2 : Find the domain

The domain of your Okta organization is displayed under your user name, in the top right corner of the Admin Console (for example xxx.okta.com).

Do not use the domain of the Admin Console itself (xxx-admin.okta.com).

Step 3 : Configure the authentication in the cluster configuration

In the cluster configuration file, you will have to fill in the following configuration by replacing the corresponding tags:

Authentication:
  Authority: https://[DOMAIN]
  ClientId: [CLIENT_ID]
  ClientSecret: [CLIENT_SECRET]
  Scopes:
    - email
  UserPropertiesMap:
    Identifier: email
    Email: email
    FirstName: given_name
    LastName: family_name

Replace :

[DOMAIN] by the domain of your Okta organization.
[CLIENT_ID] by the Client ID of the cluster application.
[CLIENT_SECRET] by the Client Secret of the cluster application.

The openid and profile scopes are always requested. The user is identified by their email address (email claim) rather than by the name claim used by default, which holds the full name and is not unique. The email address is also the login of the users in the UserPermissions module when it is synchronized with Okta, even when the Okta login (preferred_username claim) is different.

You can check the authority by opening https://[DOMAIN]/.well-known/openid-configuration: the issuer property must be equal to the Authority.

API calls with access tokens

The configuration above covers the web sign-in. To call the cluster API with an Okta access token (Authorization: Bearer header), the token must be issued by a custom authorization server: the access tokens of the organization authorization server can only be validated by Okta itself.

Under Security > API > Authorization Servers, use the default authorization server or add one dedicated to the cluster, and set its Audience to the Client ID of the cluster application: the cluster only accepts the access tokens issued for its ClientId (aud claim).
In its Access Policies tab, add a policy and a rule allowing the applications that call the API.
Use its Issuer URI as Authority:

Authentication:
  Authority: https://[DOMAIN]/oauth2/default
  ClientId: [CLIENT_ID]
  # ...

To also accept tokens issued for another audience (for example api://default), declare their authorization server in AdditionalJwtAuthorities. The tokens are routed to an additional authority according to their issuer (ValidIssuers or IssuerPattern), never according to their audience: when it is the same authorization server as Authority, all its tokens are validated by the additional authority, so ValidAudiences must contain both the Client ID and the other audience:

Authentication:
  Authority: https://[DOMAIN]/oauth2/default
  ClientId: [CLIENT_ID]
  # ...
  AdditionalJwtAuthorities:
    - Name: OktaApi
      Authority: https://[DOMAIN]/oauth2/default
      ValidIssuers:
        - https://[DOMAIN]/oauth2/default
      ValidAudiences:
        - [CLIENT_ID]
        - api://default

Troubleshooting

The 'redirect_uri' parameter must be a Login redirect URI in the client app settings: the callback URL of the cluster is not one of the Sign-in redirect URIs of the application.
User is not assigned to the client application: the user is not assigned to the application, directly or through a group.
Access has been denied because the policy requirements could not be satisfied by the users' current set of available authenticator enrollments: the authentication policy of the application requires an authenticator the user has not enrolled. Adjust the policy in Applications > [Application] > Sign On > User authentication.

The Reports > System Log page of the Admin Console gives the exact reason of a sign-in failure.

Synchronization of the users

The UserPermissions module can create the users of the cluster in Okta. See User Synchronization.

Table of Contents