This is a simple Keycloak authenticator to redirect users to their home identity provider during login.
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.
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 domain part of the provided email address and forward the user to the chosen provider.
The identity provider will be chosen by the following preference:
- If the
forwardToLinkedIdp
config option is enabled- Use the first linked identity provider with matching domain
- Use the first linked identity provider
- Use non-linked identity provider with matching domain
- If the
forwadToLinkedIdp
config option is disabled- Use the first identity provider with matching domain
Only enabled and not link-only identity providers will be considered.
Download a release (*.jar file) that works with your Keycloak version from the list of releases.
Copy the jar to the providers
folder and execute the following command:
${kc.home.dir}/bin/kc.sh build
For Docker-based setups mount or copy the jar to /opt/keycloak/providers
.
You may want to check docker-compose.yml as an example.
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.
- Navigate to
Authentication
- Create a custom
Basic
flow - Click
Add execution
- Select
Home IdP Discovery
and add the execution - Set execution as required or alternative as desired
- Bind your newly created flow as desired - either as a default for the whole realm or on a per-client basis.
See the image below for an example:
To configure click settings/gear icon (⚙)
Option | Description |
---|---|
User attribute | The user attribute used to lookup the user's email address. If set to email (default) the authenticator will use the default email property. In this case the authenticator will only forward the user if the email has been verified. For any other attribute, the authenticator will not validate if the email has been verified. A common use case is to store a User Principal Name (UPN) in a custom attribute and forward users based on the UPN instead instead of their email address. |
Bypass login page | If switched on, users will be forwarded to their home IdP without the need to reenter/confirm their email address on the login page iff email address is provided as an OICD login_hint parameter or SAML subject/nameID .If switched off, users are only redirected after submitting/confirming their email address on the login page. (default) Note: This will take SAML ForceAuthn and OIDC prompt=login|consent|select_account parameters into account. If one of these parameters is present, the login page will not be bypassed even if switched on. |
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. (default) |
Forward to first matched IdP | If switched on, users will be forwarded to the first IdP that matches the email domain (default), even if multiply IdPs may match. If switched off, user will be shown all IdPs that match the email domain to choose one, iff multiple match. The user will only be able to choose from IdPs that match the email domain. Please note that also IdPs that have Hide on Login Page switched on will be shown.If only one IdP matches, behavior is the same as if switched on. |
Email domains can be configured per identity provider. Currently, this can only be achieved via Identity Providers REST API. Make sure to post the full body, as you may receive from a GET
request to the same endpoint, plus the home.idp.discovery.domains
configuration.
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"'
If you use multiple authenticator instances each using a different user attribute, you can specify different domains per user attribute as well.
For this to work, simply add a config key home.idp.discovery.domains.<attribute_name>
where <attribute_name>
is the name of the attribute you are using.
For example, when using a custom user attribute named upn
, add a key named home.idp.discovery.domains.upn
.
The authenticator will try to look up the specific key home.idp.discovery.domains.<attribute_name>
first and fallback to home.idp.discovery.domains
if the specific key does not exist.
PUT /{realm}/identity-provider/instances/{alias}
{
...
"config": {
"home.idp.discovery.domains": "example.com##example.net",
"home.idp.discovery.domains.upn": "enterprise.local",
"home.idp.discovery.domains.email": "example.org",
...
},
...
}
In the example above, the following domains will be effective when using the configured attribute name:
configured attribute name | effective domains |
---|---|
example.org | |
upn | enterprise.local |
notconfigured | example.com, example.net |
Please note that the lookup is case-insensitive, so email
will be the same as Email
or EMAIL
.
The authenticator supports internationalization and you can add additional languages or locales as needed.
Please see the Server Developer guide for detailed information.
When you configured this authenticator as an alternative to other authenticators, Keycloak may show a link "Try Another Way" during login as shown below:
When clicking that link, the user can select the login method based on configured alternative authenticators.
You can change the title and help text for this authenticator by adding the following messages to your custom theme:
home-idp-discovery-display-name=Home identity provider
home-idp-discovery-help-text=Sign in via your home identity provider which will be automatically determined based on your provided email address.
If multiple IdPs match the email domain of the user, the user may be presented with a dialog to choose an identity provider (see config option Forward to first matched IdP
).
You can change the title by adding the following messages to your custom theme:
home-idp-discovery-identity-provider-login-label=Select your home identity provider
Maybe! There is even a high chance it will, since this extension does not make use of any Quarkus-related functionality. For installation instructions, please refer to an older version of this readme.
Please note that with the release of Keycloak 20.0.0 the Wildfly-based distro is no longer supported. Hence, I dropped support for the Wildfly-based distro already. Though this library may still work with the Wildfly-based distro, I will no longer put any efforts into keeping this extension compatible.
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 16.3.1
will be compiled against Keycloak version 16.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.
For RedHat SSO versions, please check the corresponding Keycloak version here. Above rules apply ;)
Make sure that your users email is marked as verified. You can enable the Email verified
flag per user or switch on Trust Email
in the advanced settings of the identity provider.
You may want to increase the log level to see more fine-grained information on how the authenticator discovered the home identity provider.
Try to increase the log level to DEBUG
or even TRACE
level. Details can be found in the official Configuring logging guide.
The log category for the authenticator is de.sventorben.keycloak.authentication.hidpd
.