First login flow

When users log in through identity brokering, Keycloak imports and links aspects of the user within the realm’s local database. When Keycloak successfully authenticates users through an external identity provider, two situations can exist:

  • Keycloak has already imported and linked a user account with the authenticated identity provider account. In this case, Keycloak authenticates as the existing user and redirects back to the application.

  • No account exists for this user in Keycloak. Usually, you register and import a new account into the Keycloak database, but there may be an existing Keycloak account with the same email address. Automatically linking the existing local account to the external identity provider is a potential security hole. You cannot always trust the information you get from the external identity provider.

Different organizations have different requirements when dealing with some of these situations. With Keycloak, you can use the First Login Flow option in the IDP settings to choose a workflow for a user logging in from an external IDP for the first time. By default, the First Login Flow option points to the first broker login flow, but you can use your flow or different flows for different identity providers.

The flow is in the Admin Console under the Authentication tab. When you choose the First Broker Login flow, you see the authenticators used by default. You can re-configure the existing flow. For example, you can disable some authenticators, mark some of them as required, or configure some authenticators.

You can also create a new authentication flow, write your own Authenticator implementations, and use it in your flow. See Server Developer Guide for more information.

Default first login flow authenticators

Review Profile

  • This authenticator displays the profile information page, so the users can review their profile that Keycloak retrieves from an identity provider.

  • You can set the Update Profile On First Login option in the Actions menu.

  • When ON, users are presented with the profile page requesting additional information to federate the user’s identities.

  • When missing, users are presented with the profile page if the identity provider does not provide mandatory information, such as email, first name, or last name.

  • When OFF, the profile page does not display unless the user clicks in a later phase on the Review profile info link in the page displayed by the Confirm Link Existing Account authenticator.

Create User If Unique

This authenticator checks if there is already an existing Keycloak account with the same email or username like the account from the identity provider. If it’s not, then the authenticator just creates a new local Keycloak account and links it with the identity provider and the whole flow is finished. Otherwise it goes to the next Handle Existing Account subflow. If you always want to ensure that there is no duplicated account, you can mark this authenticator as REQUIRED. In this case, the user will see the error page if there is an existing Keycloak account and the user will need to link the identity provider account through Account management.

  • This authenticator verifies that there is already a Keycloak account with the same email or username as the identity provider’s account.

  • If an account does not exist, the authenticator creates a local Keycloak account, links this account with the identity provider, and terminates the flow.

  • If an account exists, the authenticator implements the next Handle Existing Account sub-flow.

  • To ensure there is no duplicated account, you can mark this authenticator as REQUIRED. The user sees the error page if a Keycloak account exists, and users must link their identity provider account through Account management.

Confirm Link Existing Account

  • On the information page, users see a Keycloak account with the same email. Users can review their profile again and use a different email or username. The flow restarts and goes back to the Review Profile authenticator.

  • Alternatively, users can confirm that they want to link their identity provider account with their existing Keycloak account.

  • Disable this authenticator if you do not want users to see this confirmation page and go straight to linking identity provider account by email verification or re-authentication.

Verify Existing Account By Email

  • This authenticator is ALTERNATIVE by default. Keycloak uses this authenticator if the realm has an SMTP setup configured.

  • The authenticator sends an email to users to confirm that they want to link the identity provider with their Keycloak account.

  • Disable this authenticator if you do not want to confirm linking by email, but want users to reauthenticate with their password.

Verify Existing Account By Re-authentication

  • Use this authenticator if the email authenticator is not available. For example, you have not configured SMTP for your realm. This authenticator displays a login screen for users to authenticate to link their Keycloak account with the Identity Provider.

  • Users can also re-authenticate with another identity provider already linked to their Keycloak account.

  • You can force users to use OTP. Otherwise, it is optional and used if you have set OTP for the user account.

The AutoLink authenticator is dangerous in a generic environment where users can register themselves using arbitrary usernames or email addresses. Do not use this authenticator unless you are carefully curating user registration and assigning usernames and email addresses.

To configure a first login flow that links users automatically without prompting, create a new flow with the following two authenticators:

Create User If Unique

This authenticator ensures Keycloak handles unique users. Set the authenticator requirement to Alternative.

Automatically Set Existing User

This authenticator sets an existing user to the authentication context without verification. Set the authenticator requirement to "Alternative".

This setup is the simplest setup available, but it is possible to use other authenticators. For example: * You can add the Review Profile authenticator to the beginning of the flow if you want end users to confirm their profile information. * You can add authentication mechanisms to this flow, forcing a user to verify their credentials. Adding authentication mechanisms requires a complex flow. For example, you can set the "Automatically Set Existing User" and "Password Form" as "Required" in an "Alternative" sub-flow.

Disabling automatic user creation

The Default first login flow looks up the Keycloak account matching the external identity and offers to link them. If no matching Keycloak account exists, the flow automatically creates one.

This default behavior may be unsuitable for some setups. One example is when you use a read-only LDAP user store, where all users are pre-created. In this case, you must switch off automatic user creation.

To disable user creation:

Procedure

  1. Click Authentication in the menu.

  2. Select First Broker Login from the list.

  3. Set Create User If Unique to DISABLED.

  4. Set Confirm Link Existing Account to DISABLED.

This configuration also implies that Keycloak itself won’t be able to determine which internal account would correspond to the external identity. Therefore, the Verify Existing Account By Re-authentication authenticator will ask the user to provide both username and password.

Detect existing user first login flow

In order to configure a first login flow in which:

  • only users already registered in this realm can log in,

  • users are automatically linked without being prompted,

create a new flow with the following two authenticators:

Detect Existing Broker User

This authenticator ensures that unique users are handled. Set the authenticator requirement to Mandatory.

Automatically Set Existing User

Automatically sets an existing user to the authentication context without any verification. Set the authenticator requirement to Mandatory.

You have to set the First Login Flow of the identity provider configuration to that flow. You could set the also set Sync Mode to force if you want to update the user profile (Last Name, First Name…​) with the identity provider attributes.

This flow can be used if you want to delegate the identity to other identity providers (such as github, facebook …​) but you want to manage which users that can log in.

With this configuration, Keycloak is unable to determine which internal account corresponds to the external identity. The Verify Existing Account By Re-authentication authenticator asks the provider for the username and password.