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 (signing only SAML Assertions is insufficient and will generate a 400 Bad Request response)
  • 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.

Dynatrace SSO configuration in Azure

To configure Azure with Dynatrace SSO, follow the examples detailed below in the order listed.

  1. In the Azure portal, choose Enterprise Applications from the Azure Active Directory.
  2. Click the New Application button and choose Non-gallery application.
    Dynatrace SSO configuration AZURE
  3. Type the name of the application (for example, Dynatrace) and click Add to add the application.
  4. Choose Single sign-on from the application’s left-hand navigation menu and select SAML as the single sign-on method. Dynatrace SSO configuration AZURE
  5. Click Upload metadata file and choose the Dynatrace metadata file. Dynatrace SSO SP metadata is provided at https://sso.dynatrace.com/sso/metadata.
    Dynatrace SSO configuration AZURE
  6. In the Basic SAML Configuration field, enter Logout Url: https://sso.dynatrace.com:443/saml2/sp/logout and save your changes.
    Dynatrace SSO configuration AZURE
  7. Return to the Single sign-on preview.
  8. To enable SAML authorization in Dynatrace SSO, you need to add the group attribute to SAML. Edit User Attributes & Claims and Groups returned in claim. Dynatrace SSO configuration AZURE
  9. Return to the Single sign-on preview and edit SAML Signing Certificate.
  10. Switch Signing Option to Sign SAML response and assertion.
    Dynatrace SSO configuration AZURE
  11. Return to the Single sign-on preview and download Federated Metadata XML.
  12. Choose User and groups from the application’s left-hand navigation to configure user access to the Dynatrace application.
  13. In Dynatrace Account Configuration, provide the metadata you downloaded as Federated Metadata XML and the following attributes:
  • First name attribute - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • Last name attribute - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  • Security group claim attribute - http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

Note that in the SAML message returned by Azure, groups are identified with an ObjectId, not a group name. When configuring the user group mapping, make sure you use ObjectId in the Security group claim name.

Azure group mapping

Dynatrace SSO configuration in AD FS

Follow below examples in order to configure Dynatrace SSO as a service provider in AD FS.

The recommended approach is to specify the SSO Dynatrace federation metadata URL https://sso.dynatrace.com/sso/metadata:
Dynatrace SSO configuration in AD FS

If for some reason it can't be introduced, you need to download the metadata manually by running the following command in PowerShell:
wget -Outfile dynatrace_sso_metadata.xml https://sso.dynatrace.com/sso/metadata
and update it for Dynatrace SSO RelyingPartyTrust:
Update-AdfsRelyingPartyTrust -TargetIdentifier "<DYNATRACE_SSO_IDENTIFIER>" -MetadataFile 'dynatrace_sso_metadata.xml'

Ensure that the secure hash algorithm is SHA-256:
Dynatrace SSO configuration in AD FS

To configure claims mapping, right-click on Sso Dynatrace Relying Party Trust under Trust Relationship and select Edit Claims Rules....
To create Active Directory transformations, click Add Rule..., select Send LDAP Attributes as Claims (the default option), and set values according to the images shown below:
Dynatrace SSO configuration in AD FS
Dynatrace SSO configuration in AD FS
Dynatrace SSO configuration in AD FS

Token-Groups as SIDs is an example LDAP attribute that may be used for Group mapping. Depending on your corporate LDAP, select the one that contains the LDAP user groups.

Next, you need to create an Email Address to NameID transformation. Click Add Rule..., select Transform an Incoming Claim, and set the values according to the image shown below:
Dynatrace SSO configuration in AD FS

Lastly, you need to ensure that the SAML message will be signed:
Set-ADFSRelyingPartyTrust -TargetIdentifier "<DYNATRACE_SSO_IDENTIFIER>" -SamlResponseSignature "MessageAndAssertion"

...and that the system clock's skew won't affect SAML request validation:
Set-ADFSRelyingPartyTrust -TargetIdentifier "<DYNATRACE_SSO_IDENTIFIER>" -NotBeforeSkew 2

To establish SAML authorization in Dynatrace SSO, you need to specify First name attribute, Last name attribute, and the Security group claim attribute on the Single Sign-On configuration page (refer to the SAML federated IdP configuration chapter). Usually these attributes for AD FS will be: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname, and http://schemas.xmlsoap.org/claims/Group, but this may vary depending on the AD FS version and settings.

Dynatrace SSO configuration in OKTA

Follow the below examples in order to configure Okta SAML Settings with Dynatrace SSO.

Dynatrace SSO configuration in OKTA

After expanding the Advance Settings you will need to select Response Signing. Signing Assertion might be selected but it is not required though. Please mind that Assertion cannot be encrypted. The Certificate file required by Okta for the SSO Application configuration can be converted from an X509Certificate that you can find in the, publicly available, Dynatrace SSO Metadata https://sso.dynatrace.com/sso/metadata, for instance using this online tool. The result should be just a X509Certificate wrapped with a header. If you want to enable Single Logout service with Dynatrace SSO you can do it as shown in the picture.

Dynatrace SSO configuration in OKTA

To enable SAML authorization in Dynatrace SSO you need to specify Attribute Statements for the first name, last name and one Group Attribute Statement to allow mapping of groups between Okta IdP and Dynatrace SSO. These attribute names need to match the Dynatrace federated attributes values accordingly: First name attribute, Last name attribute and Security group claim attribute. Values in the images below are just examples. Since Okta uses a proprietary Expression Language, you can configure Group Attribute Statements filtering in another way. For example, .* means that all groups assigned to the user will be sent with the SAML request.
Dynatrace SSO configuration in OKTA

Dynatrace SSO configuration in GSuite (Google)

Configuring GSuite SAML application

  1. Navigate to the GSuite Admin panel, choose Apps and then SAML Apps.
    Dynatrace SSO configuration in GSuite
  2. Choose to add a new SAML Application and in the pop-up dialog, select Setup my own custom App.
    Dynatrace SSO configuration in GSuite
  3. On the next screen, download the IDP metadata as an XML file (Option 2). This will be needed when configuring single sign-on in Dynatrace:
    Dynatrace SSO configuration in GSuite
  4. Choose an intuitive Application Name.
    Dynatrace SSO configuration in GSuite
    Use the following settings for Dynatrace SSO:
  • ACS URL: https://sso.dynatrace.com:443/saml2/sp/consumer
  • Entity ID: https://sso.dynatrace.com:443/saml2/login
  • Start URL: Leave empty for now
  • Signed Response: Select this option. This information can also be found in Dynatrace SSO metadata at https://sso.dynatrace.com/sso/metadata
  1. The NameID and NameID format should be left as-is.
    Dynatrace SSO configuration in GSuite
  2. On the next screen, add two mappings for now, the FirstName and LastName. You'll need a third one for Groups as well. Please refer to the next section, "Preparing Group Mapping".
    Dynatrace SSO configuration in GSuite

Preparing group mapping

By default, GSuite doesn't facilitate the sending of user groups through SAML, which is required for mapping to certain groups/permissions in Dynatrace. The only fields that may be delivered by SAML are as follows:
Dynatrace SSO configuration in GSuite

This doesn't allow the GSuite administrator to provide a list of groups or permissions that the user should have in Dynatrace. Google suggests that you add a custom schema to user accounts, which will allow you to add multiple group entries, which upon being sent via SAML, will be mapped correctly to groups and permissions in Dynatrace. To do this, navigate to the Google Directory API:
https://developers.google.com/admin-sdk/directory/v1/reference/schemas/insert?authuser=1

A suggested schema (in JSON) for Dynatrace is provided below:

{
  "schemaName": "DynatraceSSO",
  "displayName": "DynatraceSSO",
  "fields": [
    {
      "fieldType": "STRING",
      "fieldName": "UserRole",
      "displayName": "UserRole",
      "multiValued": true,
      "readAccessType": "ADMINS_AND_SELF"
    }
  ]
}

For the customerId, use my_customer, which automatically uses this Google account's ID:
Dynatrace SSO configuration in GSuite

Click Execute to add the new schema for all users.

This new configuration will be selectable as a SAML attribute for users. Navigate back to Apps > Saml Apps, and finally, Attribute Mapping to set the Role attribute to DynatraceSSOand UserRole accordingly:

Dynatrace SSO configuration in GSuite

This will make Google send all of the entries in DynatraceSSO / UserRole for a certain user as an attribute in SAML, which Dynatrace SSO will use to assign permissions upon a federated login.

The user roles can be applied to every user separately using the user configuration screen in GSuite:

Dynatrace SSO configuration in GSuite

A user can have more than one role assigned:

Dynatrace SSO configuration in GSuite

These roles can then be mapped in Dynatrace BAS to certain permissions as needed. Notice that in GSuite, UserRole has to have the same value as the Security group claim name in BAS. For example, DynatraceTenantViewer and DynatraceAccountAdmin. Say for example that you've set up two groups in BAS and have a group called Main Account Admin, which is assigned a federated user by the Security group claim name DynatraceAccountAdmin. If you now attach the DynatraceAccountAdmin UserRole to any user in GSuite, that user will be assigned the permissions of the Main Account Admin group in BAS.

Dynatrace SSO configuration in GSuite

Upon setting up the SAML apps configuration in GSuite correctly, the SAML request sent from GSuite should contain the configured groups as SAML attributes:

Dynatrace SSO configuration in GSuite

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 request and response. It's not sufficient to just sign the assertion part.
  • Why am I logged out from my services when I've requested a logout from Dynatrace? Upon logout, a global logout is triggered, including for 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 to reauthenticate. If you want to disable it (which isn't a good idea from a security standpoint), 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 page We’ve run into technical difficulties… or 400 Bad Request? If, after you authenticate with your IdP, you are 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 accepted by us. 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. Again, check the FAQs above 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.
    • Response from 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 SAML 2.0 Specification describes as optional. Please contact the Dynatrace Support.
  • 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.