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 his identity provider account through Account management.

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 with his password 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 Link Brokered Account::
Automatically link brokered identities without any validation with this authenticator. This is useful in an intranet environment of multiple user databases each with overlapping usernames/email addresses, but different passwords, and you want to allow users to use any password without having to validate. This is only reasonable if you manage all internal databases, and usernames/email addresses from one database matching those in another database belong to the same person. Set the authenticator requirement to "Alternative".

NOTE: The described setup uses two authenticators, and 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.