Many organizations use SAML to authenticate users for web services. Twistlock supports the SAML 2.0 federation protocol for access to the 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 Active Directory Federation Service (ADFS) Identity Provider (IdP).
Twistlock supports SAML 2.0 federation with Windows Server 2016 and Windows Server 2012r2 Active Directory Federation Services via the SAML protocol. The federated workflow is as follows:
The user browses to the Twistlock Console.
The browser is redirected to ADFS SAML2.0 endpoint.
The user authenticates either via Windows Integrated Authentication or Forms Based Authentication. Multi-factor authentication can be enforced at this step in the workflow.
The ADFS SAML token is returned to the Twistlock Console.
The Twistlock Console validates the ADFS SAML token’s signature and associates the user to their Twistlock account.
The Twistlock Console is integrated with ADFS as a federated SAML Relying Party Trust.
The Relying Party trust workflows may differ slightly between Windows Server 2016 and Windows Server 2012r2 ADFS, but the concepts are the same. |
This guide assumes you have already deployed Active Directory Federation Services, and Active Directory is the claims provider for the service.
Log onto your Active Directory Federation Services server.
Go to Server Manager > Tools > AD FS Management to start the ADFS snap-in.
Go to AD FS > Service > Certificates and click on the Primary Token-signing certificate.
Select the Details tab, and click Copy to File….
Save the certificate as a Base-64 encoded X.509 (.CER) file. You will upload this certificate into the Twistlock console in a later step.
Go to AD FS > Relying Party Trusts.
Click Add Relying Party Trust from the Actions menu.
Step Welcome: select Claims aware.
Step Select Data Source: select Enter data about the relying party manually.
Step Specify Display Name: In Display Name, enter twistlock Console.
Step Configure Certificate: leave blank.
Step Configure URL: select Enable support for the SAML 2.0 WebSSO protocol. Enter the URL for your Twistlock Console https://<FQDN_TWISTLOCK_CONSOLE>:8083/api/v1/authenticate/
Step Configure Identifiers: for example enter twistlock all lower case and click Add.
Step Choose Access Control Policy: this is where you can enforce multi-factor authentication for Twistlock Console access. For this example, select Permit everyone.
Step Ready to Add Trust: no changes, click Next.
Step Finish: select Configure claims issuance policy for this application then click Close.
In the Edit Claim Issuance Policy for Twistlock Console click Add Rule.
Step Choose Rule Type: In Claim rule template, select Send LDAP Attributes as Claims.
Step Configure Claim Rule:
Set Claim rule name to Twistlock Console
Set Attribute Store to Active Directory
In Mapping of LDAP attributes to outgoing claim types, set the LDAP Attribute to SAM-Account-Name and Outgoing claim type to Name ID.
The user’s Active Directory attribute returned in the claim must match the Twistlock user’s name. In this example we are using the samAccountName attribute. |
Click Finish.
Configure ADFS to either sign the SAML response (-SamlResponseSignature MessageOnly) or the SAML response and assertion (-SamlResponseSignature MessageAndAssertion) for the Twistlock Console relying party trust. For example to configure the ADFS to only sign the response, start an administrative PowerShell session and run the following command:
set-adfsrelyingpartytrust -TargetName "Twistlock Console" -SamlResponseSignature MessageOnly
You can use Active Directory group membership to assign users to Twistlock roles. When a user’s group membership is sent in the SAML response, Twistlock attempts to associate the user’s group to a Twistlock role. If there is no group association, Twistlock matches the user to an identity based on the NameID to Twistlock username mapping. The SAML group to Twistlock role association does not require the creation of a Twistlock user. Therefore simplify the identity management required for your implementation of Twistlock.
In Relying Party Trusts, select the Twistlock Console trust.
Click Edit Claim Issuance Policy in the right hand Actions pane.
Click Add Rule.
Claim rule template: Send Claims Using a Custom Rule.
Click Next.
Claim rule name: Twistlock Groups.
Paste the following claim rule into the Custom rule field:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("groups"), query = ";tokenGroups;{0}", param = c.Value);
Login to the Twistlock Console as an administrator.
Go to Manage > Authentication > SAML.
Under SAML settings:
Integrate SAML users and groups with Twistlock: Enabled.
Identity Provider: ADFS.
Identity provider single sign-on URL: Enter your SAML Single Sign-On Service URL. For example https://FQDN_of_your_adfs/adfs/ls.
Identity provider issuer: Enter your SAML Entity ID, which can be retrieved from ADFS > Service > Federation Service Properties : Federation Service Identifier.
Audience: Enter the ADFS Relying Party identifier twistlock
X.509 certificate: paste the ADFS Token Signing Certificate Base64 into this field.
Click Save.
Go to Manage > Authentication > Users.
Click Add user.
Username: Active Directory samAccountName must match the value returned in SAML token’s Name ID attribute.
When federating with ADFS Twistlock usernames are case insensitive. All other federation IdPs are case sensitive. |
Auth method: set to SAML.
Role: select an appropriate role.
Click Save.
Associate a user’s Active Directory group membership to a Twistlock role.
Go to Manage > Authentication > Groups.
Click Add group.
Group Name matches the Active Directory group name.
Select the SAML group radio button.
Assign the Role.
The SAML group to Twistlock role association does not require the creation of a Twistlock user. |
Test login into the Twistlock Console via ADFS SAML federation while leaving your existing session logged onto the Twistlock Console in case you encounter issues. Open a new in-private browser and go to https://<FQDN_TWISTLOCK_CONSOLE>:8083.
There is a little trial and error when configuring federation. If you misconfigure the SAML integration parameters in Twistlock Console, you might get locked out from your Twistlock admin account. When you try to log into the Twistlock Console to fix the configuration, you might be redirected to the ADFS 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