Implement SAML single sign-on

When you enable SAML single sign-on in Deep Security Smart Check, users in your organization can sign in to Deep Security Smart Check with their existing organization account. You can also use your identity provider to implement user authentication access control features like:

• password strength or change enforcement
• one-time passwords (OTP)
• two-factor or multi-factor authentication (2FA / MFA)

At this time, Deep Security Smart Check supports only the HTTP POST binding of the SAML 2.0 identity provider-initiated login flow, and does not support the service provider-initiated login flow.

To use SAML single sign-on with Deep Security Smart Check:

1. Configure Deep Security Smart Check as a SAML service provider
2. Configure Deep Security Smart Check to trust your identity provider
3. Configure Deep Security Smart Check as a service provider in your identity provider

Configure Deep Security Smart Check as a SAML service provider

If your Deep Security Smart Check service is available at smartcheck.example.com, you can enable SAML by adding the following settings to your overrides.yaml file and performing a helm upgrade to apply the new settings.

auth:
  saml:
    enabled: true
    location: smartcheck.example.com

helm upgrade \
  --values overrides.yaml \
  deepsecurity-smartcheck \
  https://github.com/deep-security/smartcheck-helm/archive/master.tar.gz

In this example we assume that Deep Security Smart Check is installed as deepsecurity-smartcheck and that you are using the latest software release. You may need to modify this command to suit your needs.

Configure Deep Security Smart Check to trust your identity provider

Automatic provisioning of the identity provider entry with a metadata URL

It's easiest if Deep Security Smart Check can reach out to your identity provider directly for the metadata it needs. If your identity provider is located at identity.example.com, you can configure Deep Security Smart Check to trust your identity provider with the following API request:

curl -X POST \
  https://smartcheck.example.com/api/identity-providers/saml \
  -H 'Authorization: Bearer [token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "IdentityProvider",
    "description": "My SAML identity provider. Contact identity@example.com for support.",
    "metadataURL": "identity.example.com"
  }'

Deep Security Smart Check will periodically refresh the identity provider metadata from the URL.

If your identity provider uses a certificate issued by a private certificate authority, you may need to provide the certificate authority's root certificate to establish trust. See the Deep Security Smart Check API documentation for details.

Manual provisioning of the identity provider entry with metadata XML

If your identity provider is not reachable from Deep Security Smart Check, you can retrieve the SAML metadata from the identity provider, encode it using Base-64, and include it in the API request:

curl -X POST \
  https://smartcheck.example.com/api/identity-providers/saml \
  -H 'Authorization: Bearer [token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "IdentityProvider",
    "description": "My SAML identity provider. Contact identity@example.com for support.",
    "metadataXML": "[Base64-encoded metadata XML]"
  }'

Deep Security Smart Check will not be able to refresh the identity provider metadata without the URL, so you will need to periodically update the identity provider record to keep it in sync with any changes at the identity provider.

Configure Deep Security Smart Check as a service provider in your identity provider

Your identity provider administrator will need to provision Deep Security Smart Check as a service provider (also known as a relying party) and configure claims transforms to send the session name and role in SAML assertions.

Automatic provisioning of the service provider entry with a metadata URL

It's easiest if your identity provider can reach out to Deep Security Smart Check directly for the metadata it needs. If Deep Security Smart Check is located at smartcheck.example.com, you can use the URL https://smartcheck.example.com/saml as the metadata URL when configuring Deep Security Smart Check as a service provider.

Manual provisioning of the service provider entry with metadata XML

If Deep Security Smart Check is located at smartcheck.example.com, you can use the URL https://smartcheck.example.com/saml to retrieve the service provider metadata XML. You can then provide the service provider metadata XML to your identity provider administrator for use when configuring Deep Security Smart Check as a service provider.

Claim reference

Session name (required)

The claim must have a SAML assertion that contains an Attribute element with a Name attribute of https://deepsecurity.trendmicro.com/SAML/Attributes/RoleSessionName and a single AttributeValue element. Deep Security Smart Check will use the AttributeValue as the session name.

Typically, the session name is derived from the user name or email address in the identity provider.

Sample SAML data for role session name (abbreviated)

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
  <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
    <AttributeStatement>
      <Attribute Name="https://deepsecurity.trendmicro.com/SAML/Attributes/RoleSessionName">
        <AttributeValue>alice</AttributeValue>
      </Attribute>
    </AttributeStatement>
  </Assertion>
</samlp:Response>

Role (required)

The claim must have a SAML assertion that contains an Attribute element with a Name attribute of https://deepsecurity.trendmicro.com/SAML/Attributes/Role and between one and ten AttributeValue elements. Deep Security Smart Check uses the attribute value(s) to determine the role assigned to the session. If multiple roles are asserted, Deep Security Smart Check will require the user to select one of the asserted roles before starting the session.

Typically, the role name is derived from the user's group membership in the identity provider.

Sample SAML data for role (abbreviated)

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
  <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
    <AttributeStatement>
      <Attribute Name="https://deepsecurity.trendmicro.com/SAML/Attributes/Role">
        <AttributeValue>auditor</AttributeValue>
      </Attribute>
    </AttributeStatement>
  </Assertion>
</samlp:Response>

If you're familiar with the SAML attribute format for Workload Security, you may notice that the user role attribute format is simpler in Deep Security Smart Check.