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:
The user browses to Twistlock Console.
The browser is redirected to AAD SAML2.0 endpoint.
The user enters their AAD credentials.
The AAD SAML token is returned to Twistlock Console.
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. |
The Twistlock Console is integrated with Azure Active Directory as a federated SAML Enterprise Application.
Configure Azure Active Directory.
Required Azure Active Directory SKU: Premium
Required Azure Active Directory role: Global Administrator
Log onto your Azure Active Directory tenant (https://portal.azure.com).
Go to Azure Active Directory > Enterprise Applications
On the top left of the window pane, click + New Application.
Select Non-gallery application, from the Add your own app section.
In the Name field, enter pfox-console, then click Add. In this example I am using "pfox-console."
On the pfox-console menu select Single sign-on and choose SAML-based Sign-on
Section #2 Domain and URLs:
Identifier: pfox-console (Set to your Console’s unique Audience value. You will configure this value within your Console at a later step.)
Reply URL: https://<FQDN_of_your_Twistlock_Console>:8083/api/v1/authenticate
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.
User Identifier: user.principalname
Even if you are using AAD Groups to assign access to Twistlock set this value. |
Select Show Advanced certificate signing settings.
Set Signing Option: Sign SAML Response.
Section #4 SAML Signing Certificate:
Select Download: Certificate (Base64)
Select Show Advanced certificate signing settings
Set Signing Option: Sign SAML Response
Section #5 Configure pfox_console:
Click on the pfox-console Configuration section
Save the values of SAML Single Sign-On Service URL and SAML Entity ID
Then close the blade.
Click Save
Make sure to copy the Application’s ID.
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.
If you plan to map Azure Active Directory users to Twistlock accounts go to Configure Twistlock Console.
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.
Set Application permissions:
In Azure go to Azure Active Directory > Application Registrations > pfox-console
Click on settings
Click on Required permissions
Select Add
Click on Select an API: Windows Azure Active Directory
Select permissions: Application Permissions: Read directory data
Click save
Click Grant permission within the Required permissions blade.
Create Application Keys
Click on the application’s settings and select Keys
Add a key description
Duration: Never expires
Click save
Make sure to save the key value that is generated before closing the blade.
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.
Azure AD Portal:
Go to Azure Active Directory > App registrations > pfox-console
Click Manifest
Set "groupMembershipClaims": "SecurityGroup"
Click Save
Powershell:
Use the Azure AD powershell commandlet Set-AzureADApplication to configure the application.
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
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. |
Login to Twistlock Console as an administrator.
Integrate SAML users and groups with Twistlock: Enabled.
Identity Provider: Azure
Identity provider single sign-on URL: Azure AD provided SAML Single Sign-On Service URL
Identity provider issuer: Azure AD provided SAML Entity ID
Audience: pfox-console
Application ID: pfox-console’s AAD application ID
Tenant ID: AAD tenant ID that contains the pfox-console application
Application Secret: pfox-console application keys (only required if using AAD Groups)
X.509 certificate: paste Azure AD SAML Signing Certificate Base64 into this field
Click Save
If you plan to map Azure Active Directory users to Twistlock accounts perform the following steps.
Go to Manage > Authentication > Users
Click Add user
Create a New User
Username: Azure Active Directory userprincipalname
Role: select appropriate role
Create user in local Twistlock account database: Off
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.
When you use AAD Groups to assign roles within Twistlock you do not have to create a corresponding Twistlock account.
Go to Manage > Authentication > Groups
Click Add Group
Enter the displayname of the AAD group
Click the SAML group radio button
Select the Twistlock role for the group
Click Save
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
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