The Service Map for APM is here!

Single Sign On With SAML

This documentation assumes that you already have a SAML Identity Provider up and running.

Configuring SAML (Security Assertion Markup Language) for your Datadog account lets you and all your teammates log in to Datadog using the credentials stored in your organization’s Active Directory, LDAP, or other identity store that has been configured with a SAML Identity Provider.

Note: Created users must accept email verification in order for SAML to work.

Here’s a two-minute video walkthrough:

Configure SAML

If you are a Datadog Administrator, there is a Configure SAML option in the drop down menu that is accessed by hover over your username in the left-side navigation menu.

Saml Configure

That brings you to the SAML Single Sign On Configuration page:

  1. Upload the IdP Metadata from your SAML Identity provider by clicking the Choose File button.

    Saml choose file

    After you’ve chosen the file, click “Upload File”.

  2. Download Datadog’s Service Provider metadata to configure your IdP to recognize Datadog as a Service Provider.

  3. After you upload the IdP Meta-data and configure your IdP, enable SAML in Datadog by clicking the Enable button.

    saml enable

Once SAML is configured in Datadog and your IdP is set up to accept requests from Datadog, users can log in by using the Single Sign On URL that is shown in the Status box at the top of the SAML Configuration page.

Saml Enabled

The Single Sign On URL is also displayed on the Team page. Loading this URL initiates a SAML authentication against your IdP. Note that the URL isn’t displayed until SAML is enabled for your account.

Datadog Service Provider Details

  • Datadog supports the HTTP-POST binding for SAML2: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.
  • Datadog specifies urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress for the Format of the NameIDPolicy in Assertion Requests.
  • Assertions must be signed.
  • Assertions can be encrypted, but unencrypted assertions are accepted.
  • Datadog’s SP Metadata.

Setting Attributes

Attributes may be included with the Assertion. Datadog looks for 3 Attributes in the AttributeStatement:

  1. eduPersonPrincipalName: If specified, the eduPersonPrincipalName must correspond to the user’s Datadog username. The username is usually the user’s email address.
  2. sn: This is optional, and should be set to the user’s surname.
  3. givenName: This is optional, and should be set to the user’s first, or given name.

Datadog expects that Attributes use the URI NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:uri or the Basic NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:basic. The name used for each attribute depends on the NameFormat that your IdP uses.

If your IdP is configured to use the URI NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:uri:

  1. eduPersonPrincipalName: The IdP should set urn:oid: as the Name of the Attribute
  2. sn: The IdP should set urn:oid: as the Name of the Attribute
  3. givenName: The IdP should set urn:oid: as the Name of the Attribute

If your IdP is configured to use the Basic NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:basic:

  1. eduPersonPrincipalName: The IdP should set urn:mace:dir:attribute-def:eduPersonPrincipalName as the Name of the Attribute
  2. sn: The IdP should set urn:mace:dir:attribute-def:sn as the Name of the Attribute
  3. givenName: The IdP should set urn:mace:dir:attribute-def:givenName as the Name of the Attribute

If eduPersonPrincipalName exists in the AttributeStatement, the value of this attribute is used for the username. If eduPersonPrincipalName is not included in the AttributeStatement, the username is taken from the NameID in the Subject. The NameID must use the Format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

If sn and givenName are provided, they are used to update the user’s name in their Datadog profile.

Specific SAML IdP

For more information about configuring specific IdP’s, refer to the following Knowledge Base articles:

Additional Features

The following features can be enabled through the SAML Configuration dialog.

Just-in-Time (JIT) Provisioning

With Just-in-Time provisioning, a user is created within Datadog on the fly the first time they try to log in. This eliminates the need for administrators to manually create user accounts one at a time.

Some organizations might not want to invite all of their users to Datadog. If you would like to make changes to how SAML works for your account, contact support. It is up to the organization to configure their IdP to not send assertions to Datadog if they don’t want a particular user to access Datadog.

Administrators in accounts using SAML can also set the default role for new Just-in-Time users. The default role is Standard, but you can choose to add new JIT users as Read-Only or even Administrators.

saml JIT Default

IdP Initiated Login

When the Datadog url is loaded, the browser is redirected to the customer IdP where the user enters their credentials, then the IdP redirects back to Datadog. Some IdPs have the ability to send an assertion directly to Datadog without first getting an AuthnRequest (IdP Initiated Login).

After enabling the IdP Initiated Login feature (and waiting for caches to clear), you will need to get a new version of the SP Metadata. Your new SP Metadata will contain a different, organization-specific AssertionConsumerService endpoint to send assertions to.

If you do not use the updated SP Metadata, Datadog will not be able to associate the assertion with your organization and will display an error page with a message that the SAML response is missing the “InResponseTo” attribute.

Further Reading

Additional helpful documentation, links, and articles: