Configure SAML single sign-on with Microsoft Entra ID

For a detailed explanation of Deep Security's implementation of the SAML standard, see About SAML single sign-on (SSO). For instructions on configuring it with other identity providers, see Configure SAML single sign-on.

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.

Who is involved in this process?

Typically, there are two people required to configure Deep Security Manager to use Microsoft Entra ID for SAML single sign-on (SSO): a Deep Security administrator and a Microsoft Entra ID administrator.

The Deep Security administrator must be assigned a Deep Security role with the SAML Identity Providers right set to either Full or to Custom with Can Create New SAML Identity Providers enabled.

The following table lists steps that must be performed to set up SAML single sign-on with Deep Security using Microsoft Entra ID.

Step	Performed by
Configure Deep Security as a SAML service provider	Deep Security administrator
Download the Deep Security service provider SAML metadata document	Deep Security administrator
Configure Microsoft Entra ID	Microsoft Entra ID administrator
Configure SAML in Deep Security	Deep Security administrator
Define a role in Microsoft Entra ID	Microsoft Entra ID administrator

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.

Download the Deep Security service provider SAML metadata document

In Deep Security Manager, go to Administration > User Management > Identity Providers > SAML and click Download. The file is downloaded as ServiceProviderMetadata.xml. Send the file to your Microsoft Entra ID administrator.

Configure Microsoft Entra ID

The steps in this section are performed by a Microsoft Entra ID administrator.

Refer to Configure single sign-on to non-gallery applications in Microsoft Entra ID for details on how to perform the steps below.

In the Microsoft Entra ID portal, add a new non-gallery application.
Configure single sign-on for the application. We recommend that you upload the metadata file, ServiceProviderMetadata.xml, that was downloaded from Deep Security Manager. Alternatively, you can enter a reply URL (the Deep Security Manager URL + /saml).
Configure SAML claims. Deep Security requires these two:
- https://deepsecurity.trendmicro.com/SAML/Attributes/RoleSessionName
  This is a unique user ID that will be the username in Deep Security. For example, you could use the User Principal Name (UPN).
- https://deepsecurity.trendmicro.com/SAML/Attributes/Role
  The format is "IDP URN,Role URN". The IDP has not been created in Deep Security Manager yet, so you can configure this SAML claim later, in Define a role in Microsoft Entra ID.
You can also configure other optional claims, as described in SAML claims structure.
Download the Federation Metadata XML file and send it to the Deep Security administrator.

If there are multiple roles defined in Deep Security, repeat these steps to create a separate application for each role.

Configure SAML in Deep Security

Import the Microsoft Entra ID metadata document

In Deep Security Manager, go to Administration > User Management > Identity Providers > SAML.
Click Get Started or New.
Click Choose File, select the Federation Metadata XML file that was downloaded from Microsoft Entra ID 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

Make sure the Administration > User Management > Roles page in Deep Security contains appropriate roles for your organization. Users should be assigned a role that limits their activities to only those necessary for the completion of their duties. For information on how to create roles, see Define roles for users. Each Deep Security role requires a corresponding Microsoft Entra ID application.

Get URNs

In Deep Security Manager, gather this information, which you will need to provide to your Microsoft Entra ID administrator:

The identity provider URN. To view identity provider URNs, go to Administration > User Management > Identity Providers > SAML > Identity Providers and check the URN column.
The URN of the Deep Security role to associate with the Microsoft Entra ID application. To view role URNs, go to Administration > User Management > Roles and check the URN column. If you have multiple roles, you will need the URN for each role, because each one requires a separate Microsoft Entra ID enterprise application.

Define a role in Microsoft Entra ID

The steps in this section must be performed by a Microsoft Entra ID administrator.

In Microsoft Entra ID, use the identity provider URN and role URN identified in the previous section to define the "role" attribute in the enterprise application. This must be in the format "IDP URN,Role URN". See "Deep Security user role (required)" in the SAML claims structure section.

Use the Validate button in Microsoft Entra ID to test the setup, or assign the new application to a user and test that it works.

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.

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>