Configure SAML single sign-on

Views:

When you configure Deep Security to use SAML single sign-on (SSO), users signing in to your organization's portal can seamlessly sign in to Deep Security without an existing Deep Security account. SAML single sign-on also makes it possible to implement user authentication access control features such as:

Password strength or change enforcement.
One-Time Password (OTP).
Two-Factor Authentication (2FA) or Multi-Factor Authentication (MFA).

For a more information on the Deep Security's implementation of the SAML standard, see How SAML single sign-on works. If you are using Microsoft Entra ID as your identity provider, see Configure SAML single sign-on with Microsoft Entra ID.

Note

Currently, Deep Security supports only the HTTP POST binding of the SAML 2.0 identity provider (IdP)-initiated login flow, and not the service provider (SP)-initiated login flow

To use SAML single sign-on with Deep Security, you need to do the following:

Configure pre-setup requirements
Configure Deep Security as a SAML service provider
Configure SAML in Deep Security
Provide information for your identity provider administrator
SAML claims structure
Test SAML single sign-on
Service and identity provider settings

Configure pre-setup requirements

Ensure your Deep Security Manager is functioning properly.
Contact the identity provider administrator to:
- Establish a naming convention for mapping directory server groups to Deep Security roles.
- Obtain their identity provider SAML metadata document.
- Ask them to add any required user authentication access control features to their policy.

Support is available to assist with the following identity providers that have been tested in Deep Security with SAML single sign-on:

Active Directory Federation Services (ADFS)
Okta
PingOne
Shibboleth
Microsoft Entra ID

Configure Deep Security as a SAML service provider

First, set up Deep Security as a service provider.

In multi-tenant Deep Security installations, only the primary tenant administrator can configure Deep Security as a SAML service provider.

In Deep Security Manager, go to Administration > User Management > Identity Providers > SAML.
Click Get Started.
Enter an Entity ID and a Service Name, and then click Next.

The Entity ID is a unique identifier for the SAML service provider. The SAML specification recommends that the entity ID is a URL that contains the domain name of the entity, and industry practices use the SAML metadata URL as the entity ID. The SAML metadata is served from the /saml endpoint on the Deep Security Manager, so an example value might be https://<DSMServerIP:4119>/saml.
Select a certificate option, and click Next. The SAML service provider certificate is not used at this time, but would be used in the future to support service-provider-initiated login or single sign-out features. You can import a certificate by providing a PKCS #12 keystore file and password, or create a new self-signed certificate.
Follow the steps until you are shown a summary of your certificate details and then click Finish.

Configure SAML in Deep Security

Import your identity provider's SAML metadata document

Note

Your Deep Security account must have both administrator and "Create SAML identity provider" permissions.

On the Administration page, go to User Management > Identity Providers > SAML.
Click Get Started.
Click Choose File, select the SAML metadata document provided by your identity provider, and click Next.
Enter a Name for the identity provider, and then click Finish.

You will be brought to the Roles page.

Create Deep Security roles for SAML users

You need to create a role for each of your expected user types. Each role must have a corresponding group in your identity provider's directory server, and match the group's access permissions and tenant assignment.

Your identity provider's SAML integration will have a mechanism to transform group membership into SAML claims. Consult the documentation that came with your identity provider to learn more about claim rules.

For information on how to create roles, see Define roles for users.

Provide information for your identity provider administrator

Download the Deep Security Manager service provider SAML metadata document

On the Administration page, go to User Management > Identity Providers > SAML.
Under SAML Service Provider, click Download.Your browser will download the Deep Security service provider SAML metadata document (ServiceProviderMetadata.xml).

Send URNs and the Deep Security SAML metadata document to the identity provider administrator

You need to give the identity provider administrator Deep Security's service provider SAML metadata document, the identity provider URN and the URN of each Deep Security role you created.

Tip

To view role URNs, go to Administration > User Management > Roles and look under the URN column.

To view identity provider URNs, go to Administration > User Management > Identity Providers > SAML > Identity Providers and look under the URN column.

Once the identity provider administrator confirms they have created groups corresponding to the Deep Security roles and any required rules for transforming group membership into SAML claims, you are done with configuring SAML single sign-on.

Note

If necessary, you can inform the identity provider administrator about the SAML claims structure required by Deep Security.

SAML claims structure

The following SAML claims are supported by Deep Security:

Deep Security user name (required)
Deep Security user role (required)
Maximum session duration (optional)
Preferred language (optional)

Deep Security user 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. The Deep Security Manager will use the AttributeValue as the Deep Security user name.

Sample SAML data (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>

Deep Security user 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. The Deep Security Manager uses the attribute value(s) to determine the tenant, identity provider, and role of the user. A single assertion may contain roles from multiple tenants.

The AttributeValue contains two URNs, separated by a comma. The URNs are case sensitive.

Sample SAML data (abbreviated)

The line break in the AttributeValue element is present for readability; in the claim it must be on a single line.

<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>urn:tmds:identity:[pod ID]:[tenant ID]:saml-provider/[IDP name],
            urn:tmds:identity:[pod ID]:[tenant ID]:role/[role name]</AttributeValue>
      </Attribute>
    </AttributeStatement>
  </Assertion>
</samlp:Response>

Maximum session duration (optional)

If the claim has a SAML assertion that contains an Attribute element with a Name attribute of https://deepsecurity.trendmicro.com/SAML/Attributes/SessionDuration and an integer-valued AttributeValue element, the session will automatically terminate when that amount of time (in seconds) has elapsed.

Sample SAML data (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/SessionDuration">
        <AttributeValue>28800</AttributeValue>
      </Attribute>
    </AttributeStatement>
  </Assertion>
</samlp:Response>

Preferred language (optional)

If the claim has a SAML assertion that contains an Attribute element with the Name attribute of https://deepsecurity.trendmicro.com/SAML/attributes/PreferredLanguage and a string-valued AttributeValue element that is equal to one of the supported languages, the Deep Security Manager will use the value to set the user's preferred language.

The following languages are supported:

en-US (US English)
ja-JP (Japanese)

Sample SAML data (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/PreferredLanguage">
        <AttributeValue>en-US</AttributeValue>
      </Attribute>
    </AttributeStatement>
  </Assertion>
</samlp:Response>

Test SAML single sign-on

Navigate to the single sign-on login page on the identity provider server, and log in to the Deep Security Manager from there. You should be redirected to the Deep Security Manager console. If SAML single sign-on is not functioning, follow the steps below:

Review the set-up

Review the Configure pre-set up requirements section.
Ensure that the user is in the correct directory group.
Ensure that the identity provider and role URNs are properly configured in the identity provider federation service.

Create a Diagnostic Package

Go to Administration > System Information and click Diagnostic Logging.
Select SAML integration Issues and click Save.
Generate logs. Replicate the issue by logging in to the Deep Security Manager through your identity provider.
After the login fails, generate a diagnostic package by navigating to Administration > System Information and clicking on Create Diagnostic Package.
Once the diagnostic package has been created, navigate to https://success.trendmicro.com to open a Technical Support Case, and upload the diagnostic package during the case creation.

Service and identity provider settings

You can set how far in advance Deep Security will alert you to the expiry date of the server and identity provider certificates, as well as how much time must pass before inactive user accounts added through SAML single sign-on are automatically deleted.

To change these settings, go to Administration > System Settings > Security > Identity Providers.