Authentication with Okta

Okta is a standards-compliant OAuth 2.0 authorization server and a certified OpenID Connect provider.

FintechOS built-in integration with Okta enables users to log in to the Digital Experience Portal using the Okta single-sign on (SSO).

How to Set up the Okta Authentication

To set up the Okta authentication for your Experience Portal, follow these steps:

Step 1. Create and configure the Okta app

  1. Using an Okta admin account, log into Okta and create an Okta application (Application tab > Web > OpenID Connect).
  2. From the Applications tab > General > Login, set up the FintechOS callbacks by configuring both the login and the logout redirect URLs, as follows:
    3. login redirect uri {$portalRoot}/Account/LogonCallback
    logout redirect uri {$portalRoot}/Unauthorized
  3. From the API tab > Authorization Servers, create an authorization server for the Okta application.
  4. Expose the Okta roles in custom claims consumable by FintechOS. To do so, synchronize the user groups created in Okta with FintechOS by creating a custom claim named ftos-role mapped to the group metadata in Okta. For more information on how to create a custom claim in the Okta app, see Okta Documentation.

When a user is authorized with Okta, a corresponding system user will be created in FintechOS . In the web.config file you can configure default roles for this user, organization, business unit and user type.

Step 2. Configure the Experience Portal

Prerequisite:

Make sure that you know the following values:

  • Client ID (from the Okta app, General tab)
  • Client Secret (from the Okta app, General tab)
  • Discovery Endpoint (from the Okta app, API section > Authorization Servers > Metadata URL)

In the web.config file, go to the <appSettings> section and add the configuration of your Okta appplication:

Copy 
<!-- 1. Set Okta authentication-->
<add key="EBSDefaultAuthentication" value="Okta" />
             
<!-- 2. Replace these values with your Okta configuration: -->
<add key="openid-client-id" value="{ClientId}" />
<add key="openid-client-secret" value="{ClientSecret}" />
<add key="openid-callback-url" value="http://${portalRoot}/Account/LogonCallback" />
<add key="openid-discovery-endpoint" value="https://${oktaApplication}.okta.com/oauth2/${authServerId}/.well-known/oauth-authorization-server" />
                         
<!-- 3. Map user settings: -->
<add key="openid-auto-user-roles" value="Guest,Developer,Registered Users" />
<add key="openid-auto-user-organization" value="ebs" />
<add key="openid-auto-user-businessunit" value="root" />
<add key="openid-auto-user-type" value="Back Office" />
             
<add key="openid-auto-user-remote-roles-add" value="0|1"/>
<add key="openid-auto-user-remote-roles-sync" value="0|1"/> 

The table below describes the Okta app configuration keys:

Key Description
${portalRoot} The root URL of the Experience Portal.
${authServerId} The ID of the authorization server associated with the Okta application (default value is default).
${oktaApplication} The ID of the Okta application.
Key Description

The table below describes the user mapping configuration keys.

Parameter Value
openid-auto-user-roles The platform role names, separated by colon. These roles will be added automatically when the Okta user is mapped to a platform user.
openid-auto-user-organization The platform organization name. The mapped user will be added in this organization.
openid-auto-user-businessunit The platform business unit name. The mapped user will be added in this business unit.
openid-auto-user-remote-roles-add If set to 1, the roles from the Okta app will be added to the mapped user.
openid-auto-user-remote-roles-sync If value is 1, the roles from Okta and the default roles are always synchronized at login. Any roles manually added to a Okta user are lost.

How it Works

The diagram below describes the FintechOS login flow when using Okta authentication.

Group mapping in FintechOS

When a user is authorized with Okta, a corresponding system user is created in FintechOS. In web.config file of the FintechOS instance, default roles for this user, organization, business unit and user type are added.

Create a custom claim named ftos-role mapped to the group metadata in Okta. This configuration is done for the authorization server associated with the Okta application.

How users log in the Portal

When accessing the Digital Experience Portal URL, users will be redirected to the URL of the authorization server associated with the Okta app. The Okta login page appears.

Once they provide Okta account credentials, they will be logged into the Digital Experience Portal.

When new users are created, they will receive an email notification from Okta which contains instructions and Okta credentials.