[keycloak-user] Setting NameID to Unspecified

Tue Apr 9 16:05:46 EDT 2019

There is a bit of misinformation floating around this thread, hopefully 
I can clarify a few things.

The SAML spec defines the following NameIDFormats:

unspecified
emailAddress
X509SubjectName
WindowsDomainQualifiedName
kerberos
entity
persistent
transient

NOTE: there are some extension formats defined outside the SAML core 
spec, for example: eduPersonTargetedID

If you want to know what each of these mean refer to the saml-core 2.0 
specification.

The spec defines unspecified as: "The interpretation of the content of 
the element is left to individual implementations." But note this means 
both the relying party (e.g. SP) and the assertion provider (e.g. IdP, 
Keycloak) must agree. There would have to be mechanisms in place for 
Keycloak to extract a certain value on a per client (relying party) 
basis when the format is unspecified. To the best of my knowledge there 
is no such mechanism in Keycloak (yet).

Out of the above list Keycloak supports the following NameIDFormats:

unspecified
emailAddress
persistent
transient

With unspecified or an unsupported format Keycloak returns the user's 
username.

IMPORTANT: nameID's are NOT the same as attributes!

IMPORTANT: Traditionally relying parties that need a specific subject 
identifier are supposed to either extract that from one of the returned 
attributes or synthesize it from one or more of the returned attributes. 
This is where Keycloak's attribute mappers come into play. You can 
configure what attributes to return to facilitate this. But remember 
attributes != nameID and it's the client's job to do this.

IMPORTANT: Abusing SAML's nameID is a common problem usually born out of 
a misunderstanding of SAML concepts. The usual recommendation is to fix 
non-compliant implementations rather than introduce hacks to accommodate 
them.

Note: The Shibboleth IdP has support for per relying party custom nameID 
generation (to the best of my knowledge Keycloak has nothing like this). 
This is described here:

https://wiki.shibboleth.net/confluence/display/IDP30/CustomNameIDGenerationConfiguration 

But please note the section on the use of the unspecified format where 
it says: "We strongly urge deployers to avoid the use of this Format 
when possible. Note that in many cases when vendors claim to "require" 
its use, what they really mean (aside from "we're not interesting in 
supporting SAML properly") is that they don't care what Format you use."

You might also find this Shibboleth wiki entry on NameID useful:

https://wiki.shibboleth.net/confluence/display/CONCEPT/NameIdentifiers

FINALLY: NameID's in SAML have been a long standing source of pain, 
there is an effort to replace this part of SAML with a better mechanism, 
see this RFC:

http://docs.oasis-open.org/security/saml-subject-id-attr/v1.0/csprd02/saml-subject-id-attr-v1.0-csprd02.html

FOOTNOTE: My references to Shibboleth in the context of Keycloak are not 
meant to diminish Keycloak in any fashion whatsoever. Rather since 
Shibboleth is the oldest SAML implementation and it's architect Scott 
Cantor is a key member of the SAML committee and the fact it has 
widespread adoption means when it comes to finding any kind of decent 
documentation on SAML it's often found among the Shibboleth docs and/or 
mailing list. Keycloak has many features, including OpenID support that 
are absent in Shibboleth making Keycloak an excellent implementation 
choice among a host of other reasons to select Keycloak. No reason not 
to refer to the Shibboleth doc just to expand your conceptual 
understanding though.

On 4/9/19 2:17 PM, Aaron Echols wrote:
> Wouldn't you just need to add a mapper under your client to map to
> username, then set SAML Attribute NameFormat to unspecified there? Maybe
> I'm wrong, but that seems like the correct way to do this per client.
> --
> Aaron Echols
> 
> On Mon, Apr 8, 2019 at 5:07 AM Ron Alleva <ronallevatech at gmail.com> wrote:
> 
>> Hi Manuel,
>>
>> Thanks for replying. That url does help me understand the difference
>> between the different identifier types.
>>
>> However, the client I'm working with has it set in their IdP that the SAML
>> message sent to it should contain one of the user's attributes (specific
>> string of numbers, like a special user id) in the NameID field, with a
>> format of unspecified. In Keycloak (at least 4.4 and 5.0, that I checked),
>> there's no option for "unspecified" in the NameID format setting, or a way
>> to remove it altogether to default to unspecified.
>>
>> Is this something Keycloak can support out of the box? Is it something I
>> can accomplish with a JavaScript protocol mapper, or do I have to code my
>> own mapper for that purpose?
>>
>> Thanks,
>>
>> Ron
>>
>> On Mon, Apr 8, 2019, 05:03 Manuel Waltschek <
>> manuel.waltschek at prisma-solutions.at> wrote:
>>
>>> Hello Ron,
>>>
>>> maybe this url will help you:
>>>
>> https://stackoverflow.com/questions/11693297/what-are-the-different-nameid-format-used-for
>>>
>>> As the answer states unspecified can be used and it purely depends on the
>>> entities implementation on their own wish. So as I understand you have to
>>> send the nameId in some format, but have to decide for one format to send
>>> the client on keycloak site. Unspecified often defaults to the
>>> implementation specific default settings.
>>>
>>> Regards,
>>>
>>> Manuel
>>>
>>>
>>>
>>> -----Ursprüngliche Nachricht-----
>>> Von: keycloak-user-bounces at lists.jboss.org <
>>> keycloak-user-bounces at lists.jboss.org> Im Auftrag von Ron Alleva
>>> Gesendet: Montag, 08. April 2019 04:52
>>> An: keycloak-user at lists.jboss.org
>>> Betreff: [keycloak-user] Setting NameID to Unspecified
>>>
>>> Hi all,
>>>
>>> I'm working with a particular IdP client, and they have requested that I
>>> set the NameID field to an attribute on the user that is neither username
>>> or email, and that it must be in the "unspecified" format.
>>>
>>> I've been trying a bunch of different configuration options to get it
>>> work, but none seem to do what I need it to do. I know about
>>> "saml.persistent.name.id.for.$clientId" on a user, and I've been trying
>>> variations on that.
>>>
>>> Does anyone have any guidance on how to have a attribute of the user be
>>> populated in the NameID field, with a format of "unspecified"?
>>>
>>> Thanks,
>>> Ron
>>> _______________________________________________
>>> keycloak-user mailing list
>>> keycloak-user at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/keycloak-user
>>>
>> _______________________________________________
>> keycloak-user mailing list
>> keycloak-user at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/keycloak-user
> _______________________________________________
> keycloak-user mailing list
> keycloak-user at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/keycloak-user
> 

-- 
John Dennis