AD FS 4.0 and the curious case of claim issuance policy naming

The other day a colleague at Kloud, asked for a second set of eyes to look over and help with an Relying Party Trust setup in AD FS 4 (Server 2016). I obliged and went through a bunch of questions to try and determine what this issue might be.

To cut a long story short, the following is a quick bit of guidance when it comes to the naming of Claim Issuance Policies. I’ve found over the years that this can have a detrimental impact on configuration of an RPT if not setup with certain formatting.

A bit of further context

Just a quick description of what a Name Identifier is what it’s purpose, thanks to docs.microsoft.com ¹:

A claim is information that an identity provider states about a user inside the token they issue for that user. In SAML token, this data is typically contained in the SAML Attribute Statement. The user’s unique ID is typically represented in the SAML Subject, also called as Name Identifier.

[Update 2019-04-02]

I forgot to mention that the error message that you would receive if there may be something wrong with the Claim Issuance Policy name might look something like this:

The SAML authentication request had a NameID Policy that could not be satisfied.
Name identifier format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

SPNameQualifier:

Exception details:

MSIS7070: The SAML request contained a NameIDPolicy that was not satisfied by the issued token. Requested NameIDPolicy: AllowCreate: True Format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent SPNameQualifier: . Actual NameID properties: Format: , NameQualifier: SPNameQualifier: , SPProvidedId: .

Naming and Claim Issuance Policies

So, here lies the main brief of this blog post. What I’ve found when it comes to AD FS (particularly in v4 or Server 2016) and setting up claims is that you should always consider the name that you’ve given to the specific claim issuance policy.

SAML RPT’s would most likely have a number of claims as you want to bring across attributes and identifiers of users from Active Directory to whatever application you’ve integrated as an RPT. Without going into too much further detail on AD FS or RPT rabbit holes, that is enough to explain that claims setup under a Claim Issuance Policy need to be individually named.

Naming therefore seems to have relevance. What you name something can and does impact what is in a SAML token. Remember this!

Many application vendors configure SAML integration with AD FS or Azure AD and put out reasonably good documentation that I encourage you to always look at and follow closely for the right outcome.

What happens when there isn’t good documentation or the documentation is.. well shit? What do you do?

Well, when it comes to claim issuance policies, names matter. Again, remember this and for the most part, I’d say in a super generalised statement that is sure to spur many feedbacks; setup the RPT claims with correct naming and vendor specifications and if there’s any problems, it’s likely something or somewhere else (probably…application side) that could have a problem.

Final words

Here’s one key example and one that’s the source of inspiration for this blog post- “Name ID”. When you see it listed in the drop downs as an attribute to select: there’s a space between Name and ID.

Interesting that the Outgoing Claim Types all seem to have spaces in the way they’re written. Probably to make it easier to read for administrators.

Seeing that naming standard would naturally lead you to likely set the Claim Rule Name to something similar, like “Name ID”.

Setting the Claim Rule Name without any spaces, for example “NameID” could be the difference between a working RPT and a broken one.

Well, in my experience, here’s a note from the field: depending on what the app in your RPT is expecting in the SAML token, that space in the claim Rule Name could be sending that attribute incorrectly and cause you a right headache.