Keycloak: Home IdP Discovery
This is a simple Keycloak authenticator to redirect users to their home identity provider during login.
What is it good for?
When a federated user wants to login via Keycloak, Keycloak will present a username/password form and a list of configured identity providers to the user. The user needs to choose an identity provider to get redirected. This authenticator allows to skip the step of selecting an identity provider.
How does it work?
If this authenticator gets configured as part of a browser based login flow, Keycloak will present a username form (without password form and without list of configured identity providers). A user can then enter an email address. Keycloak will then choose an identity provider based on the provided email domain and forward the user to the chosen provider.
How to install?
Download a release (*.jar file) that works with your Keycloak version from the list of releases. Follow the below instructions depending on your distribution and runtime environment.
Wildfly-based distro
Create a Wildfly module and deploy it to your Keycloak instance. For details please refer to the official documentation.
For convenience, here is a module.xml file.
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.3" name="keycloak-home-idp-discovery">
<resources>
<resource-root path="keycloak-home-idp-discovery.jar"/>
</resources>
<dependencies>
<module name="org.keycloak.keycloak-services"/>
</dependencies>
</module>
Quarkus-based distro (Keycloak.X)
Copy the jar to the providers folder and execute the following command:
${kc.home.dir}/bin/kc.sh config
Container image (Docker)
For Docker-based setups mount or copy the jar to
/opt/jboss/keycloak/providersfor Wildfly-based distro or Keycloak.X prior to version15.1.0/opt/keycloak/providersfor Keycloak.X from version15.1.0
You may want to check docker-compose.yml as an example.
Maven/Gradle
Packages are being released to GitHub Packages. You find the coordinates here!
It may happen that I remove older packages without prior notice, because the storage is limited on the free tier.
How to configure?
Configure email domains
Email domains can be configured per identity provider. Currently, this can only be achieved via Identity Providers REST API.
PUT /{realm}/identity-provider/instances/{alias}
{
...
"config": {
"home.idp.discovery.domains": "example.com##example.net",
...
},
...
}
Note that domains need to be separated by two hashtags (##).
You can also use the Admin CLI (kcadm):
kcadm.sh update identity-provider/instances/{alias} -s 'config."home.idp.discovery.domains"="example.com##example.net"'
Configuration options
| Option | Description |
|---|---|
| Forward to linked IdP | If switched on, federated users (with already linked IdPs) will be forwarded to a linked IdP even if no IdP has been configured for the user's email address. Federated users can also use their local username for login instead of their email address. If switched off, users will only be forwarded to IdPs with matching email domains. |
Show configured email domains in Admin console
- Navigate to
Realm Settings - Click
Themestab - Choose
home-idp-discoveryfor theAdmin Console Theme - Click
Save - Reload the admin console (press F5 in your browser)
- Navigate to an identity provider
- Click
Home IdP Discoverytab
Frequently asked questions
Does it (already) work with Keycloak.X?
On October 28th 2021 the Keycloak project announced the roadmap for the new Quarkus-based Keycloak-X distribution. According to this Keycloak 16 will be the last preview of the Quarkus distribution. As of December 2021, Keycloak 17 will make the Quarkus distribution fully supported the WildFly distribution will be deprecated. Support for the Wildfly distribution will be removed by mid 2022.
Therefore, I will focus all further development of this library towards the Quarkus-based Keycloak.X distribution. Once the Wildfly support will be removed from the Keycloak project, I will remove all support for Wildfly here as well.
Don't worry, I will ensure this library stays compatible with the Wildfly distribution as well as with Keycloak.X until then.
Does it work with Keycloak version X.Y.Z?
If you are using Keycloak version X (e.g. X.y.z), version X.b.c should be compatible. Keycloak SPIs are quite stable. So, there is a high chance this authenticator will work with other versions, too. Check the details of latest build results for an overview or simply give it a try.
Authenticator version X.b.c is compiled against Keycloak version X.y.z. For example, version 12.3.1 will be compiled against Keycloak version 12.y.z.
I do not guarantee what version a.b or y.z will be. Neither do I backport features to older version, nor maintain any older versions of this authenticator. If you need the latest features or bugfixes for an older version, please fork this project or update your Keycloak instance. I recommend doing the latter on regular basis anyways.
![[BUG] domain configuration gets disappear when identity providers configuration saved from admin UI](https://avatars.githubusercontent.com/u/25844895?v=4)
![[BUG] Labels shown in select login method menu are not user friendly](https://avatars.githubusercontent.com/u/4125706?v=4)
![[Feature] Work nicely with Keycloak registration flow](https://avatars.githubusercontent.com/u/891092?v=4)
![[Feature] Allow extension of HomeIdpDiscoveryAuthenticator](https://avatars.githubusercontent.com/u/244253?v=4)
61 Nov 22, 2022
9 Sep 20, 2022
493 Dec 28, 2022
2 Jan 26, 2022
8 Aug 4, 2022
11.4k Jan 5, 2023
22 Dec 23, 2022
962 Dec 31, 2022
14.6k Jan 5, 2023
23 Sep 1, 2022
1.8k Dec 31, 2022
7 Mar 12, 2022
7 Jan 9, 2022
18 Dec 29, 2022
4 Apr 27, 2022
67 Dec 22, 2022
529 Dec 28, 2022
2 Sep 22, 2022
5 Jan 28, 2022
3 Oct 4, 2022