Single Sign On With SAML

Single Sign On With SAML

The Datadog for Government site only supports SAML login.

Overview

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: If you don’t have SAML enabled on your Datadog account, reach out to support to enable it.

Here’s a two-minute video walkthrough:

Notes:

Configuring SAML

  1. To begin configuration, see your IdP’s documentation:

  2. If you’re a Datadog Administrator, you can access the Login Methods page and the SAML Configuration page. Hover over your username at the bottom of the left-side navigation menu and click Organization Settings.

  3. Upload the IdP Metadata from your SAML Identity provider by clicking the Choose File button. After choosing the file, click Upload File.

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

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

  6. Once SAML is configured in Datadog and your IdP is set up to accept requests from Datadog, users can log in:

    • If using SP-initiated login (Service Provider, or login initiated from Datadog): By using the Single Sign-on URL shown in the Status box at the top of the SAML Configuration page. The Single Sign-on URL is also displayed on the Team page. Loading this URL initiates a SAML authentication against your IdP. Note: This URL isn’t displayed unless SAML is enabled for your account and you are using SP-initiated login.

    • If using IdP-initiated login (Identity Provider, or login initiated from your app portal): By clicking on the app icon in your app portal, for example in the Google App drawer or the Okta App Portal. In some scenarios users logging in with the SP-initiated login URL will also work with the IdP-initiated login experiences, but this depends on your Identity Provider’s configuration and support.

Note: If you want to configure SAML for a multi-org, see Managing Multiple-Organization Accounts.

Assertions and attributes

When a login occurs, a SAML Assertion containing user authorization is sent from the identity provider to Datadog.

Some important notes on assertions:

  • 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.
  • Reference Datadog’s SP Metadata for more information.

Attributes may be included in a SAML Assertion. Datadog looks for three attributes in an AttributeStatement:

  1. eduPersonPrincipalName: If specified, the eduPersonPrincipalName must correspond to the user’s Datadog username. The username is typically 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:1.3.6.1.4.1.5923.1.1.1.6 as the name of the attribute.
  2. sn: The IdP should set urn:oid:2.5.4.4 as the name of the attribute.
  3. givenName: The IdP should set urn:oid:2.5.4.42 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.

Mapping SAML attributes to Datadog roles

With Datadog, you can map attributes in your IdP’s response to Datadog roles. Users with the Access Management permission can assign or remove Datadog roles based on a user’s SAML-assigned attributes.

It’s important to understand what is sent in an assertion before turning on mappings as mappings require correct attributes. Every IdP has specific mappings. For example, Azure works with object IDs, and Okta requires you to set attributes in Okta settings. Datadog recommends cross-referencing with built-in browser tooling such as Chrome Dev Tools or browser extensions and validating your SAML assertions before creating mappings.

  1. Cross-reference and validate your SAML assertion to understand your IdP’s attributes.

  2. Go to Teams and click the Mappings tab.

  3. Click New Mapping.

  4. Specify the SAML identity provider key-value pair that you want to associate with an existing Datadog role (either default or custom). Note: These entries are case-sensitive.

    For example, if you want all users whose member_of attribute has a value of Development to be assigned to a custom Datadog role called Devs:

    Note: Every identity provider is different. Some allow you to set your attribute key or label. Others provide one by default. Datadog recommends you use an assertion inspector on your login to view the details of your particular assertion to understand how your Identity Provider is sending your group membership.

  5. If you have not already done so, enable mappings by clicking Enable Mappings.

When a user logs in who has the specified identity provider attribute, they are automatically assigned the Datadog role. Likewise, if someone has that identity provider attribute removed, they lose access to the role (unless another mapping adds it).

Important: If a user does not match any mapping, they lose any roles they had previously and are prevented from logging into the org with SAML. Double-check your mapping definitions and inspect your own assertions before enabling Mappings to prevent any scenarios where your users are unable to login.

You can make changes to a mapping by clicking the pencil icon or removing it by clicking the garbage icon. These actions affect only the mapping, not the identity provider attributes or the Datadog roles.

Alternatively, you can create and change mappings of SAML attributes to Datadog roles with the authn_mappings endpoint. For more information, see Federated Authentication to Role Mapping API.

Additional features

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

Note: You must have Admin permissions to see the SAML Configuration dialog.

Just in time (JIT) provisioning

With JIT provisioning, a user is created within Datadog the first time they try to log in. This eliminates the need for administrators to manually create user accounts one at a time. The invitation email is not sent in this case.

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 Datadog 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 can set the default role for new JIT users. The default role is Standard, but you can choose to add new JIT users as Read-Only or even Administrators.

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 saving your configuration, you can download the latest version of the SP Metadata for your Identity Provider. Your new SP metadata contains a different, organization-specific AssertionConsumerService endpoint to send assertions to.

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

SAML strict

You can make your organization SAML Strict by disabling other login method types in the the Login Methods UI. When this option is configured, all users must, by default, log in with SAML. An existing username/password or Google OAuth login does not work. This ensures that all users with access to Datadog must have valid credentials in your company’s identity provider/directory service to access your Datadog account. Org administrators can set per-user overrides to allow certain users to be SAML Strict exempt.

Self-updating Datadog SP Metadata

Certain Identity Providers (such as Microsoft’s ADFS) can be configured to pull the latest SAML service provider metadata from Datadog. After you configure SAML in Datadog, you can get the metadata URL for your organization from the SAML Configuration page and use that with your Identity Provider to get the latest service provider metadata whenever we publish changes.

Further Reading

Additional helpful documentation, links, and articles: