SAML/SSO

Summary

DCT can delegate authentication to a SAML 2.0 compatible Identity Provider (IdP) to achieve Single-Sign On (SSO). The IdP, such as Active Directory Federation Services, Azure Active Directory, PingFederate, Okta, or OneLogin, is the software that your IT team uses to manage user accounts. The IdP then enables SSO, which improves an organization’s security and eases user onboarding by allowing authentication with different applications using the same set of credentials.

DCT's implementation of SAML/SSO only enables web browser-based authentication. It cannot be used to authenticate with the API, DCT Toolkit, DevOps integrations, or other automation frameworks.

Optionally, SAML/SSO can be configured simultaneously with DCT’s other authentication methods, including LDAP/AD and Local. If configured correctly, all three authentication methods could authenticate the user with the same DCT account. This can be valuable if transitioning from a Local or LDAP/AD authorization model. Consult their respective documentation sets if interested in using those methods.

Architecture

There are two different types of IdP authentication workflows that DCT supports with SAML/SSO: IdP-initiated and SP-initiated.

IdP-initiated

This workflow inserts the Identify Provider up front in the user’s workflow. The user starts by logging in directly to the IdP’s portal and then finding their list of available applications within their organization. They then select the DCT application, and the authentication happens automatically.

SP-initiated

This workflow inserts the Identify Provider in the middle of the user’s workflow. The user starts by navigating to the DCT’s login page and clicks the login with SSO/SAML button. They are then redirected to the organization’s IdP where they log in. Once authenticated, they will be redirected back to DCT where they can then access the user interface.

Choosing a method

Both are equally valid and secure. Choose the workflow that aligns best with your organization's existing authentication workflows. If you are uncertain, then both can be configured simultaneously.

Requirements

• An Identity Provider that supports the SAML 2.0 WebSSO protocol.

• SAML 2.0 communicates with DCT via https. Each user’s web browser must be able to communicate with the IdP and DCT over port 443.

  • DCT and the IdP do not communicate directly.

• Ensure your IdP identifies records using a unique email address.

  • This identifier is managed by the SAML configuration’s `NameID` attribute.

• Recommended*DCT allows group membership to be retrieved from the IdP. On every account login, the user’s membership is retrieved from the IdP, and a login_groups tag is placed or updated on the account. If the login_groups tag matches the tag on any Access Group, the user will become assigned to that group and gain the associated permissions. This allows accounts to gain access in an automated way that reflects the defined IdP’s membership structure.

NOTE: If you are new to SSO/SAML configuration or want to better understand how the group membership mapping works, please reference this 11-minute video.

Configuration

Setting up SAML/SSO requires configuration changes both in the Identity Provider and DCT for trust to be established between both products. DCT Administrators will likely not be able to complete the first half of the setup without contacting their Identity Provider’s managing team.

Identity provider (IdP) setup

Contact your Identify Provider’s management team to gather and share the information in the table below. That team will configure a SAML integration for DCT. This integration might have different names depending on the IdP, such as a Relying Party Trust in ADFS or Application in Okta. Exact instructions are specific to the IdP, so it’s crucial you contact that team.

Once the IdP team creates the integration, they should provide the Delphix Administrator with the following information: Entity ID, XML Metadata string, and (optionally) the three Attribute Mapping values. These will be supplied in the following section.

DCT SAML/SSO setup

Next, the Delphix Administrator should log into DCT and navigate to the Admin > Authentication tab. Select the Edit button next to “SSO/SAML” and complete the form as follows:

• Enabled: Sets whether the SSO/SAML configuration is enabled.

• Auto-create Users: Allows DCT accounts to be automatically created if they have successfully authenticated with the IdP, but a matching account does not exist.

  • If disabled, Delphix Administrators must manually create an account where the DCT account’s email field matches the record’s NameID attribute (i.e. email address).

• Entity ID: This uniquely identifies the integration configured in the Identity Provider. It should match the Entity ID value provided above.

• Metadata: This is the large XML string that your Identity Provider team shares.

• Optional* Group, First Name, and Last Name Attributes: On account creation and login, the account will be dynamically updated based on the values retrieved from the IdP.

  • Specifying a Group Attribute value is critical if you wish to grant automatic access.

  • If you are uncertain of these values, contact your IdP team.

• Response Skew: The maximum difference in timestamps between the SAML response and DCT’s current time. Default is 120 seconds.

Once submitted, your users should be able to successfully login after authenticating with the IdP. Ensure your Access Groups have been successfully configured to grant the expected access. If you are struggling to assign accounts to Access Groups, see the Attributes mapping section below.

Advanced

SSO/SAML can be configured via the API’s saml-config PUT endpoint. See our API documentation for more information.

Example

url --location --request PUT 'https://<hostname>/v2/management/saml-config' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: application/json' \ 
--header 'Authorization: apk <your API key>' \ 
--data-raw '{ 
  "enabled": true, 
  "auto_create_users": true, 
  "metadata": "<json-escaped-idp-metata-xml-blob>", 
  "group_attr": "<groupsValue>",  
  "first_name_attr": "<firstNameValue>",  
  "last_name_attr": "<lastNameValue>", 
  "response_skew": 120 
}' 

NOTE: The IDP metadata must be JSON escaped. On a terminal with ./jq installed, this can be achieved with the following command: jq --slurp --raw-input <<< 'xml-metadata-here'

Attributes mapping

As explained above, the only required attribute in the SAML response (the message sent by the Identity Provider to DCT during login) is the NameId attribute which must be configured to a unique email address.

In addition to this, DCT allows for first name, last name, and group membership attributes to be included. The first and last names attributes will be stored as properties of the account object. For each group membership found in the SAML response attribute, an account tag is created with key=login_groups and value as the group name. These tags are protected (i.e cannot be modified within DCT) and can be securely used to control access groups membership.

To enable these optional attributes, specify them during the SSO/SAML configuration. If you are having trouble identifying these properties, contact your IdP team.

Advanced

Here is a sample SSO/SAML configuration where the First Name, Last Name, and Group Attributes are set:

curl --location --request PUT 'https://<hostname>/v2/management/saml-config' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: application/json' \ 
--header 'Authorization: apk <your API key>' \ 
--data-raw '{ 
  "enabled": true, 
  "auto_create_users": true, 
  "metadata": "<json-escaped-idp-metata-xml-blob>", 
  "first_name_attr": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", 
  "last_name_attr": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", 
  "group_attr": "http://schemas.xmlsoap.org/claims/Group" 
}' 

On configuration, the following sample SAML response is provided by the Identity Provider during account login:

<?xml version="1.0" encoding="UTF-8"?> 
<saml2:Assertion ID="id97923983167603821157180516" IssueInstant="2022-12-01T10:07:12.856Z" Version="2.0" 
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> 
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.idp-demo.com/exk1fupjwz1YcMo290h8</saml2:Issuer> 
    <saml2:Subject> 
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">john.doe@company.co</saml2:NameID> 
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> 
            <saml2:SubjectConfirmationData NotOnOrAfter="2022-12-01T10:12:12.857Z" Recipient="https://localhost/v2/saml/SSO"/> 
        </saml2:SubjectConfirmation> 
    </saml2:Subject> 
    <saml2:Conditions NotBefore="2022-12-01T10:02:12.857Z" NotOnOrAfter="2022-12-01T10:12:12.857Z"> 
        <saml2:AudienceRestriction> 
            <saml2:Audience>https://dct-demo.delphix.com</saml2:Audience> 
        </saml2:AudienceRestriction> 
    </saml2:Conditions> 
    <saml2:AuthnStatement AuthnInstant="2022-12-01T10:05:07.916Z" SessionIndex="id1669889232855.2084756273"> 
        <saml2:AuthnContext> 
            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef> 
        </saml2:AuthnContext> 
    </saml2:AuthnStatement> 
    <saml2:AttributeStatement> 
        <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 
            <saml2:AttributeValue 
                xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">John 
            </saml2:AttributeValue> 
        </saml2:Attribute> 
        <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 
            <saml2:AttributeValue 
                xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Doe 
            </saml2:AttributeValue> 
        </saml2:Attribute> 
        <saml2:Attribute Name="http://schemas.xmlsoap.org/claims/Group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 
            <saml2:AttributeValue 
                xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Dev-Team 
            </saml2:AttributeValue> 
            <saml2:AttributeValue 
                xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">QA 
            </saml2:AttributeValue> 
    </saml2:AttributeStatement> 
</saml2:Assertion> 

DCT will then take this response and automatically create or update an account with the following properties:

{ 
     "id": 94, 
     "username": "john.doe@company.co", 
     "firstName": "John", 
     "lastName": "Doe", 
     "email": "john.doe@company.co", 
     "tags": [ 
         { 
             "key": "login_groups", 
             "value": "Dev-Team" 
         }, 
         { 
             "key": "login_groups", 
             "value": "QA" 
         } 
     ] 
    } 

Troubleshooting

I’m not sure what SSO/SAML or IdP metadata or attribute properties to specify. Can Delphix help?

• Delphix can provide light guidance on the necessary properties. However, all attributes are highly dependent on your organization’s Identity Provider. Delphix is certified against the SAML 2.0 WebProtocol standard, but we do not have in-depth knowledge of the many implementing IdP applications. Your IdP’s managing team will be the best resource to help configure SSO/SAML.

Error Message: “There was an issue in SAML authentication: The assertion cannot be used before <timestamp>.”

• The above error message, which is accompanied by “com.coveo.saml.SamlException: The assertion cannot be used before <timestamp>” error in the application logs, indicates that DCT was not able to validate the timestamp of the authentication provided by the Identity Provider.

  This is usually due to the system clock of the machine running DCT being incorrectly configured. Consider using NTP to maintain the machine’s clock up to date.

On login or API access, our user received the following error message: “There was an error fetching data.”

• The above error message indicates that the current account does not have permission to view the data displayed on the page. Remember that, while DCT creates accounts automatically upon login when `auto_create_users` is enabled, by default accounts are created without any authorization and thus cannot see any data. Review the section above to see how SAML/SSO group membership can be assigned automatically at account creation.