How to create a unique username mapper for an idp

[zsamji]

Issue/Question
When using VC on a newly provisioned realm I am being prompted with the message about a user with the same email address already existing in the database.
Reference: https://chat.developer.gov.bc.ca/channel/sso?msg=2AJpfNqWdnvB5aRuj

Additional context
After some discovery this found to be caused by the VC role mapping having no entry for username. It would create accounts with blank usernames.

[zsamji]

The Fix/Answer

You should always map an absolutely unique value to the username mapping EMAIL is not unique!. The challenge with VC is that the unique values found as claims are not accessible when creating the role mapping. Things like
${CLAIM.sub} or any other standard oidc claim are not accessible.

If you take a look at the keycloak code base (thanks @arcshiftsolutions !) you'll find there is a use case to generate UUIDs!

in the mapper you can enter ${UUID} to generate a UUID.

More discovery is required for why standard claims can't be used as a mapper for VC.

Note: the above is true not only for VCs, but for any IdP that for some reason will not provide a unique user identifier upon successful authentication.

In the specific case of VCs, the complexity is in the fact that the same IdP (vc-authn-oidc) is used to perform authentication responding to different proof-requests that require different VCs. In this case:

the unique identifier MAY be provided as an attribute by the VC, but this is not guaranteed
the unique identifier will likely be held by a differently named attribute for each VC
There is a way of binding the value f the unique identifier - if provided by the VC - to the standard sub field of an OIDC token, however it is true that standard fields don't seem to be processable by the username preprocessor in Keycloak.

Another thing worth noting in the case of VCs is that no authorization_token is provided by the IdP, only an id_token is generated: this is by design, since the VC IdP is not meant to perform any type of authorization check other than verifying the credentials that were received are valid.

Original Source: bcgov/ocp-sso#189