Troubleshooting common SAML federation issues with Dynatrace SSO

[Waclaw_Dziewuls]

• Overview
• Common issues:
• Saml Message has not been signed. Entire SAML Message needs to be signed.
• Invalid SAML Message. Missing NameID element with value.
• SAML Message NameID Format {0} was incorrect. Allowed formats:urn:oasis:names:tc:SAML:1.1:nameid-for...
• Your IdP returned different user {0} than user {1} you entered into Dynatrace.

Overview

Dynatrace Single Sign-On supports SAML Federated Login for customers with its own set of requirements that the IdP has to meet to allow the users to access Dynatrace: https://docs.dynatrace.com/docs/shortlink/manage-users-groups-with-saml#identity-provider-idp. As SAML itself is a complex protocol, we are aware of some common pitfalls of the configuration process and we are providing a guide to explain, why they appear and how to successfully resolve them in two of the popular IdPs: Azure Entra ID and Okta.

Common issues:

Saml Message has not been signed. Entire SAML Message needs to be signed.

This error indicates that there is either no signature in the SAML message or on the assertions were signed, not the whole SAML message. The whole message must be signed, because only then is the Service Provider confident that the message was not tampered with, hence our restriction.

It's possible to notice the difference in SAML Responses between Signed Assertions and Signed Whole Messages e.g. captured and decoded by SAML Trace based on the placement of the <ds:Signature>  as shown here: https://www.samltool.com/generic_sso_res.php

In the example above, with whole message signing, the <ds:Signature> is before and top-level from the <saml:Assertion>:

<samlp:Response (...)>
  <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      (...)
    </ds:Signature>
  (...)
  <saml:Assertion (...)>

Assertion signing will contain the <ds:Signature> entry under and within the <saml:Assertion> tag:

<samlp:Response (...)>
  <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer>
  (...)
  <saml:Assertion (...)>
     <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      (...)
    </ds:Signature>
  </saml:Assertion>

Dynatrace SSO expects whole messages to be signed, which is the first one.

Resolution:

Azure

Navigate to the Azure Entra ID, and then to the SAML Enterprise Application you configured for Dynatrace. Then please open "Manage" -> "Single Sign-On" and choose "Edit" within the "SAML Certificates" section.

In the newly opened section, select the drop-down in "Signing option" and select: "Sign SAML Response"

 

Okta

Within the SAML Application configured for Dynatrace, choose the "General" tab and scroll down to the "SAML Settings" section and click "Edit".

Then click "Next" to get to the "Configure SAML section".

In the "SAML Settings" Section, scroll down and click "Show advanced settings" to see the signing options. The "Response" option should be set to "Signed", which will set whole SAML Message signing.

Invalid SAML Message. Missing NameID element with value.

SAML Message NameID Format {0} was incorrect. Allowed formats: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Dynatrace SSO expects to find the user's login in the SAMLResponse under the <Subject><NameID> field and it has to be exactly set to have Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress". Otherwise the SAML Response will be rejected. Some IdPs, such as Azure enforce this assertion by default, others have to be configured explicitly to add it.

<Subject>
    <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">Your.UserName@yourdomain.com</NameID>
</Subject>

Resolution:

Azure

Navigate to the Azure Entra ID, to the SAML Enterprise Application that you have configured for Dynatrace. Then please open "Manage" -> "Single Sign-On" and choose "Edit" within the "Attributes & Claims" section.

Then, make sure there is a Unique User Identifier (Name ID) claim.

Upon clicking on the claim, check that the Name identifier format is set to Email Address.

Okta

Within the SAML Application configured for Dynatrace, choose the "General" tab and scroll down to the "SAML Settings" section and click "Edit".

Then click "Next" to get to the "Configure SAML section".

Please make sure the "Name ID format" is set to "EmailAddress". The "Application username" should in most cases be set to "Email", especially if you use a different login as the Okta Username.

Your IdP returned different user {0} than user {1} you entered into Dynatrace.

The NameID claim (described above) is used in Dynatrace SSO to match the user login in the IdP to the one entered in the login field and they have to match.

Resolution:

First and foremost, please verify that the user currently logged into Dynatrace or the one which you input in the login field in Dynatrace SSO match:

Azure

On top of the settings from the paragraphs above about NameID, please make sure that the parameter you use for the Source attribute e.g. user.userprincipalname :

is actually the same as the value for the user currently attempting to log in:

Okta

If you are using the "Application username" as "Email" in the "SAML Settings" (see how to reach these settings above), then within the user's profile, please make sure the "Primary email" value is the same as was entered in the Dynatrace SSO login field.