1. Overview

Twistlock supports user authentication using SAML. Many organizations use SAML to authenticate users for web services.

When SAML support is enabled, administrators can log into Console with their federated credentials. They do not need to first set up a separate account in Twistlock. With SAML users and groups, admins can create granular access control rules that allow or deny specific actions against specific resources for specific users and groups.

For example, an administrator could create an access control rule called “Production read-only” that limits the SAML group “Test Team” to run just the docker ps, docker stats, and docker inspect commands on any host named prod*. When this rule is activated, users that are part of the Test Team group can only run these Docker client commands on production hosts. All other commands are blocked.

Twistlock’s internal processing for SAML access control rules is as follows:

  1. A user accesses Console.

  2. She is prompted to submit her credentials.

  3. The SAML authentication flow begins.

  4. Twistlock gets a response from the SAML Identity provider that:

    1. Validates the user’s credentials.

    2. Lists her group memberships.

  5. The user is directed to the Console access page (/configure/access/certificates), and she is prompted to download her certificate. Group memberships for the user are embedded in the certificate.

  6. Using her certificate, the user runs a Docker client command on a host protected by Defender.

  7. Defender uses the certificate to determine the user’s identity and group memberships. Defender allows or blocks the command, depending on the access policies specified in Console.

Note that Defender does not talk to the SAML IdP. Instead, it relies on the user certificate generated from the initial SAML authentication flow, when the user first tries to log into Console (see Step 1-5 above). The validity period for the certificate is controlled by the SAML IdP, which embeds the login expiration into the response.

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.

2. Integrating with SAML

Integrating Twistlock with SAML consists of setting up your IdP, then configuring Twistlock to integrate with it. In this article, we’ll use Okta as the IdP.

2.1. Setting up Twistlock in Okta

To set up Twistlock in Okta:

Procedure

  1. Log into the Okta admin dashboard.

  2. On the right, click Add Applications.

    integrate saml 610130
  3. On the left, click Create new app.

    integrate saml 610131
  4. Select SAML 2.0, and then click Create.

    integrate saml 610135
  5. In the App name field, enter Twistlock Console, then click Next.

    integrate saml 610136
  6. In the SAML Settings dialog:

    1. In the Single Sign On URL field, enter https://<CONSOLE_ADDR>:8083/api/v1/authenticate

      Note that if you’ve changed the default port you use for the HTTPS listener, you’d need to adjust the URL here accordingly. Additionally, this URL must be visible from the Okta environment, so if you’re in a virtual network or behind a load balancer, it must be configured to forward traffic to this port and it’s address is what should be used here.

    2. Select Use this for Recipient URL and Destination URL.

    3. In the field for Audience Restriction, enter twistlock (all lowercase).

    4. Expand Advanced Settings.

    5. Verify that Response is set to Signed.

    6. Verify that Assertion Signature is set to Signed.

      integrate saml 610140
  7. (Optional) Add a group.

    Setting up groups is optional. If you set up group attribute statements, then permission to access Twistlock is assessed at the group level. If you don’t set up group attribute statements, them permission to access Twistlock is assessed at the user level.

    1. Scroll down to the GROUP ATTRIBUTE STATEMENTS section.

    2. In the Name field, enter groups.

    3. In filter drop down menu, select Regex and enter a regular expression that captures all the groups defined in Okta that you want to use for access control rules in Twistlock.

      In this example, the regular expression .*(t|T)wistlock.* is used to include all groups prepended with either Twistlock or twistlock. You should enter your own desired group name here. If you have just one group, such as YourGroup, then just enter YourGroup. Regular expressions are not required. If you have multiple groups, you can use a regular expressions, such as (group1|group2|group3).

      integrate saml 610146
  8. Click Next, and then click Finish.

    You are directed to a summary page for your new app.

    integrate saml 610150
  9. Click on the People tab, and add users to the Twistlock app.

    integrate saml 610156
  10. Click on the Groups tab, and add groups to the Twistlock app.

    integrate saml 610160
  11. Click on the Sign On tab and click View setup instructions.

    The following values are used to configure Twistlock Console, so copy them and set them aside.

    • Identity Provider Single Sign-On URL

    • Identity Provider Issuer

    • X.509 Certificate

      integrate saml 610163

2.2. Configuring Console

To configure Console:

Procedure

  1. Open Console, and login as admin.

  2. Go to Manage > Authentication > SAML.

  3. Set Enabled to ON.

  4. Copy the following values from Okta and paste them into their corresponding fields in Console:

    • Identity Provider Single Sign-On URL

    • Identity Provider Issuer

    • X.509 Certificate

  5. Click Save.

    Do NOT log out of Console after this step without creating access rules (following the procedure listed below). If you log out now you will be redirected to authenticate via SAML without having a group yet, causing the login to fail.

2.3. Granting access by group

Grant access to Twistlock Console by group. Each group must be assigned a role. You can optionally use these groups to define RBAC rules for controlling who can run which Docker Engine commands in your environment.

Procedure

  1. Open Console.

  2. Define a SAML group.

    1. Go to Manage > Authentication > Groups.

    2. Click Add group.

    3. In the Name field, enter a group name.

      The group name must exactly match the group name in the SAML IdP. Console does not verify if that the value entered matches a group name in the SAML IdP.

    4. Select the SAML group checkbox.

    5. Select a role.

    6. Select a project(s) - Optional.

    7. Click Save.

2.4. Granting access by user

Grant access to Twistlock Console by user. Each user must be assigned a role. You can optionally use these user to define RBAC rules for controlling who can run which Docker Engine commands in your environment.

  1. Open Console.

  2. Define a SAML user.

    1. Go to Manage > Authentication > Users.

    2. Click Add user.

    3. In the Username field, enter a user name.

      The username must exactly match the username in the SAML IdP. Console does not verify if that the value entered matches a user name in the SAML IdP.

    4. Select SAML as the Auth method

    5. Select a role.

    6. Select a project(s) - Optional.

    7. Click Save.

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 to log into Console to fix the configuration, you might be redirected to the Okta login page.

Console has a back door that lets you log in with Twistlock users, not SAML users. An example of a Twistlock user is the default admin account created when you first install Twistlock.

To log in 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