keycloak-scim/server_admin/topics/identity-broker/first-login-flow.adoc

[[_identity_broker_first_login]]

=== First Login Flow

When a user logs in through identity brokering some aspects of the user are imported and linked within the realm's local database.
When {project_name} successfully authenticates users through an external identity provider
there can be two situations:

* There is already a {project_name} user account imported and linked with the authenticated identity provider account.
  In this case, {project_name} will just authenticate as the existing user and redirect back to application.
* There is not yet an existing {project_name} user account imported and linked for this external user.
  Usually you just want to register and import the new account into {project_name} database, but what if there is an existing
  {project_name} account with the same email? Automatically linking the existing local account to the external
  identity provider is a potential security hole as you can't always trust the information you get from the external identity provider.

Different organizations have different requirements when dealing with some of the conflicts and situations listed above.
For this, there is a `First Login Flow` option in the IDP settings which allows you to choose a <<_authentication-flows, workflow>> that will be
used after a user logs in from an external IDP the first time.
By default it points to `first broker login` flow, but you can configure and use your own flow and use different flows for different identity providers.

The flow itself is configured in admin console under `Authentication` tab.
When you choose `First Broker Login` flow, you will see what authenticators are used by default.
You can re-configure the existing flow. (For example you can disable some authenticators, mark some of them as `required`, configure some authenticators, etc).

ifeval::[{project_community}==true]
You can also create a new authentication flow and/or write your own Authenticator implementations and use it in your flow.
See link:{developerguide_link}[{developerguide_name}] for more details.
endif::[]

==== Default First Login Flow

Let's describe the default behavior provided by `First Broker Login` flow.

Review Profile::
  This authenticator might display the profile info page, where the user can review their profile retrieved from an identity provider.
  The authenticator is configurable.
  You can set the `Update Profile On First Login` option.
  When `On`, users will be always presented with the profile page asking for additional information in order to federate their identities.
  When `missing`, users will be presented with the profile page only if some mandatory information (email, first name, last name) is not provided by the identity provider.
  If `Off`, the profile page won't be displayed, unless user clicks in later phase on `Review profile info` link (page displayed in later phase
  by `Confirm Link Existing Account` authenticator).

Create User If Unique::
  This authenticator checks if there is already an existing {project_name} 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 {project_name} 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 {project_name} account and the user will need to link the identity provider account through Account management.

NOTE: If you want to skip the ability to create new users, but you want that users authenticated from identity provider must already exists in {project_name} with same username or email like the user from identity provider, you can create new flow and replace `Create User If Exists` authenticator with `Detect Existing Broker User` . More details in the <<Detect Existing User First Login Flow,examples below>>.
  
Confirm Link Existing Account::
  On the info page, the user will see that there is an existing {project_name} account with the same email.
  They can review their profile again and use different email or username (flow is restarted and goes back to `Review Profile` authenticator).
  Or they can confirm that they want to link their identity provider account with their existing {project_name} account.
  Disable this authenticator if you don't want users to see this confirmation page, but go straight to linking identity provider account by email verification or re-authentication.

Verify Existing Account By Email::
  This authenticator is `ALTERNATIVE` by default, so it's used only if the realm has SMTP setup configured.
  It will send email to the user, where they can confirm that they want to link the identity provider with their {project_name} account.
  Disable this if you don't want to confirm linking by email, but instead you always want users to reauthenticate with their password (and alternatively OTP).

Verify Existing Account By Re-authentication::
  This authenticator is used if email authenticator is disabled or not available (SMTP not configured for realm). It will display a login screen
  where the user needs to authenticate to link their {project_name} account with the Identity provider.
  User can also re-authenticate with some different identity provider, which is already linked to their {project_name} account.
  You can also force users to use OTP. Otherwise it's optional and used only if OTP is already set for the user account.

==== Automatically Link Existing First Login Flow
WARNING: The AutoLink authenticator would be dangerous in a generic environment where users can register themselves using arbitrary usernames/email addresses. Do not use this authenticator unless registration of users is carefully curated and usernames/email addresses are assigned, not requested.

In order to configure a first login flow in which users are automatically linked without being prompted, create a new flow with the following two authenticators:

Create User If Unique::
This authenticator ensures that unique users are handled. Set the authenticator requirement to "Alternative".

Automatically Set Existing User::
Automatically sets an existing user to the authentication context without any verification. Set the authenticator requirement to "Alternative".

NOTE: The described setup uses two authenticators. This setup is the simplest one, but it is possible to use other
authenticators according to your needs. For example, you can add the Review Profile authenticator to the beginning of the flow if you still want
end users to confirm their profile information. You can also add authentication mechanisms to this flow, forcing a user to verify his credentials. This
would require a more complex flow, for example setting the "Automatically Set Existing User" and "Password Form" as "Required" in an "Alternative" sub-flow.

[[_disabling_automatic_user_creation]]
==== Disabling Automatic User Creation
The Default first login flow will look up a Keycloak account matching the external identity, and will then offer to link them; if there is no matching Keycloak account, it will automatically create one.
This default behavior may be unsuitable for some setups, for example, when using read-only LDAP user store (which means all users are pre-created).
In this case, automatic user creation should be turned off. To disable user creation:

* open the `First Broker Login` flow configuration;
* set `Create User If Unique` to `DISABLED`;
* 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.

NOTE: 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.