External SAML Authentication

Overview

This topic explains how to configure TOS for SAML authentication using Okta or Azure. SAML is an open standard that enables users to log into an external authentication system, the Identity Provider (IDP). The IDP then automatically logs the user into TOS, the Service Provider (SP). TOS supports SAML 2.0.

TOS uses the OpenID Connect protocol, which in turn uses the Keycloak Authentication service as an IDP. For OpenID Connect, TOS is a Relying Party (RP) that can accept and receive information from a third-party authentication service.

To configure TOS to use Keycloak as an external IDP, you must first configure Keycloak as a SAML SP.

External SAML authentication only applies to SecureTrack, unless you also use internal SSO authentication to make it apply to all TOS modules - SecureTrack, SecureChange and SecureApp. For TOS R22-1 and later, internal SSO authentication is enabled by default. When upgrading from earlier releases, this feature needs to be manually activated.

SAML Authentication Flow

TOS authenticates login requests via SAML as follows:

  1. SecureTrack is the RP for OpenID Connect. It redirects authentication requests to Keycloak, the internal IDP for OpenID Connect.

  2. Keycloak is also the SAML SP. It redirects requests to an external SAML IDP.

  3. The SAML IDP completes the authentication and redirects the authentication approval back to Keycloak.

  4. Keycloak then redirects the authentication approval back to SecureTrack.

Prerequisites

To configure SecureTrack for SAML authentication, you need the following:

  • Browser access to a SAML provider

    • For Microsoft Edge, a signed CA certificate for the Apache HTTPD web server. The self-signed certificate provided by SecureTrack is not supported by Microsoft Edge for SAML SPs.

  • Outgoing HTTPS connection from the SecureTrack server to the SAML SP.

    SecureTrack can resolve the domain name of the SAML provider.

  • String to be used as a label on the SAML login button. Maximum length is 10 characters including spaces.

Before You Begin

  • Backup your SecureTrack configuration using the following command: 

    [<ADMIN> ~]$ sudo tos backup create
    sudo tos backup create

    See tos backup create.

  • Make sure your SAML provider administrator is available during the configuration process.

Which Server Needs to be Configured?

Environment Server
Standard SecureTrack server
High Availability Active SecureTrack server
Distributed Architecture Central Server

SAML Configuration Procedure

    1. In the server, run: 

      [<ADMIN> ~]$ kubectl exec -it deploy/keycloak-service -c keycloak-service -- manage_keycloak -r add_keycloak_admin_user -u <username>
      kubectl exec -it deploy/keycloak-service -c keycloak-service -- manage_keycloak -r add_keycloak_admin_user -u <username>

    2. Enter the new password for the Keycloak Administrator user.

      You can log into Keycloak using the credentials configured above:

      https://<ip>/auth/admin/master/console/
      https://<ip>/auth/admin/master/console/

    1. Log into Keycloak as the Administrator user you created in the previous step.

      2. https://<ip>/auth/admin/master/console/
      https://<ip>/auth/admin/master/console/

    2. In the navigation pane, switch to tufin-realm.

    3. Go to Authentication > Flows tab and select Tufin-flow.

    4. In the Actions menu, click Add Step.

      The Add Step form appears.

    5. Go to the second page, select Identity Provider Redirector, and click Add.

    6. Drag the Identity Provider Redirector step below the Cookie step and change the requirement to Alternative.

    1. Go to Authentication, and click Create Flow.

      2. The Create Flow page appears.

    2. In the Namefield, enter Tufin-Broker Flow, and click Create.

    3. In the new flow, click Add an Execution.

      The Add Step to Tufin-Broker-Flow form appears.

    4. Select Create User (Tufin), and click Add.

    5. In the Tufin-Broker-Flow page, select the Alternative requirement.

    1. Go to Identity Providers, and in the Add Provider drop-down menu, select SAML v2.0

      2. The Add identity provider page appears.

    2. Copy the Redirect URI to a separate file.

    3. In the Alias field, enter a unique identifier for your IDP. The Alias is used to reference the IDP internally and is included in the Redirect URL.

    4. In the Display Name field, enter the string you are going to use as the label on the Login button.

      Do not click Save or close the Identity Provider. This procedure continues below after you receive the IDP metadata.

  5. Okta (to configure Microsoft Azure as the external IDP, use step 6)

      1. Sign in to Okta as an administrator.

      2. In Okta, go to Applications > Applications, and click Create App Integration.

        3. The Create a new app integration dialog box is displayed.

      3. Select SAML 2.0 as the Sign-in method, and click Next.

        4. The Create SAML Integration form is displayed.

      4. In the App Name field, enter a name for the application (for example, SAML Application), and click Next.

      5. In the Single Sign On URL, and Audience URI (SP Entity ID) fields, enter the Keycloak Redirect URL (you pasted into a separate file above), and click Next.

      6. Answer the questions in the Feedback tab, and click Finish.

      1. Go to Applications > Applications, and in the drop-down menu for the app you created in the previous step, select Assign to Users.

        2. The Assign SAML Application to People dialog box appears.

      2. Use the Search field to locate the relevant users.

      3. For each user, click Assign.

      4. Click Done.

      1. Go to Applications > Applications, and click on the application you created.

        2. The application is displayed.

      2. In the Sign On tab, click on View Setup Instructions.

        3. The How to Configure SAML 2.0 for SAML Application Application page opens in a separate tab.

      3. In the Optional section, copy the IDP metadata to a separate file (for example, okta_conf.xml).

      4. In the Identity Provider in Keycloak, toggle off Use Entity Descriptor.

      5. In the Import config from file field, upload the saved file.

        Keycloak imports the relevant configuration information from the saved file.

      6. Click Add.

        The Identity Provider is created.

      7. In the IDP > Advanced Settings, in the First login flow field, select Tufin-Broker-Flow.

      8. Click Save.

    4. Create Mappers in the Keycloak IDP

        1. In the Keycloak IDP, go to the Mappers tab, and click Add Mapper.

          2. The Add Identity Provider Mapper page is displayed.

        2. Enter the following information:

          • Name:SAML Username

          • Mapper Type: Select SAML Username Attribute Importer

          • User Attribute Name:real_user_name

        3. Click Save.

        1. In the Keycloak IDP, go to the Mappers tab, and click Add Mapper.

          2. The Add Identity Provider Mapper page is displayed.

        2. Enter the following information:

          • Name: AuthType

          • Mapper Type: Select Hardcoded Attribute

          • User Attribute:AUTH_TYPE

          • User Attribute Name: SSO

        3. Click Save.

      1. In the application you created in Okta, (in this example, it is "SAML Application") go to the General tab > SAML Settings, and click Edit.

        2. The Edit SAML Integration page appears.

      2. Click Next.

      3. In the Attribute Statements (Optional) section,

      4. add three attribute statements with the following information:

        1. first name:

          • Name:firstName

          • Name format: Unspecified

          • Value:user.firstName

        2. last name:

          • Name:lastName

          • Name format: Unspecified

          • Value:user.lastName

        3. email

          1. Name:email

          2. Name format: Unspecified

          3. Value:user.email

      5. Click Next and then Finish.

      6. In the Keycloak IDP, go to the Mappers tab, and click Create.

      7. The Add Identity Provider Mapper page is displayed.

      8. Enter the following information:

        • Name:firstName

        • Mapper Type: Select Attribute Importer

        • Attribute Name:firstName

        • Friendly Name:firstName

        • User Attribute Name:firstName

      9. Click Save.

      10. Repeat this procedure to create mappers for: lastName and email.

      These attribute names need to be the same as the attribute names configured in Okta.

      1. In the Keycloak IDP, go to the Settings tab, and do the following:

        1. Want Assertions Signed: Toggle On

        2. Validate Signature: Toggle On

      2. Click Save.

      7. You can now log in to SecureTrack via Okta.

  6. Microsoft Azure (To configure Okta as the external IDP, use step 5)

    1. Before beginning, clear browser cookies.

      1. In the Azure Active Directory, go to Enterprise Applications, and click Add.

      2. When setting up the application, in the Single Sign-on page, select SAML.

      3. In the set up Single Sign-On With SAML page > Basic SAML Configuration, click the Edit button, and enter the following information:

        • Identifier (Entity ID): Keycloak URL

        • Reply URL (Assertion Consumer Service URL): Redirect URL to the IDP you created in Keycloak

        • Sign on URL (Optional): The SecureTrack URL

      4. In User Attributes and Claims, click the Edit button, and edit the claims as follows:

        Name

        Source attribute (do not change)
        firstName user.givenname
        lastName user.surname
        email user.email

        5. The names in the Azure Enterprise application need to be identical to the names of the IDP mappers in Keycloak. The names are case sensitive.

      5. Clear the Namespace field for each user attribute.

      1. In the Keycloak IDP SAML Settings, change the NameID Policy Format to Unspecified.

      2. In the Azure Enterprise Application, copy the IDP metadata to a separate file.

      3. In the Identity Provider in Keycloak, toggle off Use Entity Descriptor.

      4. In the Import config from file field, upload the saved file.

        Keycloak imports the relevant configuration information from the saved file.

      5. Click Add.

        The Identity Provider is created.

      6. In the IDP > Advanced Settings, in the First login flow field, select Tufin-Broker-Flow.

      7. Click Save.

    3. Create Mappers in the Keycloak IDP

        1. In the Keycloak IDP, go to the Mappers tab, and click Add Mapper.

          2. The Add Identity Provider Mapper page is displayed.

        2. Enter the following information:

          • Name:SAML Username

          • Mapper Type: Select SAML Username Attribute Importer

          • User Attribute Name:real_user_name

        3. Click Save.

        1. In the Keycloak IDP, go to the Mappers tab, and click Add Mapper.

          2. The Add Identity Provider Mapper page is displayed.

        2. Enter the following information:

          • Name: AuthType

          • Mapper Type: Select Hardcoded Attribute

          • User Attribute:AUTH_TYPE

          • User Attribute Name: SSO

        3. Click Save.

      1. In the Keycloak IDP, go to the Mappers tab, and click Create.

      2. The Add Identity Provider Mapper page is displayed.

      3. Enter the following information:

        • Name:firstName

        • Mapper Type: Select Attribute Importer

        • Friendly Name:firstName

        • User Attribute Name:firstName

      4. Click Save.

      5. Repeat this procedure to create mappers for: lastName and email.

      Unlike Okta, the Attribute Name field needs to be empty.

      1. In the Keycloak IDP, go to the Settings tab, and enter the following information:

        1. Want Assertions Signed: Toggle On

        2. Validate Signature: Toggle On

      2. Click Save.

  7. Delete the Keycloak Administrator user.
    • In Keycloak, go to the Users page, and delete the user you created in step 1.
  8. If you are using TOS SSO, when activating the feature, the SecureTrack Administrator must manually add all the SAML authenticated users into SecureTrack, and assign them roles before they log in for the first time.
    9. Do not delete integration_user. This user is needed for the SecureTrack integration.

Known Issues

Issue

If an LDAP user logs into SecureTrack for the first time and SecureTrack already contains an SAML user with the same username, SecureTrack may confuse the LDAP and SAML user identities, which will result in the LDAP user logging into SecureTrack on behalf of the SAML user.

Workaround

Do not create LDAP users and SAML users with the same user name. The same user should not use LDAP authentication and SAML authentication for the same SecureTrack server.

Troubleshooting

  • When logging into TOS using the SAML Login button, the following error appears:

    Reply URL does not match the reply URLS Configured in the application

    To solve this issue:

    In Azure, check that the reply URL matches the URL in the Keycloak IDP.

    The Reply URL can be found in the first step of the Azure Basic SAML configuration.

  • When logging into SecureTrack using the SAML login button, the user gets a Redirect Identity URL Provider error.

    To solve this issue:

    In the Keycloak IDP settings, make sure that the Alias is one word with no spaces.

  • The user enters the correct credentials for logging in with SAML. However, instead of being logged into TOS, the user is redirected back to the Login screen.

    No error message appears in the log file.

    To solve this issue:

    In the Keycloak IDP, check that the correct First Login Flow is selected, and that it is configured according to the instructions above.

  • After logging in with SAML, the account's user name attributes has the wrong values.

    To solve this issue:

    Check the following:

    1. The user attributes in Azure match the user name in the mapper in Keycloak.

    2. The user name that Azure is sending back to SecureTrack. It could be that the attribute username is being translated incorrectly, or changed to the e-mail.

      To fix the user name, click Unique User Identifier (Name ID).

      The Identify format should be Persistent.

  • When logging into SecureTrack, the user receives a message that the user already exists.

    The /opt/tufin/logs/services/keycloak-service/server.log log file contains the following warning message:

    WARN 2018-10-22 10:12:55,673
   [default task-15::c.t.c.k.a.a.b.CustomIdpCreateUserIfUniqueAuthenticator.checkExistingUser]
   [user:] CustomIdpCreateUserIfUniqueAuthenticator: username
   [...] already exists, the user id [...].

    To solve this issue:

    The SecureTrack administrator needs to delete the user with the same user name from SecureTrack.

    If the existing SecureTrack user cannot be deleted, the SAML user will not be able to log in.

    The SAML user name is not case sensitive.

  • The user enters the correct credentials for logging in with SAML, and the following error is displayed:

    Error:
   OpenID Connect Provider error: Remote user could not be set:
   contact the website administrator

    To solve this issue

    In the Keycloak IDP check that the real_user_name mapper is configured according to the instructions above.

  • The user enters the correct credentials for logging in with SAML, and an error is displayed.

    The /opt/tufin/logs/services/keycloak-service/server.log log file contains the following warning message:

    ERROR 2018-10-22 11:18:12,793
   [catalina-exec-1::c.t.s.s.RemoteUserIntegrationFilter.doFilter]
   [user:system] Authentication failed for user: [[email protected]]
   java.lang.IllegalArgumentException: Authentication type cannot be empty

    To solve this issue:

    In the Keycloak IDP check that the AUTH_TYPE mapper is configured according to the instructions above.

  • In Azure, the user receives a message that they do not have permissions to log in.

    To solve this issue:

    Confirm that you can log in locally with an Admin account, and try to log into Azure from a different application using the user name that was denied access.

    If you are can log in with Admin Credentials, the issue is with the Azure configuration and not with the connection to Keycloak.

  • A hostname sign in error message appears when logging into SecureTrack.

    AADSTS700016: Application with identifier 'https://<ST IP Address>/auth/
realms/tufin-realm' was not found in the directory '7f59c73b-4f18-1987
-ba40-7410bd850974'. This can happen if the application has not been
installed by the administrator of the tenant or consented to by any
user in the tenant. You may have sent your authentication request to
the wrong tenant.

    To solve this issue:

    Log in using the SecureTrack hostname instead of the IP address.

  • One of the user attributes (First Name, Last Name, or Email Address) is empty in SecureTrack after successful authentication.

    To solve this issue:

    You need to open the SAML IDP configuration and configure the mappers for the missing user attribute (First Name, Last Name, or Email Address) according to the instructions above.

  • When logging in, the page appears as follows:

    To solve this issue:

    • Clear browser cookies

    • Check the attribute settings in both Azure and Keycloak, and make sure they are entered correctly. Attribute names are case sensitive.

  • User lacks permission to log into SecureTrack.

    To solve this issue:

    • Login locally from a different account

    • Check if this issue is limited to SecureTrack by logging into a different application with the same user.

    • Verify that the user credentials are correct.

Notes

The Keycloak Server Log is /opt/tufin/logs/services/keycloak-service/server.log