Federation concepts

Federation types

The introduction of account-specific federation means you now have an alternative to global federation.

Global

Use cases:

You are using only a single Dynatrace account or you are aware of other Dynatrace accounts used within the organization and the possible impact on them (you want to federate all of them at once).

Benefits

  • Federated login is triggered regardless of how you navigate to SSO (for example, through Zendesk)

Drawbacks

  • Possibility to affect other accounts with the same domain
  • It uses the same entityId and SAML metadata for all federations. This can be a limiting factor if, for example, you need to configure two federations in the same Azure AD.

Account or Environment

Use cases:

  • You would like to use federated login for users not sharing your domain (for example, partners and contractors). Setting up the account-default federation will trigger federated login regardless of the domain the user's login belongs to. This will cause account federated guest users to be created. It's also useful if you cannot verify certain additional domains.

  • You would like to use different IdPs to gain access to the account or certain environments. Having separate SAML entityIDs in Dynatrace SSO makes troubleshooting of federated login easier.

  • You would like to use the same IdP, but different applications within the IdP. There's no possibility of conflict in the IdP configuration, and it helps in troubleshooting.

  • You would like to manage the IdP or application used to log in to each environment separately. Environment-specific federation allows you to assign a different IdP or application to each environment.

  • You want to ensure that federation set up in your account doesn't affect any other account (especially within the same organization).

Comparison table

Global
Account-specific
Environment-specific

May affect other accounts?

Must navigate to tenant URL to trigger federated login?

1

Allows federating unverified domains (account federated guests)?

Federation applies to all users with a certain domain:

Regardless of account and tenant

All tenants within a single account

Selected tenants within a single account

1

Dynatrace SaaS SSO uses the tenant URL (for example, https://abc12345.live.dynatrace.com) to extract the tenant (abc12345) and then link it to the account to create a login context (through the Environment Discovery mechanism). If Dynatrace SaaS SSO is not given the tenant context (for example, the user gets redirected to SSO from the community instead of using the tenant URL), then SSO tries to read it from the cookie LastUsedEnvironmentForSignIn. If that fails as well, SSO uses a fallback to either global federation or, if that is not configured, uses password login.

Benefits of using SAML with Dynatrace Saas SSO

Global federation features

  • Users logging in through SAML federation will automatically be created in Dynatrace (JIT provisioning)
    • Ability to use the 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 through 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

Account/environment-specific features

Configuration for the same domain will only be used in the context of the current account and not impact others, even if another one also verifies and configures federation for the same domain.

Example: Previously @company.com global federation would have spanned across different accounts and would force all users from the @company.com domain to log in through Azure - regardless of which account they were part of. Right now, an account can configure a different federated IdP, which would only be considered for this particular account without affecting the login process of other accounts used by other company branches. Account-specific federation is also never shared between accounts - something that was a feature of global federation.

Users can be redirected to a different IdP (or Enterprise Application), depending on if they are logging into test or production environments.

Example: Users logging in to tenant https://abc12345.live.dynatrace.com may be redirected to Azure IdP, while to tenant https://jql98765.live.dynatrace.com may go to Okta. This can be configured within the same account.

This allows configuration of multiple Dynatrace SAML applications in the same IdP. It was a limitation for Azure AD users.

Example: Previously, there was a single global entityId for all of Dynatrace SaaS SSO: https://sso.dynatrace.com:443/saml2/login. Now, every federation gets its own with a unique uuid, such as https://sso.dynatrace.com/identity-federation/federation/0e911469-ea43-49fa-8afa-efb900828bc6.

There are also unique AssertionConsumerService and SingleLogoutService URLs within the SP metadata.

You can allow users to be redirected to their IdP, even if their login domain was not verified. Such users are called account federated guests and have special identifiers, unique to the account they logged into. This is particularly useful for granting Dynatrace access to contractors or partners who do not share any of the domains owned by the company itself. Note that account federated guests are not supported in global federation.

Example: If an account federated only @company.com, but the IdP also has users from other domains, if account (or tenant) default federation was configured, then tom@external.com (and any other user) would also be redirected to the IdP when logging in to this particular account/tenant.

SAML notice and limitations

Domain scope

SAML 2.0 is used for authentication and optionally for authorization.

  • For global federations, 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.

    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.

    If you don't want this behavior, you should instead use account-specific federation.

  • Account and environment federations are bound to the account, not to the domain. Within the account or environment scope, they can be mapped on the domains. When the user signs in, they are then redirected to the appropriate federated IdP based on their sign-in domain and the Dynatrace environment to which they are signed in.

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).

Logging in to external Dynatrace services

Logging in to external Dynatrace services (such as University or Zendesk) redirects to the SSO login page, but without the environment context. If the user is logging in for the first time to Dynatrace or is using browser incognito mode, the LastUsedEnvironmentForSignIn cookie is probably not set.

In such cases, SSO cannot detect which environment the user is accessing and the login/password login prompt might be presented. If global federation is configured for the user domain, this federation will be used for authentication.

To remedy this, the user should log in using the environment URL first to save the last accessed environment in a LastUsedEnvironmentForSignIn cookie and then navigate to the appropriate service. Subsequent login attempts should then redirect correctly based on the cookie, even when going straight to the external service.

SP-initiated authentication

In SP-initiated authentication, the authentication process is initiated by the Service Provider (SP).

Bold terms in glossary

  1. The user starts the authentication process by attempting to access a specific application or service provided by the SP, like the Dynatrace cluster.
  2. The SP recognizes the need for authentication and redirects the user to Dynatrace SSO.
  3. During federation discovery, the sign-in is delegated to a federation.

SP-initiated sign-in start

When the user signs into Dynatrace, they enter the username on the sign-in page, or the username is resolved based on the remember me cookie. Federation is discovered within the context of the environment to which the user wants to sign in.

Environment discovery

The environment is resolved using the following algorithm.

  • If the user is signing in to their Dynatrace environment, this environment is used in the sign-in context.

    The environment discovery mechanism is used to determine which environment and account the user is accessing, to look for an active federation configured on any of these levels.

    Once the user signs in via the account or environment federation, the last used environment cookie (LastUsedEnvironmentForSignIn), which contains the environment ID, is set.

  • If the user is signing to any other Dynatrace service, like Community or Zendesk, and the LastUsedEnvironmentForSignIn cookie set, sign-in is performed like the user would sign in to the last used environment.

Federation discovery

The federation discovery algorithm chooses an eligible federation for a given username in the environment.

  1. If the user belongs to the federated domain for the environment, and that federation is active, choose it.
  2. If the environment account has a default federation set, and that federation is active, choose it.
  3. If the user belongs to the globally federated domain, and that federation is active, choose it.
  4. Otherwise, the user must sign in using their credentials.

If the user is an account federated guest and enters their mapped sign-in on the sign-in page, the identity federation service unmaps their sign-in for the federation discovery algorithm, and the unmapped sign-in is sent to the federated IDP as the user sign-in.

As a security measure, the account federated guest must confirm the redirection to the federated IDP. Once they sign in via the federated IDP, it becomes their trusted IDP. The user doesn't have to confirm redirections to their trusted IDP.

The user enters their credentials on the IDP's sign-in page, and after successful verification, the IDP generates an authentication assertion. The IDP redirects the user back to the SP along with the authentication message, and upon validation, the user is granted access to the requested application or service.

IdP-initiated authentication

In IdP-initiated authentication, the user starts their authentication journey at the IdP's website or portal.

  • The user enters their credentials (username and password) on the IdP's sign-in page, and upon successful verification, the IdP generates an authentication message.
  • The IdP then redirects the user to the identity federation service along with the authentication message (like in SP-initiated authentication).
  • In this type of configuration, the environment context is missing. To determine where the user will be redirected, you set the post-sign-in redirect URL inside the Relay State param.

Frequently Asked Questions

SAML configuration and attributes

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

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

Clear the ALWAYS SIGN ASSERTION checkbox

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

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.

Yes, Dynatrace supports JIT creation of users when using SAML federation. Federated users are created or updated on the fly after successful authentication.

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

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.

The signing certificate inside the IdP metadata has expired since you set up the SAML configuration. The metadata is always validated at the beginning of the verification process.

To solve this, you need to rotate the signing certificate on your IdP side, save (or copy) the updated IdP metadata, and upload it to your federation configuration in Dynatrace.

Authentication and logout

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 re-authenticate.

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.

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, both IdP-initiated sign-in and RelayState are supported.

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.

Signatures and certificates

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

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.

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

  1. Create a new certificate that meets our requirements.

    Caution

    Don't change it on your IdP side yet! If you do so, you will cut access to the Dynatrace environment.

  2. 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.

      <KeyDescriptor use="signing">
         <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
         <X509Data>
            <X509Certificate>(...) Certificate 1 (...)</X509Certificate>
         </X509Data>
         </KeyInfo>
      </KeyDescriptor>
      <KeyDescriptor use="signing">
         <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
         <X509Data>
            <X509Certificate>(...) Certificate 2 (...)</X509Certificate>
         </X509Data>
         </KeyInfo>
      </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.

  3. Update the metadata on the Dynatrace side only.

  4. Test your configuration.

  5. If the verification process completes without issues, you can update the certificate on your IdP side.

  6. Run the configuration test again.

  7. optional To double-check 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.

  8. optional Remove the older certificate from your IdP metadata in Dynatrace.

Troubleshooting

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 (the 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.

If Error AADSTS50105 - The signed in user is not assigned to a role for the application occurs during federated authentication with Microsoft Entra ID, it indicates that the user hasn't been granted access to the application in Entra ID.

For details, see the Microsoft documentation:

If Error AADSTS50105 - The request has expired. Try to submit new request. occurs during federated authentication with Microsoft Entra ID, contrary to the error description, it indicates that the user tried to sign in to Dynatrace by IdP-initiated login (via M365 app launcher) while the Azure application had Signature Verification enabled. This is a limitation of Entra ID, as per SAML Request Signature Verification in the Microsoft documentation:

Enabling Require Verification certificates will not allow IDP-initiated authentication requests (like SSO testing feature, MyApps or M365 app launcher) to be validated as the IDP would not possess the same private keys as the registered application.

To resolve this issue, choose one of the following approaches:

  • Users need to use the Dynatrace environment URL to sign in to Dynatrace
  • Signature Verification needs to be disabled

For details, see the Microsoft documentation.

Glossary

Term
Definition

account

In the account scope, a customer can manage their federations, account verified domains, federated domains, and account default federation. An account is identified by UUID, which is typical for all Dynatrace applications.

account domain

When the customer confirms their ownership of a given domain in the process of domain verification in the account, this domain becomes an account verified domain. An account can own multiple verified domains, and multiple accounts can own the same verified domain.

account default federation

The default federation for a user who doesn't belong to any of the account federated domains. It's used in federation discovery.

account federated guest

An account federated guest is created whenever a user logs in through account/environment-specific federation, but does not belong to any verified domain within the account. In this case, SSO creates a new user with a very specific identifier to make sure that this user is tied to a single account and does not interfere with the global user, who may freely be assigned to multiple accounts.

The username of an account federated guest is remapped on the fly as follows:

<login_part>_<domain_part>@a.<account_uuid>.sso.dynatrace.com

For example, user mary.smith@example.com, in an account with IDM UUID 7f5bab5a-9620-11ee-960a-2fcdafd38a3b, would become the following account federated guest:

mary.smith_example.com@a.7f5bab5a-9620-11ee-960a-2fcdafd38a3b.sso.dynatrace.com

The mapping from the original login to the account federated guest stamp is automatic.

  • The user is free to use either their regular or mapped email in the login field.
  • In the Account Management People list, however, account federated guests are displayed with the mapped value.
  • The account UUID, which is part of the mapped login, is not parsed and does not influence the process of environment discovery.

environment

Identified by ID, which is unique across Dynatrace (usually called tenantId). The environment belongs to one account. The environment defines how users sign into it. It can have a user-friendly alias. The alias is unique and the environment can have at least one alias.

environment discovery

The process used to resolve the environment from the sign-in context. For details, see the Environment resolution section.

federated domain

Association between domain and federation. When a user signs in to the account and belongs to a federated domain, they are redirected to federated domain's federation. It can be set on the account or environment scope. It's used in federation discovery.

federation

Defines Dynatrace as a Service Provider (SP), which delegates sign-in, manages sessions, and manages user groups to the customer's Identity Provider (IdP). This configuration enables linking identities (users) to Dynatrace SSO. It has a unique UUID. The federation IdP ID corresponds to the entity ID from the SAML 2.0 specification. Federation belongs to the account.

federation discovery

The process used to choose the federation for signing in users in the SP-initiated authentication. For details, see the Federation discovery section.

global federation

Bound to the account verified domain and shared between all accounts having this domain.

global user

The user for which, in the current setup, the username, login, and email are synonymous.

IdP-initiated authentication

Sign-in process initiated by the federated IDP. For example, when the user wants to open Dynatrace application in the Azure Portal. For details, see the IdP-initiated authentication section.

last used environment cookie

An optional cookie that contains the environment ID. For details, see the Environment discovery

SP-initiated authentication

Sign-in process initiated by Dynatrace. For example, when the user wants to sign into the environment. For details, see the SP-initiated authentication section.

username

The user enters their username on the SSO sign-in page to sign in. It's in email address format.