Skip to content

Improve docs around idp-domain links #53123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
vramik wants to merge 1 commit into
base: main
Choose a base branch
from
+53 −29
Draft

Improve docs around idp-domain links #53123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions docs/documentation/server_admin/topics/organizations/authenticating-members.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,14 +59,17 @@ and create an account at the realm.
After that, the administrator can send an invitation link to the user or manually add the user as a member of an organization.
For more details, see <<_managing_members_,Managing members>>.

If the organization has an identity provider without a domain and the *Hide on login page* setting is *OFF*, users can also click
If the organization has an identity provider with the *Hide on login page* setting *OFF*, users can also click
the identity provider link at the identity-first login page to automatically create an account and join an organization
once they authenticate through the identity provider.
For more details, see <<_managing_identity_provider_,Managing identity providers>>.

In a similar situation to the previous section, the organization may have a domain configured to route to an identity provider
with auto-redirect enabled.
In this situation, the user is redirected to the identity provider if that user's email matches the domain.
When a domain is linked to an identity provider and auto redirect is enabled, the user is automatically redirected to
that identity provider if their email matches the domain. When no identity provider is linked to the domain, or auto
redirect is disabled, the organization's available identity providers are shown for the user to select manually.
For details on how domain-to-identity-provider linking controls routing and email enforcement, see
<<managing-organization-domains_{context},Managing organization domains>>.

Once the flow completes, an account is created and the user joins the organization. In case the user has any first-factor credentials
configured (e.g.: password, passwordless, kerberos) to the account, the user is not automatically redirected to the identity provider but asked to authenticate using their
credentials.
Expand Down
60 changes: 41 additions & 19 deletions docs/documentation/server_admin/topics/organizations/managing-domains.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,45 @@ zero, one, or multiple domains.
When no domain is assigned, members are not validated against domain restrictions and email-based redirection to
identity providers is unavailable. A domain-less organization can still use auto-membership through a linked identity provider -- see <<authenticating-members_{context},Authenticating members>> for details.

== Linking a domain to an identity provider

Each domain can optionally be linked to one of the organization's identity providers.
This linking is configured from the *Domains* tab when editing a domain, using the following settings:

Identity provider::
The identity provider to associate with this domain. Linking a domain to an identity provider has two effects:
+
* *Login routing*: Determines which identity provider is offered or used when a user enters an email matching this domain. See <<authenticating-members_{context},Authenticating members>> for details on the identity-first login flow.
* *Email enforcement*: During the first broker login flow, users authenticating through the linked identity provider are required to use an email address that matches this domain. This prevents a user from changing their email on the profile review page to a domain that is not associated with the identity provider.
+
When no identity provider is linked, users with a matching email see the organization's available identity providers listed for manual selection, and no email domain restriction is enforced during profile review.

Auto redirect::
When enabled and an identity provider is linked, users with a matching email domain are automatically redirected to the identity provider without seeing a selection page. When disabled, the linked identity provider is still available for manual selection, and email enforcement remains active.
+
This setting has no effect when no identity provider is linked to the domain.

The following table summarizes the behavior for each configuration:

[cols="1,1,1", options="header"]
|===
| Configuration | Login screen | Email enforcement during first broker login

| Identity provider linked, auto redirect ON
| User is automatically redirected to the identity provider
| User's email must match this domain

| Identity provider linked, auto redirect OFF
| Organization's identity providers are shown for manual selection
| User's email must match this domain

| No identity provider linked
| Organization's identity providers are shown for manual selection
| No email domain restriction is enforced
|===

NOTE: Auto-membership is independent of domain-to-identity-provider linking. It is controlled by the *Auto membership* setting on the identity provider link (configured from the *Identity providers* tab) and requires that the user's email domain matches one of the organization's domains. An organization without any domains skips this check entirely. See <<_managing_identity_provider_,Managing identity providers>> for details.

== Domain types

Exact::
Expand All @@ -50,31 +89,14 @@ organization membership mapper.

== Configuring domain routing

Each domain can optionally be configured to route users to a specific identity provider
linked to the organization. This determines which identity provider handles authentication
for users whose email matches the domain.

Domain routing replaces the identity provider-level settings that were previously used to configure email domain matching.
The routing configuration is now on the domain itself, giving administrators fine-grained control over how each domain is handled.
To configure identity provider routing and auto-redirect for a domain:

.Procedure

. Navigate to the organization.
. Click the *Domains* tab.
. Click the domain name in the list, or click the action button and select *Edit*.
. In the edit dialog:
+
Identity provider::
Select the identity provider to route users to when their email matches this domain. The dropdown shows identity providers
linked to this organization, plus a *None* option. Selecting *None* means no routing is configured -- users with this email domain
will not be redirected to any identity provider and will see the standard login form instead.

Auto redirect::
When enabled, users whose email domain matches this domain are automatically redirected to the selected identity provider
without being shown the login form. When disabled, the identity provider is available for selection on the login page but
no automatic redirect occurs.
+
This setting has no effect when no identity provider is selected.
. Select the *Identity provider* and configure *Auto redirect* as described in <<linking-a-domain-to-an-identity-provider,Linking a domain to an identity provider>>.
+
If a user has first-factor credentials configured (for example, a password), the user is not automatically redirected but asked to authenticate using their credentials.

Expand Down
3 changes: 2 additions & 1 deletion ...ocumentation/server_admin/topics/organizations/managing-identity-providers.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ The identity provider you want to link to the organization. A single identity pr

Auto membership::
When enabled, users who authenticate through this identity provider are automatically added as members of the organization,
subject to the domain gate (see <<authenticating-members_{context},Authenticating members>>). Enabled by default.
provided their email domain matches one of the organization's domains. If the organization has no domains, the domain check
is skipped and all users from this identity provider are added. See <<authenticating-members_{context},Authenticating members>> for the full membership resolution flow. Enabled by default.

Membership type::
The membership type assigned to users who are auto-added through this identity provider link.
Expand Down
8 changes: 3 additions & 5 deletions js/apps/admin-ui/maven-resources/theme/keycloak.v2/admin/messages/messages_en.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3714,15 +3714,15 @@ removeDomainConfirm=Are you sure you want to remove this domain from the organiz
domainRemovedSuccess=Domain removed successfully
domainUpdatedSuccess=Domain updated successfully
domainHelp=The domain name used to match user email addresses to this organization. Wildcard domains (e.g. *.example.com) match all subdomains.
domainIdentityProviderHelp=Select from identity providers linked to this organization for email-based routing. If none are available, link an identity provider first from the Identity providers tab.
domainIdentityProviderHelp=The identity provider to use for this domain. Controls email-based routing at login and enforces that users authenticating through this provider use an email matching this domain. If left empty, users see the organization's available providers for manual selection and no email restriction is enforced during first login.
emptyDomains=No domains
emptyDomainsInstructions=There are no domains associated with this organization. Add a domain to enable email-based identity provider routing.
searchDomain=Search domain
autoRedirect=Auto redirect
autoRedirectHelp=If enabled, users with email addresses matching this domain will be automatically redirected to the linked identity provider.
autoRedirectHelp=If enabled and an identity provider is linked, users with email addresses matching this domain are automatically redirected to that provider without seeing a selection page. When disabled, the linked provider is still available for manual selection.
verified=Verified
autoMembership=Auto membership
autoMembershipHelp=If enabled, users authenticating through this identity provider will be automatically added as members of this organization.
autoMembershipHelp=If enabled, users authenticating through this identity provider are automatically added as members of this organization, provided their email domain matches one of the organization's domains. If the organization has no domains, all users from this provider are added regardless of email domain.
membershipTypeHelp=The membership type for users added through this identity provider. Managed means the user cannot exist outside this organization. Unmanaged means the user can exist independently. This field is disabled when auto membership is off or when another organization already claims managed membership for this identity provider.
duplicateDomain=A domain with this name already exists
organizationAliasHelp=The alias uniquely identifies an organization using a format that is mainly targeted for referencing the organization internally. For instance, when issuing organization-related claims into tokens or when in a custom theme.
Expand Down Expand Up @@ -3780,8 +3780,6 @@ noLinkedDomains=No linked domains
noLinkedDomainsInstructions=No organization domains are associated with this identity provider. Assign domains from an organization's domains tab.
organization=Organization
send=Send
redirectWhenEmailMatches=Redirect when email domain matches
redirectWhenEmailMatchesHelp=Automatically redirect the user to this identity provider when the email domain matches the domain
emailVerificationHelp=Independent timeout for email verification
idpAccountEmailVerificationHelp=Independent timeout for IdP account email verification
forgotPasswordHelp=Independent timeout for forgot password
Expand Down
Loading