How does AM (All versions) use account mapping to identify the end user from a SAML Assertion?
The purpose of this article is to provide information on how AM identifies the end user from a SAML Assertion using account mapping, specifically the NameID element. Understanding account mapping will help you configure SAML federation correctly.
1 reader recommends this article
Account mapping in SAML
Note
All the account mapping related logic is extensible and these features are part of the default implementation (DefaultLibrarySPAccountMapper or DefaultIDPAccountMapper). See How do I create a custom SAML2 SP account mapper in AM (All versions)? and How do I create a custom SAML2 IdP account mapper in AM (All versions)? for further information.
An Assertion can identify an end user either by specifying a unique identifier within the NameID element or by providing SAML attributes within the Assertion to allow the remote entity to perform a lookup based on the provided data.
The NameID value's format is dependent on the NameID-Format being used:
- The transient and persistent NameID-Formats have additional restrictions on the NameID value; both of them should be an opaque identifier and
must not
have any relation to the user's identity. In other words, the NameID would look like this: <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" NameQualifier="samlidp" SPNameQualifier="corbinsp">27DbY51ErokOremYdvFBfe9HiHee</saml:NameID> This also means that if an IdP sends an Assertion for the first time to an SP, then the user's identity cannot be determined based on just the NameID value. In these scenarios, an AM SP normally just presents the login page to allow the end user to authenticate locally and then, depending on the NameID-Format, a link between the accounts is stored persistently:
- When using the transient NameID-Format, saving the value is pointless because each SAML authentication with the IdP will result in a different NameID value.
- When using the persistent NameID-Format, it is necessary to ensure that the account at the IdP always corresponds to the same account at the SP, hence this link needs to be persisted in the directory server.
- The unspecified NameID-Format has no restrictions on the actual NameID value, hence it can be anything, even the user's unique identifier across the systems.
In summary, the NameID persistence logic is as follows:
- Persistent NameID - NameID recommended be stored.
- Transient NameID - NameID must not be stored.
- Ignored user profile mode - NameID cannot be stored (fails if used in combination with persistent NameID-Format).
- For any other case - NameID may be stored based on customizable logic.
How does AM identify the end user from the incoming Assertion?
AM identifies the end user from the incoming Assertion based on these concepts:
- AM uses the local account linking mechanism by default; this means that the user does not have SSO when the transient NameID-Format is used, but for any other NameID-Format, a link is set up between the NameID value and the user account after a successful authentication at the SP.
- When using the transient NameID-Format, you can set up a Transient User, which means that each logged in user at the SP will be authenticated as that transient user, for example, 'anonymous'.
- You can also configure AM to handle the NameID value as the User ID, which is mostly useful when using non-transient or non-persistent NameID-Formats; this makes it possible to log users in with NameIDs such as: <saml:NameID>jdoe</saml:NameID>
- You can also use auto federation (which can be combined with the use of NameID as user ID), which allows the setup of an automatic link (without the initial login at the SP) based on the incoming assertion. This also means that SSO works correctly as well.
See Also
Persistent or transient federation
Related Training
N/A
Related Issue Tracker IDs
OPENAM-11921 (Incorrect NameId Format offered for SAML2 auth module in console)