Skip to main content

Documentation Portal

Update SAML Configuration

In case SAML is configured as your IdP it needs to be reconfigured after updating TrendMiner. The following is a step-by-step guide for both Azure AD and OKTA.

Tip

This page only applies to customers who upgraded from 2021.R3.0 and already had a SAML IdP configured before the upgrade. To enable SAML for the first time, check our installation guide.

Important

Users will not be able to log in via SAML after the upgrade as long as this configuration update is not applied.

Azure AD

As a first step user and security claims need to be setup correctly. With this configuration Azure AD will return the correct Subject in the response for use in TrendMiner.

  1. Configure user attributes & claims:

    1. Click the "Edit"-button under "User Attributes & Claims"

      Update_Itentity_1.png

    2. Click on the "Unique User Identifier (Name ID)" option.

      Update_Itentity_2.png

    3. Migration logic will try to autodetect the correct nameIdPolicy format, that you specified in SAML. It defaults to the ‘PERSISTENT’ type in case it could not detect the format for some reason. Note that the source attribute "user.userprincipalname" refers to the email in Azure. Under "Source" select ''Transformation" and add the "ToLowercase()" transformation for the "user.userprincipalname" as shown in the screenshot below.

      Note

      If you are not using the email addresses as usernames in TrendMiner, select the source attribute which matches the username format in TrendMiner.

      azuread-name-identifier-format.png

  2. Configure groups:

    1. Click the "Edit"-button under "User Attributes & Claims"

    2. Click the "Add a group claim"-option.

      Update_Itentity_4.png

    3. Set the Group Claims as shown on the screenshot below:

      • Associated: Groups assigned to the application.

      • Source attribute: Group ID

        Update_Itentity_5.png

        Note

        In this release TrendMiner does not support syncing the group names yet so groups will be shown in ConfigHub by their ID.

    After setting up the initial application in AZURE you can continue in TrendMiner's ConfigHub. Via ConfigHub you can see an overview of the existing Identity Providers.

  3. Configure TrendMiner ConfigHub:

    1. Navigate to TrendMiner's ConfigHub and open the "Identity Providers" tab in the "Security" section.

    2. Select your identity provider. A side-panel should open where you can edit your IdP settings (actions > edit).

      Update_Itentity_6.png

    3. Enable the Attributes mapping and fill out the fields. The values you need to fill in for the attribute mapping can be found in Azure under 'Attributes & Claims'.

      azure_saml_attributes_claims.png

      • First name: extract first name out of assertions. e.g.:

        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'

      • Last name: extract last name out of assertions. e.g.:

        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname'

      • email: extract e-mail out of assertions. e.g.:

        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'

      • Group: extract groups out of assertions. e.g.:

        'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups'

      • Separator: parse group value out of group assertion. Used when all groups are available in one Attribute Value tag. Default is 'none'

        Update_Itentity_7.png

  4. Download the metadata from TrendMiner:

    1. Navigate to TrendMiner's ConfigHub and open the "Identity Providers" tab in the "Security" section.

    2. Select your identity provider. A side-panel should open where you can download the metadata (actions > download metadata).

      Update_Itentity_8.png

  5. Update metadata of the identity Provider:

    1. Navigate in Azure AD to your SAML application and open the "Single sign-on"-tab.

    2. Click the "Upload metadata file" and upload the TrendMiner metadata file. The values in 'Identifier (Entity ID)' and 'Reply URL (Assertion Consumer Service URL)' will be updated with the values read from the metadata file.

      Update_Itentity_9.png

    3. It can happen that the metadata file is not processed correctly. In case the 'Logout Url (Optional)' field is filled in and the 'Reply URL (Assertion Consumer Service URL)' field is empty, copy the logout url value to the reply url field and save your changes.

      Update_Itentity_10.png

  6. The SAML setup is complete and you should be able to login to TrendMiner. After logging in with a SAML user in TrendMiner the assigned groups should be synced and ACLs can be configured.

OKTA

As a first step the user and security claims need to be setup correctly. With this configuration OKTA will return the correct Subject in the response for use in TrendMiner.

  1. Navigate in OKTA to your application and open the "General"-tab.

    1. Click "edit" for the SAML settings and proceed to step 2 "Configure SAML"

    2. Fill out the details for the SAML settings and click on next when finished.

      • Application username: OKTA username

        saml_okta_settings.png

    3. Make sure that the following Attribute statements are set:

      • firstName / unspecified / user.firstName

      • lastName / unspecified / user.lastName

      • email / unspecified / user.email

        Update_Itentity_12.png

    4. Make sure that a Group statements is present:

      Update_Itentity_13.png

    After setting up the initial application in OKTA you can continue in TrendMiner's ConfigHub. Via ConfigHub you can see an overview of the existing Identity Providers.

  2. Configure TrendMiner ConfigHub:

    1. Navigate to TrendMiner's ConfigHub and open the "Identity Providers" tab in the "Security" section.

    2. Select your identity provider. A side-panel should open where you can edit your IdP settings (actions > edit).

      Update_Itentity_14.png

    3. You can edit the main provider details:

      • Name: Display name in ConfigHub and used as root group. Does not relate to any technical SAML details.

      • Base Domain: Used in URLs of the SP metadata file. Eg: where the IDP has to redirect after identification.

      • NameID Policy Format: A dropdown to select the policy format as being used by the customer SAML provider (f.ex. Azure, Okta). Possible values are: Persistent, Transient, Email, Kerberos, X.509 Subject Name, Windows Domain Qualified Name, Unspecified

      • Principal Type: A dropdown to select the principal type as being used by the customer SAML provider (f.ex. Azure, Okta). Possible values are: Subject name ID, Attribute name, Attribute friendly name

      • Principal Attribute: In case attribute name or attribute friendly name was selected as an option from the Principal Type dropdown a extra input field will become visible to allow to enter the name of the specific attribute to be used

      SAML-OKTA-attribute_mapping.png

    4. Enable the Attributes mapping and fill out the fields.

      • First name: extract first name out of assertions. e.g.: firstName

      • Last name: extract last name out of assertions. e.g.: lastName

      • E-mail: extract e-mail out of assertions. e.g.: email

      • Group: extract groups out of assertions. e.g.: groups

      • Separator: parse group value out of group assertion. Used when all groups are available in one AttributeValue tag. Default is 'none'

        Update_Itentity_15.png

  3. Download the metadata from TrendMiner:

    1. Navigate to TrendMiner's ConfigHub and open the "Identity Providers" tab in the "Security" section.

    2. Select your identity provider. A side-panel should open where you can download the metadata (actions > download metadata).

      Update_Itentity_16.png

  4. OKTA does not support uploading SP metadata files so some manual extraction is necessary:

    1. Open the metadata file from TrendMiner in a text-editor. The metadata should like this:

      <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="ID_3f7843b9-664f-40e7-a536-2fa8893e87b6" entityID="https://trendminer.example.com/auth/realms/trendminer">

<md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://trendminer.example.com/auth/realms/trendminer/broker/7fc6524e-3d55-4ae2-9edf-3d678e376063/endpoint"/>

<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://trendminer.example.com/auth/realms/trendminer/broker/7fc6524e-3d55-4ae2-9edf-3d678e376063/endpoint" index="1" isDefault="true"/>

<md:AttributeConsumingService index="1" isDefault="true">

<md:RequestedAttribute FriendlyName="lastName" Name="lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>

<md:RequestedAttribute FriendlyName="email" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>

<md:RequestedAttribute FriendlyName="firstName" Name="firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>

</md:AttributeConsumingService>

</md:SPSSODescriptor>

</md:EntityDescriptor>

    2. Copy the Location value from <md:SingleLogoutService>. In this example this corresponds to: https://trendminer.example.com/auth/realms/trendminer/broker/7fc6524e-3d55-4ae2-9edf-3d678e376063/endpoint

      This URL needs to be added in OKTA.

    3. Navigate in OKTA to your application and open the "General"-tab.

    4. Click "edit" for the SAML settings and proceed to step 2 "Configure SAML"

      Update_Itentity_17.png

    5. Make sure that the "Single sign on URL" and "Audience URI" are set to the copied URL.

      Update_Itentity_18.png

    6. The SAML setup is complete and you should be able to login in TrendMiner. After logging in with a SAML user in TrendMiner the assigned groups should be synced and ACLs can be configured.

In this section: