Keycloak Custom Attribute IDP Linking

Keycloak default authenticator flows for external identity provider brokering only match existing users only on username and password attributes. If you want to lookup user with different attributes you can use this extension. If you for example get attribute eid from your external provider and want your local user, for example from ldap storage provider matched where you store this eid value in an attribute with name u_eid you can do so. Matching attributes will add identity provider links in keycloak and your users will not get created twice in your keycloak database. An example would be European Union eIDAS project with services/members like ID Austria.

Development

mvn clean install

docker-compose up

Update Plugin in container by running mvn install.

Attach remote jvm debug session on port 5005 (default).

Installation

Tested on Keycloak 15.0.2, 17.0.0, `22.0.3.

Keycloak >= v17.0.0

After Packaging the project with,

mvn package -f "./pom.xml"

deploy the keycloak-custom-attribute-idp-linking-2.0.1.jar to /opt/keycloak/providers and rebuild keycloak to bring this provider in.

Deploy custom attribute provider

# Sometimes (depending on versions), this dir is not present;
[ ! -d "/opt/keycloak/providers" ] && sudo mkdir /opt/keycloak/providers;
sudo mv keycloak-custom-attribute-idp-linking-2.0.1.jar /opt/keycloak/providers/keycloak-custom-attribute-idp-linking-2.0.1.jar;

Rebuild and Restart Keycloak

all-in-one: This is the suggested method, check Keycloak's Docs for more configuration options from the cli

# This will rebuild keycloak and make the provider available in the Keycloak admin console
sudo /opt/keycloak/bin/kc.sh start --auto-build;

build only:

/opt/keycloak/bin/kc.sh build

Keycloak <= 15.0.2

Copy or mount plugin in your keycloak installation depending on your environment (k8s, compose, gke). For example in /opt/jboss/keycloak/standalone/deployments/ (see file docker-compose.yml). You should see something like following in your keycloak log:

...
WFLYSRV0010: Deployed "keycloak-custom-attribute-idp-linking-1.0.0.jar" (runtime-name : "keycloak-custom-attribute-idp-linking-1.0.0.jar")
...

Now you can use Custom Attribute IDP Linking Authenticator in your Keycloak Authentication configuration.

Using the Provider

Setup below is only for testing and your production configuration might differ. Read more about Keycloak Authenticators and Flows Configurations.

[Optional] Check your external provider attribute mapping

If necessary check whether you really map and import the attribute you want to use for matching users.

Create Custom Authentication Flow

Go to Authentication and create a new Flow. In this example will call it Auto-linking. Next add this extensions Custom Attribute IDP Linking execution as well as the standard Automatically Set Existing User as a fallback.

Adjust configuration to your needs. Attribute name on external side and lookup attribute for existing users.

Set first login flow

Set first login flow in your identity provider configuration to your newly created custom flow.

[Optional ;)] Check config

Login in using your external provider and check if user get linked to the provider.