93 lines
No EOL
7.3 KiB
Text
93 lines
No EOL
7.3 KiB
Text
[[_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 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
|
|
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. |