1. Overview

SAML is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider.

  • ServiceProvider (SP) = Twistlock Console UI

  • IdentityProvider (IdP) = SiteMinder, ADFS, Okta, AzureAD, PING Federate, Shibboleth, etc.

SAML Federation is based upon HTTP redirections. This is used for browser based applications such as the Twistlock Console’s UI.

The SAML specification can be found here: http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf

In this article, we outline example SAML authentication requests and SAML responses, giving in detail explanation on what to look for in each. The aim is to help provide a guideline for troubleshooting SAML related issues with Twistlock.

2. Example SAML Authentication Request sent from Twistlock to ADFS IdP

<samlp:AuthnRequest
    AssertionConsumerServiceURL="https://console.lab.twistlock.com/api/v1/authenticate"
    Destination="https://saml-adfs.ad.lab.twistlock.com/adfs/ls"
    ID="_56f9f278-c1b1-ed6d-ecc8-c3ce057b2a09" IssueInstant="2019-04-15T20:19:12Z"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Version="2.0"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <saml:Issuer>pfox-twistlock</saml:Issuer>
    <samlp:RequestedAuthnContext Comparison="exact" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
        <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
        <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:federation:authentication:windows</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

2.1. Things to look for in the AuthnRequest

AssertionConsumerServiceURL

AssertionConsumerServiceURL="https://console.twistlock.com/api/v1/authenticate"

This is the endpoint the IdP will use to redirect the user’s browser back to Twistlock. This value can be controlled in the Manage > Authentication > SAML > "Console URL" settings. It is common to set this value when the Twistlock Console is behind a proxy such as OpenShift external router or an Istio Ingress Controller . The Twistlock code will add "/api/v1/authenticate" to the value you put in the field. If this value is not set, the Twistlock code will automatically generate this value. This value must match the IdP’s Twistlock SP configurations

Issuer

 <saml:Issuer>console-twistlock</saml:Issuer>

The identifier of the Twistlock Console. Every SAML IdP must have a unique identifier for all SPs. By default Twistlock will send the twistlock issuer. You can change this value in the Audience value in the Twistlock Console’s SAML settings.

AuthnContextClassRef

<samlp:RequestedAuthnContext Comparison="exact" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:federation:authentication:windows</saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

Requests the methods of authentication to occurs at the IdP. urn:federation:authentication:windows is for ADFS IdPs that support Windows Integrated Authentication. Some IdPs will not know how to process these values. For example, CA SiteMinder will error with a SAML Response of

<StatusMessage>The AuthnRequest with AuthnContexts is not supported!</StatusMessage>

In this case you will need to configure the SiteMinder IdP to ignore the AuthnContextClassRef values.

3. Example SAML Response from ADFS IdP to Twistlock

<samlp:Response Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
    Destination="https://console.lab.twistlock.com/api/v1/authenticate"
    ID="_3ac05c43-11b8-4fac-9063-0b0a5f83707f" InResponseTo="_56f9f278-c1b1-ed6d-ecc8-c3ce057b2a09"
    IssueInstant="2019-04-15T20:21:59.095Z" Version="2.0"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://console.lab.twistlock.com/adfs/services/trust</Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#_3ac05c43-11b8-4fac-9063-0b0a5f83707f">
                <ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>ppj1biegltD2D701NL9Of+xDctgdChV166ja9E2DqtQ=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>Mh9dAnyo2CY0kz+cah8KVwwu7ZSWXO6ubyPOBk7CjD6CVHPfR2OFJ2S3fM695/usCWYud2CwQsdd1DVCDsnnAqifkGZiabHH38bBa9Jdv3YdWs3hoz4nqQbFesdQGV5QjL54Ip19FxFWUAxt4bKpundfP2h8OikRjkoi24QLVzSIcvuH/vkvz/DP7vF6e+YCbzu6BJDPWXf3TzvO6Og1mx4URDw2kycy83CHsB0mMJm3cfvb39DSLlnE6EvR+msUqoTWuLw==</ds:SignatureValue>
        <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
                <ds:X509Certificate></ds:X509Certificate>
            </ds:X509Data>
        </KeyInfo>
    </ds:Signature>
    <samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>
    <Assertion ID="_d6029da5-a589" IssueInstant="2019-04-15T20:21:59.095Z"
        Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
        <Issuer>http://saml-adfs.ad.lab.twistlock.com/adfs/services/trust</Issuer>
        <Subject>
            <NameID>pfox</NameID>
            <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><SubjectConfirmationData InResponseTo="_56f9f278-c1b1-ed6d-ecc8-c3ce057b2a09"
                NotOnOrAfter="2019-04-15T20:26:59.095Z"
                Recipient="https://console.lab.twistlock.com/api/v1/authenticate"/></SubjectConfirmation>
        </Subject>
        <Conditions NotBefore="2019-04-15T20:21:59.095Z" NotOnOrAfter="2019-04-15T21:21:59.095Z">
            <AudienceRestriction>
                <Audience>console-twistlock</Audience>
            </AudienceRestriction>
        </Conditions>
        <AttributeStatement>
            <Attribute Name="groups">
                <AttributeValue>Domain Admins</AttributeValue>
                <AttributeValue>Domain Users</AttributeValue>
                <AttributeValue>TLAdmins</AttributeValue>
            </Attribute>
        </AttributeStatement>
        <AuthnStatement AuthnInstant="2019-04-15T20:21:59.032Z"
            SessionIndex="_d6029da5-a589-4559-beaf-b734f45fd452">
            <AuthnContext>
                <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthnContextClassRef>
            </AuthnContext>
        </AuthnStatement>
    </Assertion>
</samlp:Response>

3.1. Things to look for in the Response

Issuer

<Issuer>http://saml-adfs.ad.lab.twistlock.com/adfs/services/trust</Issuer>

Response Token’s Issuer value matches the Identity provider issuer value in the SAML settings for the ADFS IdP

ds:Signature

The SAML Response Token must be either Signed Response or Signed Response + Assertion The IdP’s signing certificate must be loaded into the Twistlock settings for the IdP in the X.509 Certificate field in Base64 format.

groups

<AttributeStatement>
    <Attribute Name="groups">
        <AttributeValue>Domain Admins</AttributeValue>
        <AttributeValue>Domain Users</AttributeValue>
        <AttributeValue>TLAdmins</AttributeValue>
    </Attribute>
</AttributeStatement>

Group mapping requires that the SAML Token must contain the groups claim. This can contain an array of group names and they will be compared against the SAML groups defined in Manage > Authentication > groups. This might require a custom claim .

NameID

<Subject>
    <NameID>pfox</NameID>
    <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><SubjectConfirmationData InResponseTo="_56f9f278-c1b1-ed6d"
        NotOnOrAfter="2019-04-15T20:26:59.095Z"
        Recipient="https://console.lab.twistlock.com/api/v1/authenticate"/></SubjectConfirmation>
</Subject>

The nameid attribute must be present and match a Twistlock SAML user name if group association is not used.