Unexpected error when authenticating with Identity provider, duplicate key value violates unique constraint constraint_40

Version/Environment (if relevant):

4.x thru latest release 5.5.2, involving Keycloak integrations with SSO (like okta, websso, etc).

Issue:

An individual user attempts to login and sees "Unexpected error when authenticating with Identity provider":

A first troubleshooting step when encountering issues like this involves testing a different browser and/or removing all cookies and cache.  But that doesn't help in this case, instead grepping/searching for "exception" in keycloak logs, like:

kubectl logs -n domino-platform keycloakpodname --timestamps | grep -i exception

leads to a clue:

2023-04-25T13:06:37.247217108Z ESC[0mESC[31m13:06:37,247 ERROR [org.hibernate.engine.jdbc.spi.SqlExceptionHelper] (default task-3858) ERROR: duplicate key value violates unique constraint "constraint_40"
2023-04-25T13:06:37.247219975Z   Detail: Key (identity_provider, user_id)=(domino-credentials, 39a47782-8c3e-46d1-9091-a7105ff795ea) already exists.

Root Cause:

Domino requests that Keycloak verify authentication against SSO, and based on the response from SSO, Keycloak is trying to create a new record (user_id) for the combo of "Provider Username"  and email address.  Keycloak is behaving this way because it assumes a new record is needed due to detecting some change in the username or email address or other.  For example if the SSO SAML response returns an email address with an upper case letter keycloak will assume that new record should be added.

The Keycloak error occurs because one of either the username or "Provider User ID" already exist, hence the "duplicate key" violation.

Resolution:

In Keycloak UI navigate into the individual user record, hit the "Remove" button on the "Identify Provider Links" tab (see above screenshot), then have the user re-attempt login into the Domino UI.

Notes/Information:

To fully understand why Keycloak is assuming that a new record is needed for the user you need to review the SAML requests and responses between Keycloak and the SSO provider.