Manage users and groups with SAML in Dynatrace SaaS

Dynatrace SaaS enables authentication through your organization's identity provider (IdP). If you want to use your organization's corporate credentials for authentication in Dynatrace, you can set up SAML to delegate the authentication to your IdP. SAML 2.0 is used for authentication. Based on the domain part of your corporate email address, Dynatrace can determine if SAML was configured for that domain and redirect to your company’s IdP for authentication.

Dynatrace SSO Service Provider Configuration using your IdP

Your IdP needs to follow some basic SAML specification and security requirements to be compliant with Dynatrace SSO:

  • Entire SAML message must be signed
  • SAML protocol version is urn:oasis:names:tc:SAML:2.0:protocol
  • NameID format is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • IdP response NotBefore and NotOnOrAfter assertion timestamps must consider system clock skew and must be set with at least 1 minute before and 1 minute after current time (this particularly concerns AD FS default settings)
  • IdP response status code must be urn:oasis:names:tc:SAML:2.0:status:Success
  • SignatureMethod algorithm is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
  • DigestMethod algorithm is http://www.w3.org/2001/04/xmlenc#sha256
  • No assertion encryption

If your IdP already has an application that uses the previous Dynatrace SSO model (https://proxy.dynatrace.com or https://signin.dynatrace.com), you'll need to create a new application. Please keep the old configuration enabled until the new configuration is tested and verified and all of your users have been successfully transitioned.

Dynatrace SSO SP metadata is provided at https://sso.dynatrace.com/sso/metadata. If your IdP requires manual configuration and you don't have any XML parser addons installed in your Chrome browser, we recommend that you view the metadata in Firefox.

Depending on the IdP type, these endpoints need to be configured as follows:

  • https://sso.dynatrace.com:443/saml2/login for Entity ID / Audience Restriction
  • https://sso.dynatrace.com:443/saml2/sp/consumer for Single Sign On URL / Destination URL / Recipient URL
  • https://sso.dynatrace.com:443/saml2/sp/logout for Single Logout Service URL

If your IdP configuration screen contains the option to set SAML bindings for login or logout, set it to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

SAML federated IdP configuration

To set up SAML for your domain, go to account settings in the user menu and click the Single sign-on menu entry on the left. First, you need to prove ownership of the domain for which you want to set up SAML.

  • Enter the domain for which you want set up SAML into the Domain input field.
  • Click Copy and add the TXT resource record to your domain’s DNS configuration.
  • Click Verify so that Dynatrace can verify that the record was added to your domain’s DNS. Note that it may take a few minutes for the record to be propagated in the DNS system and the value is available for Dynatrace to verify.

SAML verify domain

After successful verification, you'll see a check mark next to the Verified button (see example below).

SAML domain verified

You can now begin configuring the metadata.

Note: Before performing the following steps, make sure that you have a non-federated user account that has the "manage users" permission and isn't covered by the federated login. You can achieve this by inviting a user with a non-federated email address (i.e., a different domain than the one you set up SAML for). Specify the manage users permission in the invite (users can be invited via the User management page). This non-federated user is a must-have otherwise you may be locked out of Dynatrace in the case of configuration problems.

First, you need to download the service provider metadata and register it at your IdP. You can do this by clicking the Download button.

Second, you need to upload the metadata of your IdP in XML format. In the input field, upload the XML metadata to Dynatrace by clicking Upload and selecting the proper XML metadata file.

Please specify values for the fields below. First name attribute is the attribute that contains the first name of a user. Last name attribute is the attribute that contains the last name. For Microsoft Azure, it's http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname and http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname respectively.

Security group claim attribute is the one that contains the groups/roles of a user from your IdP. This field is needed if you want to use SAML authorization.

SAML metadata and attributes

To enable federated sign-on, enable the Federated sign-on switch at the top of the SAML configuration setting.

Note: Don't log out of Dynatrace yet in case any SSO issues occur. To test the configuration, open a new browser instance and a new incognito window, navigate to sso.dynatrace.com and enter your email address at the login page. Click Next and you should be redirected to your company’s IdP. Provide your domain password. After successful authentication, you should redirected to your Dynatrace environment’s home page.

If you experience troubles, use the non-federated user that you created before to change the configuration or disable federation. Also take a look at the FAQ section below for assistance with technical issues.

SAML authorization

You can utilize SAML authorization to manage permissions in Dynatrace. You need to map groups from your IdP to groups in Dynatrace. To map groups, click Group management and select a group. We strongly recommend that you create a new group first to test if the SAML authorization works for that group. Also, ensure that you have a non-federated user with manage groups permission, as discussed in the previous section.

As soon as you specify a security group claim name for a group and click Save, all existing users from that group will be removed. The group becomes a federated group and assignment of users to that group is then controlled via the security group claim attribute that you specified on the Single-sign on page, as discussed in the previous section.

To set up the mapping, Expand the Edit pane of a group.

Specify a value in the field security group claim name. This is the federated group name that is returned by your IdP that this Dynatrace group is mapped to. Note, this typically isn't a group display name. It may be, for example, an LDAP ID.

SAML federated group mapping

Click Save.

Note: Don't log out of Dynatrace yet. Open a new browser instance and a new incognito window and perform the login. Then navigate to account settings (click Account settings in the user menu) and verify that you can still see the User management and Group management tabs on the left. If you can't, you've lost your Dynatrace admin permissions. You can use the non-federated user account to change the configuration if you've run into any issues.

Dynatrace checks the value of the security group claim attribute of each user following successful login. If a matching Dynatrace group is found, the user will be added to the Dynatrace group and inherit all the permissions of that group.

When using SAML authorization, it's not required that you invite users to Dynatrace. If a user doesn't yet exist in Dynatrace, but during login one or more matching Dynatrace groups are found (via the security group claim name), the user will be created on-the-fly.

Upon each login, the Dynatrace group assignment is updated based on the values specified in the security group claim attribute.

Frequently asked questions (FAQs)

  • What’s the proper NameIdFormat? The NameIdFormat must be urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
  • What needs to be signed in SAML? Whole messages need to be signed, including logout requests and responses. It's not sufficient to just sign the assertion part.
  • Why am I logged out from my services when I request a logout from Dynatrace? Upon logout, we trigger a global logout, including your IdP, which then cascades to other services. Otherwise you would be logged out from Dynatrace, but it would be sufficient to just enter your email address for reauthentication. If you want to disable this feature (which isn't recommended from a security stand point), edit your metadata, remove all SingleLogoutService tags, and upload the updated metadata as described above.
  • What Claim Rules do I need in AD FS on the Dynatrace relying party? You need two issuance transform rules in this order:
    • The first one uses the Send LDAP Attributes as Claims rule template and creates an outgoing claim type named E-Mail Address from an LDAP Attribute in your attribute store containing the Dynatrace username (the user’s domain email address).
    • The second one uses the Transform an Incoming Claim rule template and creates an outgoing claim type Name ID and outgoing name ID format Email with the Pass through all claim values option enabled.
  • What are the possible causes of the Dynatrace technical difficulties messages We’ve run into technical difficulties… or 400 Bad Request? If, after you authenticate with your IdP, you're redirected to this Dynatrace page, it's likely that there is a problem with the configuration. The most common causes of this are:
    • Your IdP doesn’t accept an authN request using our NameId format and returns an error response with status code InvalidNameIdPolicy. Please check the FAQs above for the proper NameIdFormat. You may also need a rule to create a NameId using our format.
    • You're using a <saml:Attribute/> to return the Dynatrace username but the attribute wasn't recognized by us; alternatively, we couldn't find it using NameID as we didn't recognize its format. Again, check the FAQ above for the proper format.
    • We didn't trust your IdP SAML signing certificate. The IdP SAML metadata you uploaded didn't contain a certificate for signing that matches the certificate in the assertion sent by your IdP. Verify that the certificate is in the metadata XML file that was uploaded to Dynatrace. If you're using a URL to upload the metadata to us, look at the contents generated by the URL. In some organizations, the SAML signing certificate must be requested separately and manually inserted into the metadata by saving the URL contents to a file, adding the signing certificate to the file, and then uploading the file.
    • Response from the IdP isn't fully signed (assertion signature might be present, but it's not sufficient).
    • Your IdP doesn't accept some SAML objects or attributes that the SAML 2.0 Specification describes as optional.
  • Are SAML users added automatically to Dynatrace? Yes, users are added following successful authentication.
  • Is the domain verification TXT resource record needed permanently? No, it can be removed after Dynatrace has successfully validated ownership of the domain.
  • Are multiple domains and subdomains supported for authentication? Yes, but you need to do domain verification and create a configuration for each domain separately. Each domain configuration can use the same IdP metadata and settings.