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 authentication to your IdP.

Benefits of using SAML with Dynatrace Saas SSO

Users logging in through SAML federation will automatically be created in Dynatrace (JIT provisioning)
- Ability to use organization's IdP MFA/2FA for increased account security
If configured, Dynatrace is also able to provide authorization based on group assignments within the IdP by means of SAML Assertion role mapping
- After initial configuration access to Dynatrace can be managed solely in the IdP
- SAML Groups can be added to Dynatrace programmatically using Account Management API

SAML notice and limitations

Domain scope

SAML 2.0 is used for authentication and optionally for authorization. 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.

Be aware that the SAML configuration affects all other accounts and users that share the same domain name.

SAML federation for multiple accounts

If your company has several Dynatrace accounts and you are using the same domain to sign in for all of your accounts, then the other accounts will inherit the federation configuration and will use your identity provider for authentication. For instance, if you set up SAML federation on account A for domain mycompany.com and you have other accounts in Dynatrace also using mycompany.com to sign in (account B and C), then all other accounts (and all user sign-ons ending with mycompany.com) will use federation after you've activated SSO for mycompany.com in account A.

Mobile user access

SAML is mainly a protocol for Single-Sign-On (SSO) and Identity Federation, and does not provide features for regular user and permission synchronization.

Although we support on-the-fly creation of federated users for the first time they have authenticated to Dynatrace over your company's IdP, and federated user attributes update on every sign-on, additional actions are required to cover functionalities that are not within the scope of SAML. Specifically, if a federated user has been removed or deactivated in the customer Active Directory but not in Dynatrace, and if that user issued Oauth2 tokens (for access to the Dynatrace Mobile App) before losing access to Dynatrace, those tokens can remain valid for up to 30 days.

In order to remove all access, you need to remove users manually (or you can harness SCIM for automatic user management).

IdP requirements and specification

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

The entire SAML message must be signed (signing only SAML assertions is insufficient and generates a 400 Bad Request response).
The SAML protocol version is urn:oasis:names:tc:SAML:2.0:protocol.
The 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 to at least 1 minute before and 1 minute after the current time (this particularly concerns AD FS default settings).
The IdP response status code must be urn:oasis:names:tc:SAML:2.0:status:Success.
The SignatureMethod algorithm is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256.
The DigestMethod algorithm is http://www.w3.org/2001/04/xmlenc#sha256.
No assertion encryption.
Just-in-Time provisioning is supported.
Session timeout is not configurable and it is 1 hour.

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 extensions 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 sign-in or sign-out, set it to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

SAML federated IdP configuration

To set up SAML for your domain

Create a fallback user account

Verify your ownership of the domain

Configure metadata

Test your configuration

Create a fallback user account

When a user signs in, Dynatrace checks the domain part of your corporate email address to determine whether SAML was configured for that domain. If there's a match, the sign-in is redirected to your company’s IdP for authentication. For a fallback, you need an email address that won't be redirected like this.

You need to create a fallback user account so you won't be locked out if you have configuration troubles.

Your fallback account must be a non-federated user account belonging to a group that has View and manage users and groups permission and isn't covered by the federated sign-in.

Open Account Management. If you have more than one account, select the account you want to manage.
Go to Identity & access management > People and select Invite user.
In the User email step, enter a non-federated email address (an email address with a different domain from the one for which you are setting up SAML) and then select Next.
In the Add to groups step, add the user to a group that has View and manage users and groups permission and then select Next.
In the Confirm permissions step, confirm that you have added the correct permissions and then select Invite.

Verify your ownership of the domain

Before you can configure the domain for which you want to set up SAML, you need to prove ownership of the domain.

Open Account Management.
To open Account Management through the web UI:
- Latest Dynatrace: from the user menu in the lower-left corner (at the bottom of the Docker), select Account Management.
- Previous Dynatrace: from the user menu in the upper-right corner, select Account settings.
Go to Identity & access management > Domain verification.
In the Add domain section, enter the domain (for example, mycompanyname.com) for which you want to set up SAML and select Add to add it to the Pending domains table.
Multiple domains
If users in your organization use more than one domain to sign in (for example, @mycompanyname.com and @uk.mycompanyname.com), you can add additional domains in additional rows and start verifying them all in parallel. Enter each domain in a different row.
For each domain you are verifying, in the Pending domains table, select Copy (in the Value column) and add the copied TXT resource record to your domain’s DNS configuration.
For each domain you are verifying, in the Pending domains table, select Actions > Verify so that Dynatrace can verify that the record was added to your domain’s DNS.
Propagation time
It typically takes a few minutes for a record to propagate through the DNS system and the value to become available for Dynatrace to verify. In some cases, it may take up to 24 hours.
Each verified domain is added to the Verified domains table.

Configure metadata

After you create a fallback user account and verify your ownership of the domain, you can configure metadata.

Open Account Management.
To open Account Management through the web UI:
- Latest Dynatrace: from the user menu in the lower-left corner (at the bottom of the Docker), select Account Management.
- Previous Dynatrace: from the user menu in the upper-right corner, select Account settings.
Go to Identity & access management > SAML configuration.
On SAML configuration, in the Verified domains table, select Actions > Edit configuration.
Select Download XML to download the service provider (SP) metadata displayed in Service provider SAML 2.0 XML metadata.
- Alternative: If you prefer, you can select the data in the Service provider SAML 2.0 XML metadata text box and copy it to your clipboard instead of downloading a file.
Register the data at your IdP and get the metadata of your IdP in XML format. The activities involved in this step depend on your IdP's interface and requirements.

The X509Certificate appended to metadata needs to be signed using one of the following algorithms: SHA256withRSA, SHA384withRSA, or SHA512withRSA.
IdP-specific instructions
Dynatrace supports all IdPs that support the SAML 2.0 standard. For frequently used IdPs, we have IdP-specific instructions for registering the SP data at your IdP and getting the IdP metadata:
AD FS
Azure
Google Workspace
Okta
These examples were correct at the time of writing, but Dynatrace has no control over changes that may be made by your IdP.
Select Choose file to upload the file containing the metadata of your IdP in XML format.
- Alternative: If you prefer, you can paste the IdP metadata text directly into the Identity provider SAML 2.0 XML metadata box instead of uploading a file.
In the Attribute mapping section, specify the following:
- First name attribute is the attribute that contains the first name of a user.
  For Microsoft Azure, it's http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname.
- 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/surname.
- Security group claim attribute contains the groups/roles of a user from your IdP. This field is needed if you want to use SAML authorization.
Select Validate configuration to verify your settings.
Important: Configuration validation is based on sign-in to Dynatrace via SSO. Validation can succeed only if:
You have privileges to sign in to Dynatrace.
You sign in to federation and are redirected to Dynatrace with the proper SAML message.
- If validation is successful, Dynatrace displays a confirmation message. Close the message to return to Add configuration and then select Continue to display a summary of the validated configuration.
- If there's an error in the Results list, select Edit configuration to fix it before continuing.
On Enable SSO, select Enable if you are ready to activate your configuration.

Don't sign out of Dynatrace yet in case any SSO issues occur.
Select Save & continue to save your configuration.

These configuration changes affect accounts and users that share the same domain name. For example:

If you've already configured SAML for a trial account using domain example.com and now you are configuring a production account that also uses domain example.com, the changes you submit now will apply to both accounts (you will overwrite the SAML configuration for the trial account when you save changes for the production account).
If you have users on another account whose email addresses also use the example.com domain, those users (all users whose email address ends with example.com) will have to sign in using the new IdP configuration.

Test your configuration

To test your configuration

Open a new browser instance and a new incognito window.
Go to sso.dynatrace.com and enter your email address.
Select Next.
You should be redirected to your company’s IdP.
Provide your domain password.
After successful authentication, you should be redirected to your Dynatrace environment's home page.

Troubleshooting:

If you experience trouble, use the non-federated user (the fallback user account you created earlier) to sign in and change the configuration or disable federation.
See Frequently asked questions below for answers to common questions.

SAML authorization

To use SAML authorization to manage permissions in Dynatrace, you need to specify the security group claim attribute in the attribute mapping configuration that contains the groups/roles of a user from your IdP, and then map groups from your IdP to groups in Dynatrace.

In Dynatrace, all user group permissions are joined together. The user will be granted permissions from all group types: LOCAL, SAML, and SCIM. It is the Account Manager's responsibility to decide if and how user permissions are isolated.

Open Account Management.
To open Account Management through the web UI:
- Latest Dynatrace: from the user menu in the lower-left corner (at the bottom of the Docker), select Account Management.
- Previous Dynatrace: from the user menu in the upper-right corner, select Account settings.
Go to Identity & access management > Groups and add a new group or find an existing group you want to map. You can filter the list by name and permissions.
Important
We strongly recommend that you first create a new group (select Create group) to test whether SAML authorization works for that group.
Switching a LOCAL group to SAML removes all user assignments to that group.
Make sure you have a non-federated user with manage groups permission as discussed earlier.
Expand the Edit pane of the group to set up a mapping.
- Group name—Make sure it matches the group you intend to edit.
- Security group claims—A list of one or more federated group names returned by your IdP and mapped to this Dynatrace group.
  Select Add claim if you need to add a claim.
  This typically isn't a group display name. It can be, for example, an LDAP ID.
  When you specify security group claim for a group and select Save:
  All existing users from that group are removed.
  The group becomes a federated group. Assignment of users to that group is then controlled via the Security group claim attribute that you specified on Single-sign on.
  The type of the group changes to SAML
- Account permissions
  Account-related permissions for members of this group.
- Environment permissions
  Environment-related permissions for members of this group.
- Management zone permissions
  Management zone—related permissions for members of this group.
Select Save.

Don't sign out of Dynatrace yet.
Open a new browser instance and a new incognito window and sign in.
Go to Account Management and verify that you can still see Identity & access management > People and Identity & access management > Groups.
If you can't see them, you've lost your Dynatrace admin permissions. Use the non-federated user account to change the configuration if you've run into any issues.
Dynatrace checks Security group claims of each user following successful sign-in. If a matching Dynatrace group is found, the user is added to the Dynatrace group and inherits all permissions of that group.

When using SAML authorization, you don't have to invite users to Dynatrace. During sign-in, a user that doesn't already exist in Dynatrace is created automatically.

Upon each sign-in, the Dynatrace group assignment is updated based on the values specified by the Security group claim attribute.

Frequently asked questions

If you are using PingFederate as an IdP and you get a Missing Destination Attribute value error

Go to PingFederate and select Identity Provider in the left sidebar.
Select the Signature Policy tab.
Clear the ALWAYS SIGN ASSERTION checkbox as in the following example.

The NameIdFormat must be urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Whole messages need to be signed, including sign-out requests and responses. It isn't sufficient to sign just the assertion part.

Upon sign-out, a global sign-out is triggered, including for your IdP, which then cascades to other services. Otherwise, you would be signed out from Dynatrace, but it would be sufficient to just enter your email to reauthenticate.

If you want to disable it (not a good idea from a security standpoint), edit your metadata, remove all SingleLogoutService tags, and upload the updated metadata.

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.

If, after you authenticate with your IdP, you are redirected to a Dynatrace page such as We’ve run into technical difficulties… or 400 Bad Request, it's likely that there's 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 the status code InvalidNameIdPolicy. The NameIdFormat must be urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. You might 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 Dynatrace; alternatively, we couldn't find it using NameID as we didn't recognize its format. See the previous question (What claim rules do I need in AD FS on the Dynatrace relying party?) for the proper format.
Dynatrace didn't trust your IdP SAML signing certificate. The IdP SAML metadata you uploaded did not 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, 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 to us.
The response from the IdP isn't fully signed (assertion signature might be present, but it isn't sufficient).
Your IdP doesn't accept some SAML objects or attributes that the SAML 2.0 specification describes as optional—contact a Dynatrace product expert via live chat.

No, it can be removed after Dynatrace has successfully validated ownership of the domain.

Yes, but you need to perform domain verification and create a configuration for each domain separately. Each domain configuration can use the same IdP metadata and settings.

Yes, customer IdP metadata can contain multiple signing certificates. Dynatrace SSO validates that SAML messages from the customer IdP are signed by one of them.

No, a full DN contains commas, and this is recognized as independent group names. The IdP should send the group name or group ID.

Yes. When a Dynatrace environment URL is sent in the RelayState parameter, the user is redirected to the specified URL upon signing in. When the RelayState value is missing, the user is redirected to the last accessed Dynatrace tenant or account page.

Depending on the IdP, setting RelayState in an IdP SAML configuration usually affects all IdP users. Dynatrace SSO does not support a default destination per user.

Yes. If the value of the Group SAML attribute contains a comma-separated list of groups, the value will be split by comma and interpreted as a list of groups.

Yes. For example, if your IdP returned groups as the LDAP path:
CN=Admin,OU=SSO Team,DC=dynatrace,DC=com
Dynatrace would interpret this as a comma-separated list of four groups:
CN=Admin, OU=SSO Team, DC=dynatrace, and DC=com
In group mapping, you should use one of these values.

If your security policy requires emergency access to Dynatrace in case of problems with your IdP, we recommend that you invite a non-federated user to the environment with Account manager permissions and use that as your Break Glass account.

If this is not an option, you can configure an additional federated domain to a different IdP and use it for backup sign-on in case of problems with your regular IdP.
Configuring multi-factor authentication (MFA) is not supported by Dynatrace. You can configure authentication and MFA through your organization's IDP.

Configuring multi-factor authentication (MFA) is not supported by Dynatrace. You can configure authentication and MFA through your organization's IDP.

SAML metadata can contain more than one certificate, not all of which need to be valid. This is very useful when you want to rotate your certificates because the current one is going to expire.

To switch certificates

Create a new certificate that meets our requirements.

Don't change it on your IdP side yet! If you do so, you will cut access to the Dynatrace environment.
Append the new certificate to your metadata in Dynatrace.
- If your IdP allows you to include more than one certificate, you can add the certificate in the IdP and then upload to Dynatrace the entire updated metadata generated by your IdP.
To maintain uninterrupted access to Dynatrace during certificate rotation, look at the entries between the <KeyDescriptor> tags to verify that the XML metadata contains two different certificates, as shown in the example below.
1<KeyDescriptor use="signing">
2 <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
3 <X509Data>
4 <X509Certificate>(...) Certificate 1 (...)</X509Certificate>
5 </X509Data>
6 </KeyInfo>
7 </KeyDescriptor>
8 <KeyDescriptor use="signing">
9 <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
10 <X509Data>
11 <X509Certificate>(...) Certificate 2 (...)</X509Certificate>
12 </X509Data>
13 </KeyInfo>
14 </KeyDescriptor>
Be aware that Azure XML metadata might not contain the new certificate immediately after it is created. If you notice that the certificate is missing, wait a few minutes to allow Azure to process the new certificate and then download the XML metadata again.
- Otherwise, copy the full <KeyDescriptor use="signing"> (...) </KeyDescriptor> element in metadata, paste it under the current one, and, in the copy, replace the certificate value with your new certificate value, which is located between the <ds:X509Certificate> and </ds:X509Certificate> tags in the <KeyDescriptor> element you just pasted.
Update the metadata on the Dynatrace side only.
Test your configuration.
If the verification process completes without issues, you can update the certificate on your IdP side.
Run the configuration test again.
optional To doublecheck your configuration, sign out and in again.
If you have problems, you can switch back to the older certificate in your IdP and try again.
optional Remove the older certificate from your IdP metadata in Dynatrace.

If Error AADSTS50105 - The signed in user is not assigned to a role for the application occurs during federated authentication with Azure Active Directory (Azure AD), it indicates that the user hasn't been granted access to the application in Azure AD.

For details, see the Microsoft documentation: