keycloak/docs/documentation/server_admin/topics/organizations/managing-identity-providers.adoc

[id="managing-organization-identity-providers_{context}"]

[[_managing_identity_provider_]]
=  Managing identity providers
[role="_abstract"]

An organization might have its own identity provider as the single source of truth for their identities. In this case,
you want to configure the organization to authenticate users using the organization's identity provider, federate their
identities, and finally add them as a member of the organization.

An organization can have one or more identity providers associated with it so that they can authenticate their users from
different sources and enforce different constraints on each of them.

Before you can link an identity provider to an organization, you create an organization at the realm level from the *Identity Providers*
section in the menu. You can link any of the built-in social and identity providers available in the realm to an organization.

== Linking an identity provider to an organization

An identity provider can be linked to an organization from the *Identity providers* tab. If identity providers already exist, you see a list of them and options to search, edit, or unlink from the organization.

.Organization identity providers
image:images/organizations-identity-providers.png[alt="Organization identity providers"]

.Procedure

. Click *Link identity provider*
. Select an *Identity provider*
. Set the appropriate settings
. Click *Save*

.Linking identity provider
image:images/organizations-link-identity-provider.png[alt="Linking identity provider"]

An identity provider has the following settings:

Identity provider::
The identity provider you want to link to the organization. An identity provider can only be linked to a single organization.

Domain::
The domain from the organization that you want to link with the identity provider.

Excluded domains::
A comma-separated list of domains to skip automatic redirection. You can use wildcard domains like `*.example.com` to exclude all subdomains of `example.com`.

Hide on login page::
If this identity provider should be hidden in login pages when the user is authenticating in the scope of the organization.

Hide on login page when organization not resolved::
If enabled, the identity provider will be hidden on the login page when the organization cannot be resolved based on the user's email domain. Otherwise, the identity provider will be shown on the login page regardless of whether the organization is resolved or not. If 'Hide on login page' is also enabled, the identity provider will always be hidden on the login page.

Show on login page for unlinked members::
If enabled, organization members can see this identity provider on the login page even when they are already linked to another identity provider.

Redirect when email domain matches::
If members should be automatically redirected to the identity provider when their email domain matches the domain set to the identity provider. If the domain is set to `Any`, members whose email domain matches *any* of the organization domains will be redirected to the identity provider.

If the org is linked with multiple identity providers, the organization authenticator prioritizes the provider that matches the email domain of the user for automatic redirection. If none is found, it tries to locate one whose domain is set to `Any`.

Once linked to an organization, the identity provider can be managed just like any other in a realm by accessing the *Identity Providers* section in the menu. However, the options herein described are only available when managing the identity provider in the scope of an organization. The only exception is the
 *Hide on login page* option that is present here for convenience.

=== Mapping federated users to organization groups

When an identity provider is linked to an organization, you can configure mappers to automatically assign users authenticating through the IdP to organization groups based on claims or attributes from the external IdP.

==== Using the Hardcoded Group mapper

The Hardcoded Group mapper automatically adds all users authenticating through the IdP to a specific group.

.Procedure

. Click *Identity Providers* in the menu.
. Select your identity provider linked to your organization.
. Click the *Mappers* tab.
. Click *Add mapper*
. Select *Hardcoded Group* mapper type.
. Configure the mapper:

Name::
A descriptive name for this mapper.

Sync Mode Override::
How membership is managed (Import, Force, Inherit).

Group::
The group to assign users to. If the IdP is linked to an organization, you can either select realm groups or groups from that organization.

. Click *Save*.

IMPORTANT: Groups are filtered to the organization linked with this identity provider. If the IdP is unlinked from the organization, users will no longer be assigned to organization groups during authentication.

==== Using the Advanced Group mapper

The Advanced Group mapper assigns users to groups based on claim values from the external IdP.

.Procedure

. Click *Identity Providers* in the menu.
. Select your identity provider linked to your organization.
. Click the *Mappers* tab.
. Click *Add mapper*
. Select *Advanced Claim to Group*.
. Configure the mapper:

Name::
A descriptive name for this mapper.

Sync Mode Override::
How membership is managed (Import, Force, Inherit).

Claims::
Key-value pairs to match claims from the external IdP. Add claim names and their expected values. Users matching these claim values will be assigned to the specified group.

Regex Claim Values::
When enabled, claim values are treated as regular expressions for pattern matching. When disabled, values must match exactly.

Group::
The target group. If the IdP is linked to an organization, you can select groups from that organization alongside with realm groups.

. Click *Save*.

==== Group selection behavior

When configuring group mappers for an identity provider:

* *IdP linked to organization:* Both realm groups and groups from that organization are selectable
* *IdP not linked to organization:* Only realm groups are selectable
* *IdP unlinked from organization:* Existing organization group mappings are preserved but no longer active.

==== Runtime validation

When a user authenticates through an identity provider:

. The mapper checks if the IdP is still linked to an organization
. If the IdP is unlinked, organization group mappings are skipped
. Only realm group mappings continue to work
. A warning is logged to help administrators identify outdated mapper configurations
. Authentication continues successfully—no error is thrown to the user

This ensures that unlinking an IdP from an organization doesn't break authentication, but organization-specific mappings become inactive.

==== Migration considerations

If you unlink an identity provider from an organization:

* Review all mappers on that IdP
* Update any mappers referencing organization groups
* Consider changing those mappings to realm groups if needed
* Alternatively, re-link the IdP to the organization to restore group mappings

NOTE: Organization groups cannot be shared across organizations. If you move an IdP from one organization to another, update the group mappings accordingly.

== Editing a linked identity provider

You can edit any of the organization-related settings of a linked identity provider at any time.

.Procedure

. In the menu, click *Organizations* and go to the *Identity providers* tab.
. Locate the *identity provider* in the list.
+
You can use the search option for this step.
. Click the action button (three dots) at the end of the line.
. Click *Edit*.
. Make the necessary changes.
. Click *Save*.

.Editing linked identity provider
image:images/organizations-edit-identity-provider.png[alt="Editing linked identity provider"]

== Unlinking an identity provider from an organization

When an identity provider is unlinked from an organization, it remains available as a realm-level provider that is no longer associated with an organization. To delete the unlinked provider, use the *Identity Providers* section in the menu.

.Procedure

. In the menu, click *Organizations* and go to the *Identity providers* tab.
. Locate the *identity provider* in the list.
+
You can use the search capabilities for this step.
. Click the action button (three dots) at the end of the line.
. Click *Unlink provider*.

.Unlinking identity provider
image:images/organizations-unlink-identity-provider.png[alt="Unlinking identity provider"]