1. Overview

Many organizations use SAML to authenticate users for web services. Twistlock supports the SAML 2.0 federation protocol to access 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 PingFederate v8.4 Identity Provider (IdP).

The Twistlock/PingFederate SAML federation flow works as follows:

  1. User browses to the Twistlock Console.

  2. Browser is redirected to PingFederate SAML2.0 endpoint.

  3. User enters their credentials.

  4. PingFederate SAML token is returned to the Twistlock Console.

  5. Twistlock Console validates the PingFederate SAML token’s signature and associates the user to their Twistlock account.

  6. User is directed to the Console Authentication page (Manage > Authentication > Certificates), and is prompted to download their certificate. Group memberships for the user are embedded in the certificate.

  7. Using this certificate, user runs a Docker client command on a host protected by Defender.

  8. 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.

    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. 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. Federation with PingFederate

Twistlock Console is integrated with PingFederate as a federated SAML Service Provider.

2.1. Configure PingFederate

Procedure

  1. Logon to PingFederate

  2. Go to IdP Configuration > SP Connection > Connection Type, and select Browser SSO.

    ping saml step2
  3. Go to IdP Configuration > SP Connection > Connection Options, and select Browser SSO Profiles SAML 2.0.

    ping saml step3
  4. Skip the Import Metadata tab.

  5. Go to IdP Configuration > SP Connection > General Info.

    1. In Partner’s Entity ID, enter twistlock.

      By default, the Partner’s Entity ID is "twistlock". When configuring the SAML Audience in the Twistlock Console, the default value is "twistlock". If you choose a different value here, be sure to set the same value in your Console.
    2. In Connection Name, enter Twistlock Console.

    3. Click Add.

      ping saml step5
  6. In Browser SSO > SAML Profiles, select both IDP-INITIATED SSO and SP-INITIATED SSO.

    ping saml step6
  7. Go to Assertion Creation and set SAML_SUBJECT to SAML 1.1 nameid-format.

    In this example you mapped the user’s email address to the SAML_SUBJECT attribute which matches the user’s Twistlock account. If you are using group-to-Twistlock-role associations, add groups to the list of attributes to be returned in the SAML token.

    ping saml step7
  8. In IdP Configuration > SP Connection > Browser SSO > Protocol Settings > Assertion Consumer Service URL, specify an assertion consumer URL.

    1. Under Binding, select POST.

    2. Under Endpoint URL, enter https://<FQDN_OF_YOUR_TWISTLOCK_CONSOLE>:8083/api/v1/authenticate.

      ping saml step8
  9. In IdP Configuration > SP Connection > Browser SSO > Protocol Settings > Signature Policy, leave both values unchecked.

    ping saml step9
  10. In IdP Configuration > SP Connection > Browser SSO > Protocol Settings, review the protocol settings.

    ping saml step10
  11. Click Done.

  12. Copy the PingFederate SAML token signing X.509 certificate as Base64 in Server Configuration. This certificate will be imported into Twistlock Console.

2.2. Configure the Twistlock Console

Procedure

  1. Login to the Twistlock Console as an administrator.

  2. Go to Manage > Authentication > SAML.

    1. Set Integrate SAML users and groups with Twistlock to Enabled.

    2. Set Identity Provider to Ping.

    3. In Identity provider single sign-on URL, enter your PingFederate IdP endpoint.

    4. In Identity provider issuer, enter your PingFederate Entity ID.

    5. In Audience, enter twistlock (default) or the value set for Partner’s Entity ID in PingFederate.

    6. In X.509 certificate, paste your PingFederate X.509 Signing Certificate Base64.

      ping saml step11
  3. Click Save.

User account name matching
  1. Go to Manage > Authentication > Users.

  2. Click Add user.

  3. Create a new user:

    1. In Username, enter the value returned within the SAML_SUBJECT attribute IdP user’s email address.

    2. In Role, select the appropriate role.

    3. Set Create user in local Twistlock account database to Off.

      ping saml step12
  4. Click Save.

Group name matching
  1. Go to Manage > Authentication > Groups.

  2. Click the +Add Group button.

  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.

    ping saml step13
  5. Click Save

Test login into the Twistlock Console via PingFederate 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_OF_YOUR_TWISTLOCK_CONSOLE>:8083

3. Troubleshooting

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 PingFederate 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