Getting started with SAML single sign-on

When you configure Deep Security to use SAML single sign-on, 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 detailed explanation of Deep Security's implementation of the SAML standard, see Implement SAML single sign-on.

At this time, 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 will need to do the following:

1. Configure pre-set up requirements
2. Configure Deep Security as a SAML service provider
3. Configure SAML in Deep Security
4. Provide information for your identity provider administrator
5. SAML claims structure
6. Test SAML single sign-on
7. Service and identity provider settings

Configure pre-set up requirements

1. Ensure your Deep Security Manager is functioning properly.
2. 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

Configure Deep Security as a SAML service provider

As the first step in the SAML single sign-on configuration, you will need to set up Deep Security as a service provider.

For a more detailed explanation of Deep Security's implementation of the SAML standard, see Implement SAML single sign-on.

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

1. On the Administration page, go to User Management > Identity Providers > SAML.
2. Click Get Started.

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

4. Select a certificate option, and click Next. The 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. When creating the service provider, you can import a certificate and private key or create a new self-signed certificate and private key.

Import a Certificate and Private Key

1. Click Choose File and open the PKCS #12 keystore file containing your certificate.
2. Enter the password for the keystore.

3. Click Next.

   You will be shown a summary of your certificate details.

4. Click Finish.

Generate a new self-signed server certificate

1. Enter the following details for your certificate:
   • Common Name (CN)
   • Organization (O)
   • Organizational Unit (OU)
   • Email Address (E)

2. Click Next.

   You will be shown a summary of your certificate details.

3. Click Finish.

Keep the current Server Certificate

1. Click Next, and then click Finish.

Deep Security is now set up as a SAML service provider.

Configure SAML in Deep Security

Import your identity provider's SAML metadata document

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

1. On the Administration page, go to User Management > Identity Providers > SAML.
2. Click Get Started.
3. Click Choose File, select the SAML metadata document provided by your identity provider, and click Next.

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

1. On the Administration page, go to User Management > Identity Providers > SAML.
2. 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.

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.

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.

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)
• zh-CN (Simplified Chinese)

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

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

Create a Diagnostic Package

1. Go to Administration > System Information and click Diagnostic Logging.
2. Select SAML integration Issues and click Save.
3. Generate logs. Replicate the issue by logging in to the Deep Security Manager through your identity provider.
4. After the login fails, generate a diagnostic package by navigating to Administration > System Information and clicking on Create Diagnostic Package.
5. 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.