[keycloak-dev] Proposal: more flexible brokered identity with SAML IdP

[Dmitry Telegin]

Background
==========

Consider the problem: we are preparing a Keycloak deployment with the
following properties:
- users come from LDAP/AD, self-registration disabled;
- vast majority of the users will be authenticating via a 3rd party
SAML IdP that shares user DB with our Keycloak.

To make onboarding easier, we want to free the users from the need to
manually link their accounts with the IdP, by mass pre-creating the
links programmatically using Admin REST API.

In theory, this should be doable by issuing a POST to
users/{id}/federated-identity/saml, passing IdP's userId and userName,
which should create and persist a FederatedIdentity instance.

In practice, we're hitting a roadblock because of how SAML brokered
identities are implemented in Keycloak.

Problem
=======

Currently, it is hardcoded [1] that FederatedIdentity's userId and
userName should be taken verbatim from SAML assertion's NameID value
(via intermediary BrokeredIdentityContext). The problem is that most
SAML IdPs provide meaningless NameIDs, like hashes or purely random
strings. In general, SAML NameID is not predictable. To make things
worse, NameID can be different for SPs, so we can't simply peek it in
another application already integrated with the IdP.

OTOH, incoming assertion is guaranteed to contain other attributes that
are well-known to us and uniquely identify the user, like e.g. mobile
phone number.

[1] https://github.com/keycloak/keycloak/blob/master/services/src/main/
java/org/keycloak/broker/saml/SAMLEndpoint.java#L398 

Solution
========

The problem could be solved by introducing a configurable (and thus
more flexible) mechanism to map SAML assertions to FederatedIdentities.
With that, we could instruct Keycloak to take userId and userName from
arbitrary assertion attributes, or even complex expression, similar to
what we have in UsernameTemplateMapper.

Questions are:
1. From what I've learned, this should be doable with the help of a
custom IdP mapper, using preprocessFederatedIdentity() method. Is that
correct?
2. Regardless of the answer to 1, would Keycloak team welcome this
contribution?

Some thoughts not directly related to this particular problem; from my
3+ years experience with Keycloak and its corporate users, I can surely
tell that SAML under no circumstances should be considered either
legacy or obsolete. It is *very* actively used in the areas like
fintech, education and healthcare. I'd myself be happy to see Keycloak
become 1st class SAML IdP/broker, and going to do my best to make it
happen. I'm particularly interested in improving SAML/OIDC
interoperability in terms of IdP-initiated SSO and token exchange.

Best regards,
Dmitry