Authentication with SAML🔗

In this section, we will cover how to integrate Textkernel's TK Portal with well-known Identity Providers using the SAML 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.

In order to integrate the Textkernel user interface in an iframe, an Identity Provider-initiated SSO flow needs to be set up. Please refer to your Textkernel Technical Consultant for further information and configuration support.

Definitions🔗

Identity Provider (IdP, IDP): is a service used to store and manage digital identities. Organizations use IdPs to allow their users to connect to various resources while using the same credentials. IdPs make it possible to manage access privileges, and provide a layer of security.
Service Provider (SP): is the entity that provides the service. In our case, Textkernel is the SP.
Claim: is a piece of information about the end-user, i.e. the user that wants to access the TK Portal. In SAML, claims are communicated in the form of assertions.

Requirements🔗

The customer must:

Use a SAML2 compatible Identity Provider (e.g. Microsoft ADFS, Salesforce, Okta, etc).
Be able to, either:
1. Send a single identity claim containing the email address of a user (with some restrictions) or,
2. Add custom claim rules.
Provide the metadata data of their Identity Provider, either in a file or using a URL.
Allow the Textkernel SAML2 Service 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 SAML2 can be used by the customer.

TK Portal SAML Assertions🔗

Here is the complete list of assertions to be implemented:

All assertions are of Type String
Required claims are marked with an asterisk *. The rest are Optional.

Assertions
http://textkernel.com/auth/portal/user * ID within the account, e.g. username, email address or unique user ID. Never shown to the user.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress * Required for Saved Searches and Email Alerts functionality.
http://textkernel.com/auth/portal/displayname Text shown in the TK Portal screen once the user is logged in, and in other communications with the user.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname Used to construct a displayname if no displayname was given.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname Used to construct a displayname if no displayname was given.
http://textkernel.com/auth/portal/roles This attribute can be used to pass a list of Portal Roles. Invalid portal roles will be ignored. Portal roles can be supplied as multiple values or one single comma or semicolon separated string. Please make sure the portal roles themselves contain no commas or semicolons. If an activerole is provided and it's not among these roles, the activerole parameter will be ignored and the active role will be set to the first role in the list.
http://textkernel.com/auth/portal/searchPolicies This attribute can be used to pass a list of Search Policies. The policies passed will overwrite the Search Policies that have been previously set. Policies can be supplied as multiple values or one single comma or semicolon separated string. Please make sure to follow the naming conventions.
http://textkernel.com/auth/portal/activerole The value must be one of the roles configured in the account in the TK Portal account configuration.
http://textkernel.com/auth/portal/lang 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 SAML2 can be used as well, and the instructions should be similar.

The IdPs covered are:

ADFS 3.0
Salesforce
Okta

SAML with ADFS🔗

Warning

Microsoft 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 ADFS documentation

TK Portal has its own account and user configuration. Therefore, for SAML authentication with AD/ADFS, AD users must be mapped to TK Portal users. We will describe 2 methods to achieve this mapping, by:

Sending a single identity claim containing the AD user's email address
Adding Textkernel-specific custom claims that specify the TK Portal user, TK Portal account, and the TK Portal interface language.

The document describes the procedure for Windows 2012R2 Server, and ADFS 3.0. The procedure for older versions of ADFS is similar.

Creating a trust relationship🔗

To create a trust relationship, perform the following steps on the ADFS server:

Open Server Manager
On the menu bar of Server Manager, choose Tools -> AD FS Management
On the right, in the Actions list, choose Add Relying Party Trust
On the Welcome page, click Start
On the next page choose option "Import data about the relying party published online", import the metadata that has been or will be provided to you by a Textkernel Technical Consultant, and click Next
If a popup window explains that some content from metadata was skipped, just click OK, this is expected behaviour
In the next screen, enter a display name, e.g. Textkernel TK Portal Trust, click Next
On the next screen leave the default option "I do not want multi-factor authentication settings for this relying party trust at this time" and click Next
On the next screen, choose "Permit all users to access this relying party". If you only want to grant access to specific users you can also choose for option "Deny all users access to this relying party". No explanation will be given in this guide of how to configure issuance authorization rules for specific users to enable access for them. Click Next.
On the next screen, review all settings, and click Next.
The trust has been successfully configured.

Editing Claim rules🔗

Edit the rules for sending claims to the relying party.

Sending a single identity claim🔗

Note that some restrictions apply in this scenario:

You can not define a specific interface language on a per user basis.
You must use an email address for the UPN.
An email address consists of a local and a domain part, e.g. in tom@test.nl, "tom" is the local part, and "test.nl" is the domain part.
In TK Portal, the domain part will be mapped to a TK Portal account, and the local part to a TK Portal user name in that account. This means that you can only use a single claim, if all users from the same domain can/must be mapped to the same TK Portal account.
Configure the UPN claim
Open Server Manager
On the menu bar of Server Manager, choose Tools -> AD FS Management
On the left navigate to AD FS -> Trust Relationships -> Relying Party Trusts
Select the Textkernel TK Portal Trust
On the right in the Actions list, under Textkernel TK Portal Trust, click Edit Claim Rules
In the Edit Claim Rules window, on tab Issuance Transform Rules, click Add Rule
In the Add Transform Claim Rule Wizard choose the claim template Send LDAP Attributes as Claims and click Next
On the next screen, enter a name for the claim rule, e.g. "UPN Claim"
Select attribute store Active Directory
In the mapping configuration table, click on down arrow in the first empty cell of the first empty row
Choose LDAP attribute User-Principal-Name
In the second column of the same row, choose UPN from the dropdown
Click Finish
The UPN will be sent to in form of user@domain.win, where user is the UPN logon from the user properties of the Active Directory and domain.win is its domain part (Textkernel will map those values to the appropriate account in TKPortal)

Adding Textkernel-specific custom claims🔗

First, complete all the steps described in the previous section

Then, add 2 other claim rules to define the Textkernel specific claims:

Edit Claim Rules window, on tab Issuance Transform Rules, click Add Rule
In the Add Transform Claim Rule Wizard choose claim template Send Claims using a Custom Rule and click Next
On the next screen, enter a name for the claim rule, e.g. "TK TK Portal Account Claim"
Paste the following code into the Custom rule textbox:

c:[Type ==
"http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer ==
"AD AUTHORITY"]
=> issue(type = "http://textkernel.com/auth/portal/account", value = "demo");

This rule sets the TK Portal account claim to the fixed value "demo" (replace this with the account name as provided by your Textkernel Technical Consultant), so all users will use this TK Portal account. If you have more complicated requirements, you can also use any other AD attribute. For example, you could use AD attribute department, to map users from one department to one TK Portal account. Please consult with Textkernel if you have this kind of requirement.
Click Finish
In the Add Transform Claim Rule Wizard choose claim template Send Claims using a Custom Rule and click Next
On the next screen, enter a name for the claim rule, e.g. "TK TK Portal user and language claim"
Paste the following code into the Custom rule textbox:

c:[Type ==
"http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer ==
"AD AUTHORITY"]
=> issue(store = "Active Directory", types =
("http://textkernel.com/auth/portal/user", "http://textkernel.com/auth/portal/lang"),
query = ";sAMAccountName,preferredLanguage;{0}", param = c.Value);

This claim rule maps the AD attribute sAMAccountName from the account properties in the Active Directory to the TK Portal user name and the AD attribute preferredLanguage to the TK Portal interface language.
Click Apply

This completes the setup.

SAML 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 SAML documentation

To configure SAML in Salesforce, a user with specified user permissions can follow these steps:

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, check the Enable SAML checkbox
Enter the Entity Id and ACS URL as provided by your Textkernel Technical Consultant
Save all settings
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

SAML 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 SAML 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: SAML 2.0
Fill in the General settings
Your Textkernel Technical Consultant will provide you with the values to fill in the Configure SAML section.
Download the Okta Certificate metadata and provide it to your Textkernel Technical Consultant.
Configure claims in the Attribute Statements section, using the URI Reference format.
Configure feedback.