1. Overview

Many organizations use SAML to authenticate users for web services. Twistlock supports the SAML2.0 federation protocol to access Twistlock Console. When SAML support is enabled, administrators can log into the Console with their federated credentials. This article provides detailed steps for federating your Twistlock Console with your Azure Active Directory (AAD) tenant’s Identity Provider (IdP).

The Twistlock / Azure Active Directory SAML federation workflow is as follows:

  1. The user browses to Twistlock Console.

  2. The browser is redirected to AAD SAML2.0 endpoint.

  3. The user enters their AAD credentials.

  4. The AAD SAML token is returned to Twistlock Console.

  5. The Twistlock Console validates the Azure Active Directory SAML token’s signature and associates the user to their Twistlock account via user identity mapping or group membership. Twistlock supports SAML groups for Azure Active Directory federation.

When Twistlock is integrated with SAML, the logout button in Console works differently than expected. When you log out Twistlock unregisters your token, but it does not log you out from your SAML provider (because users want to stay signed into their other apps). Instead, the token is removed and you are redirected back to the login page, which automatically signs you back into Console (assuming that you are still logged into the SAML provider). Logging out from Console, therefore, essentially refreshes your account information and group memberships.

The Azure Portal may change the Enterprise Application SAML federation workflow over time. The concepts and steps outlined in this document can be applied to any Non-gallery application.

2. Federation with Azure Active Directory

The Twistlock Console is integrated with Azure Active Directory as a federated SAML Enterprise Application.

2.1. Configure Azure Active Directory

Configure Azure Active Directory.

Prerequisites

  • Required Azure Active Directory SKU: Premium

  • Required Azure Active Directory role: Global Administrator

Procedure

  1. Log onto your Azure Active Directory tenant (https://portal.azure.com).

  2. Go to Azure Active Directory > Enterprise Applications

  3. On the top left of the window pane, click + New Application.

  4. Select Non-gallery application, from the Add your own app section.

    aad saml 20180912 1
  5. In the Name field, enter pfox-console, then click Add. In this example I am using "pfox-console."

  6. On the pfox-console menu select Single sign-on and choose SAML-based Sign-on

    aad saml 20180912 2
  7. Section #2 Domain and URLs:

    1. Identifier: pfox-console (Set to your Console’s unique Audience value. You will configure this value within your Console at a later step.)

    2. Reply URL: https://<FQDN_of_your_Twistlock_Console>:8083/api/v1/authenticate

      aad saml 20180912 3
  8. Section #3 User Attributes:

    Select the Azure AD user attribute that will be used as the user account name within Twistlock. This will be the NameID claim within the SAML response token. Recommend using the default value.

    1. User Identifier: user.principalname

      aad saml 20180912 4
      Even if you are using AAD Groups to assign access to Twistlock set this value.
    2. Select Show Advanced certificate signing settings.

    3. Set Signing Option: Sign SAML Response.

  9. Section #4 SAML Signing Certificate:

    1. Select Download: Certificate (Base64)

    2. Select Show Advanced certificate signing settings

    3. Set Signing Option: Sign SAML Response

      aad saml 20180912 5
  10. Section #5 Configure pfox_console:

    Click on the pfox-console Configuration section

    1. Save the values of SAML Single Sign-On Service URL and SAML Entity ID

    2. Then close the blade.

      aad saml 20180912 6
  11. Click Save

  12. Make sure to copy the Application’s ID.

  13. Click on Users and Groups within the Manage section of the application. Add the users and/or groups that will have the right to authenticate to Twistlock Console.

    aad saml 20180912 7

2.1.1. Twistlock User to AAD User Identity mapping

If you plan to map Azure Active Directory users to Twistlock accounts go to Configure Twistlock Console.

2.1.2. Twistlock Groups to AAD Group mapping

When you use Azure Active Directory Groups to map to Twistlock SAML Group, do not create users in Twistlock Console. Configure the AAD SAML application to send AAD group membership (http://schemas.microsoft.com/ws/2008/06/identity/claims/groups) claims within the SAML response token. If you enable AAD Group authentication the Twistlock User to AAD User Identity method of authentication will be ignored.

  1. Set Application permissions:

    1. In Azure go to Azure Active Directory > Application Registrations > pfox-console

    2. Click on settings

    3. Click on Required permissions

    4. Select Add

    5. Click on Select an API: Windows Azure Active Directory

    6. Select permissions: Application Permissions: Read directory data

      aad saml 20180912 8
    7. Click save

    8. Click Grant permission within the Required permissions blade.

  2. Create Application Keys

    1. Click on the application’s settings and select Keys

    2. Add a key description

    3. Duration: Never expires

    4. Click save

    5. Make sure to save the key value that is generated before closing the blade.

      aad saml 20180912 9
  3. Configure the application to send group claims within the SAML response token.

    You can configure this setting either within the Azure portal or via powershell.

    1. Azure AD Portal:

      1. Go to Azure Active Directory > App registrations > pfox-console

      2. Click Manifest

      3. Set "groupMembershipClaims": "SecurityGroup"

      4. Click Save

    2. Powershell:

      1. Use the Azure AD powershell commandlet Set-AzureADApplication to configure the application.

      2. Run the following powershell commands:

        import-module AzureAD
        Connect-AzureAD
        $twistlock = Get-AzureADApplication | where-object {$_.DisplayName -eq "pfox-console"}
        $oid = $twistlock.ObjectId
        Set-AzureADApplication -ObjectID $oid -GroupMembershipClaims 1
      3. Confirm that the GroupMembershipClaims has been set to SecurityGroup

        $twistlock = Get-AzureADApplication | where-object {$_.DisplayName -eq "pfox-console"}
        $twistlock.GroupMembershipClaims
        Allow several minutes for these permissions to propagate within AAD.

2.2. Configure Twistlock Console

Procedure

  1. Login to Twistlock Console as an administrator.

    1. Integrate SAML users and groups with Twistlock: Enabled.

    2. Identity Provider: Azure

    3. Identity provider single sign-on URL: Azure AD provided SAML Single Sign-On Service URL

    4. Identity provider issuer: Azure AD provided SAML Entity ID

    5. Audience: pfox-console

    6. Application ID: pfox-console’s AAD application ID

    7. Tenant ID: AAD tenant ID that contains the pfox-console application

    8. Application Secret: pfox-console application keys (only required if using AAD Groups)

    9. X.509 certificate: paste Azure AD SAML Signing Certificate Base64 into this field

      aad saml 20180912 10
  2. Click Save

2.2.1. Twistlock User to AAD User Identity mapping

If you plan to map Azure Active Directory users to Twistlock accounts perform the following steps.

  1. Go to Manage > Authentication > Users

  2. Click Add user

  3. Create a New User

    1. Username: Azure Active Directory userprincipalname

    2. Role: select appropriate role

    3. Create user in local Twistlock account database: Off

      aad saml 20180912 11
    4. Click Save.

Test logging into Twistlock Console via Azure Active Directory SAML federation. Leave your existing session logged onto Twistlock Console in case you encounter issues. Open a new in-private browser and go to https://<FQDN_of_your_Twistlock_Console>:8083.

2.2.2. Twistlock Groups to AAD Group mapping

When you use AAD Groups to assign roles within Twistlock you do not have to create a corresponding Twistlock account.

  1. Go to Manage > Authentication > Groups

  2. Click Add Group

  3. Enter the displayname of the AAD group

  4. Click the SAML group radio button

  5. Select the Twistlock role for the group

  6. Click Save

    aad saml 20180912 12
Azure Active Directory SAML response will send the user’s group membership as OIDs and not the name of the group. When a group is added, Twistlock Console will query the Microsoft Azure endpoints to determine the OID of the group entered. Ensure your Twistlock Console is able to reach https://login.windows.net/ and https://graph.windows.net

Test logging into Twistlock Console via Azure Active Directory SAML federation while leaving your existing session logged into Twistlock Console in case you encounter issues. Open a new in-private browser and goto https://<FQDN_of_your_Twistlock_Console>:8083

3. Troubleshooting

If you misconfigure the SAML integration parameters in Twistlock Console, you might get locked out from your Twistlock admin account. When you try logging into Twistlock Console to fix the configuration, you might be redirected to the Azure Active Directory login page.

The Twistlock Console provides the ability to logon with a local database account when SAML integration is enabled. An example of a Twistlock user is the default admin account created when you first install Twistlock.

To login with a Twistlock user account when SAML is enabled, add the URL fragment /#!/login to Console’s address. For example:

https://<CONSOLE_IPADDR | HOSTNAME>:8083/#!/login

Regular SAML users should log in with the address to Console’s front page:

https://<CONSOLE_IPADDR | HOSTNAME>:8083