Authentication with OIDC

In this section, we will cover how to integrate Textkernel's TK Portal with well-known Identity Providers using the OIDC protocol, in order to establish a trust relationship and allow users to access Textkernel products with the same credentials that they already use in their organization.

Definitions

• OpenID provider: is the authorization server that issues the ID token, generally an Identity Provider (IdP), e.g. Keycloak, Okta, Salesforce, etc.

• Relying party: is the client application that requests the ID token from the IdP. In our case, Textkernel is the relying party.

• Claim: is a piece of information about the end-user, i.e. the user that wants to access the TK Portal. In OIDC, claims are communicated encoded in a JSON Web Token (JWT).

Requirements

The customer must:

• Use an OIDC compatible Identity Provider (e.g. Keycloak, Salesforce, Okta, Google, etc).
• Be able to add custom claim rules.
• Provide the metadata data of their Identity Provider, either in a file or using a URL.
• Allow the Textkernel OIDC provider access to the handlers of the customer's Identity Provider, including through a firewall.

If these conditions can be met, any Identity Provider supporting OIDC can be used by the customer.

TK Portal OIDC Claims

Here is the complete list of claims to be implemented:

• Required claims are marked with an asterisk *. The rest are Optional.

Claim	Type	Description
preferred_username*	String	Unique ID for the user supplied by the identifying system, this may be a UserID, EMail Address, username, etc. This will be used in Portal as the ID and External ID for the user
email*	String	Required for Saved Searches and Email Alerts functionality
name	String	Can be used to display a user friendly user name, e.g. in the case a UUID or other non human-readable string is used as subject
given_name	String	Used to construct a display name if no name was given
family_name	String	Used to construct a display name if no name was given
tkproles	List of strings	A comma or semicolon separated list of TKPortal role names. This attribute can be used to pass a list of Portal Roles. Invalid portal roles will be ignored. Please make sure the portal roles themselves contain no commas or semicolons. If an active role is provided and it is not among these roles, the active role parameter will be ignored and the active role will be set to the first role in the list
tkpsearchPolicies	List of strings	This attribute can be used to pass a list of Search Policies. A comma or semicolon separated list of TKPortal SearchPolicy names. A list of available values can be provided by a Textkernel Technical Consultant. On every login, the policies passed will overwrite the Search Policies that have been previously set. If the attribute is not provided in the JWT request, the user's search policies remain unchanged. If the attribute is provided in the request, but left empty, all Search Policies of the user will be removed. If default policies are defined for the account and the user logs in for the first time, the default policies will be assigned to the newly created user. Please make sure to follow the naming conventions
tkpactiverole	String	The active TKPortal role of a user in a multi role setup; a list of available values can be provided by a TK technical consultant. If tkpactiverole is provided in the JWT and the content is valid, the active role of the user will be set to the attribute value. In case the active role is not in the portal roles of the user, the active role will be added to the portal roles of the user
tkplang	String	The interface language of TK Portal in a multilingual setup. A list of available values can be provided by a Textkernel Technical Consultant

Setting up the Identity Provider

In this section, we provide some instructions on how to configure several popular and widely used Identity Providers to work with TK Portal. Other Identity Providers that support OIDC can be used as well, and the instructions should be similar.

The IdPs covered are:

• Salesforce
• Okta

OIDC with Salesforce

Warning

Salesforce often change the look and feel of their systems, so these directions might not always be up to date and the configuration steps might be slightly different. When in doubt, consult the Salesforce OIDC documentation

• Go to Setup
• Search for Identity Provider and open the Identity Provider page
• If the Identity Provider Setup is not yet enabled, click on Enable Identity Provider
• Choose the Self-signed certificate, or the certificate used by your organization, from the list and click Save
• Download the Salesforce IdP metadata by clicking on Download Metadata
• Provide the downloaded metadata to your Textkernel Technical Consultant
• Search for Connected App and open the Manage Connected Apps page
• Create a new New Connected App
• In the Web App Settings section, configure the necessary OAuth settings for the connected app
• Select the Allow access to your unique identifier (openid) scope to apply to the connected app
• Select Configure ID token
• With the primary ID token setting enabled, configure the secondary settings that control the ID token contents in both access and refresh token responses. This is where both standard and custom attributes can be set
• Textkernel will now proceed to install the provided metadata

To assign users or user profiles to the Connected App, e.g. via Manage Connected Apps:

• Click on the Connected App to which profiles it should be assigned
• In section Profiles, click on Manage Profiles

OIDC with Okta

Warning

Okta often change the look and feel of their systems, so these directions might not always be up to date and the configuration steps might be slightly different. When in doubt, consult the Okta OIDC documentation

To configure SAML in Okta, a user with Administrator privileges can follow these steps:

• In the Admin panel, create a new App Integration by clicking on Create App Integration
• In the Create a new app integration dialogue select:
  • Sign-in method: OIDC - OpenID Connect
  • Application type: Web Application
• In your newly created application, configure the Sign-in redirect URIs as provided by your Textkernel Technical Consultant
• (Optional) If you want to grant access to certain user groups only choose Limit access to selected groups in the Assignments - Controlled access section
• Provide the Client ID, Client secret and Okta domain to the Textkernel Technical Consultant