Logo/Docs

Identity Providers Overview

Identity Providers

Identity Providers allow you to enable third-party login in FusionAuth. This includes social options such as Facebook and Google, and enterprise options such as OIDC and SAML.

Find the FusionAuth Identity Providers in the UI by navigating to Settings -> Identity Providers or use the Identity Providers APIs.

Identity Providers

Social Identity Providers

The following providers are available:

If you’re looking for a provider that is not listed here, review the open features in GitHub and either vote or comment on an existing feature, or open a new feature request if you do not find an existing feature open.

Enterprise Identity Providers

The following providers are available:

If you’re looking for a provider that is not listed here, review the open features in GitHub and either vote or comment on an existing feature, or open a new feature request if you do not find an existing feature open.

Identity Providers and Tenants

Identity providers can be configured to set a limit on the number of links that may be established on a per tenant basis.

In the following, we have enabled “Limit links per user” on the Default tenant and set a “Maximum link count” of 2. With this configuration, a user will only be able to establish at most two links for this IdP specifically.

Identity Providers

Identity Providers and Applications

Identity providers can be enabled or disabled on a per application basis.

In the following screenshot you will see that we have enabled this login provider for the Pied Piper application and enabled “Create registration”. Enabling “Create registration” means that a user does not need to be manually registered for the application prior to using this login provider.

Identity Providers

For example, when a new user attempts to log into Pied Piper using Google, if their user does not exist in FusionAuth it will be created dynamically, and if the Create registration toggle has been enabled, the user will also be registered for Pied Piper and assigned any default roles assigned by the application.

If you do not wish to automatically provision a user for this Application when logging in with Google, leave Create registration off and you will need to manually register a user for this application before they may complete login with Google and be authorized for the Pied Piper Application.

Regardless of whether you enable “Create registration” or not, a user may be created within FusionAuth when a person signs in with the identity provider. What happens depends on the configured linking strategy. This setting controls whether a user is registered and therefore authorized for this application.

When you enable an identity provider you’re indicating that this external provider is an additional SoR (Source of Record). When the user successfully logs into this provider such as Google, Google has told FusionAuth the user exists and their credentials are valid. In return FusionAuth accepts this source of record and creates link and/or user, depending on the linking strategy. Next we identify if the configuration allows us to automatically register (that is, provide authorization) for the requested application, based on the “Create registration” setting.

Overrides

For each application, you can provide different identity provider configurations. You might do this if you had two different applications that were both using Apple as an identity provider, but with different Apple configuration settings. You can override none, some or all of the configuration values by expanding the “Overrides” link for the given application assignment or modifying the identityProvider.applicationConfiguration values using the API.

Overriding Identity Provider settings

However, you cannot have two different Identity Providers for the same application. Use two different applications instead.

Additionally, override settings are not available in the External JWT, SAMLv2, or OpenID Connect Identity Providers. You can create multiple instances of these providers; that is the correct way to have multiple configurations for these providers

Hints

When you are using the FusionAuth hosted login pages, you can bypass the login page and go directly to a third party Identity Provider based upon the user’s email address or an Identity Provider Id.

Hints currently work with most Identity Providers with the exception of HYPR and the SAML v2 Identity Provider Initiated type Identity Provider.

An Identity Provider Id is appended to the Login URL for an application using the idp_hint request parameter. For example, to send a user directly to a login page for an OIDC identity provider with the id 44449786-3dff-42a6-aac6-1f1ceecb6c46, you’d append &idp_hint=44449786-3dff-42a6-aac6-1f1ceecb6c46.

An email address or domain may be provided in the login_hint request parameter. For example, to send a user directly to the login page of an OIDC IdP configured with a domain of example.com, you’d append &login_hint=example.com to the application’s Login URL. The use of this parameter is up to the Identity Provider, so adding this parameter may or may not be supported by the Identity Provider you are using.

You can read more about the login_hint and idp_hint parameters in the OAuth Endpoints documentation.

Account Security

When you configure an Identity Provider, you are explicitly trusting this federated identity system to authenticate users. MFA requirements and configuration, roles and groups, email or phone verification, and account identifiers are controlled by the provider.

Be careful who you allow to set up an Identity Provider. Your security is only as strong as the security of the platform to which you federate.

A malicious identity provider can negatively impact your system. For instance, it could create accounts with email addresses already in FusionAuth. This could lead to account takeover; the malicious user could log in to the identity provider, return to FusionAuth, and access user data.

Such attacks can be mitigated by:

Linking Strategies

Linking Strategies

The linking strategy is used when creating the link between the Identity Provider and the user account in FusionAuth.

Here’s a table illustrating the alternatives. Note that Disabled was added in version 1.37.0.

StrategyUser must existUser linked onUse when the identity provider…
Create a Pending LinkDepends on application, see note belowUser chooses account manually…shares a different email or username than an existing FusionAuth identity and users know enough to link them.
Disabled––When you want to manage linking explicitly using the Link API.
Anonymously LinkNoIdP id…exposes neither username nor email.
Link On Email. Create the user if they do not exist.NoEmail address…shares the user’s email and users that do not exist in the identity provider can have access.
Link On Email. Do not create the user if they do not exist.YesEmail address…shares the user’s email and you don’t want users that do not exist in FusionAuth to have access. Such users must be provisioned beforehand.
Link On Username. Create the user if they do not exist.NoUsername…shares the user’s username and users that do not exist in the identity provider can have access.
Link On Username. Do not create the user if they do not exist.YesUsername…shares the user’s username and you don’t want users that do not exist in FusionAuth to have access. Such users must be provisioned beforehand.

Some identity providers don’t provide a username and/or email. In those instances, it is recommended to consider using a pending link or creating an anonymous link. Both of these options enable you to link the user without an email or username in the response from the identity provider.

Linking and Create Registration

The Linking strategy and Create registration configurations are related to each other, but distinct. The Linking strategy controls how a User is created in FusionAuth based on information returned from the remote identity provider. Create registration controls if the User created in FusionAuth is registered for a given Application.

Linking Strategy Examples

Here are some walkthroughs of linking scenarios. A user, Richard, is trying to access an app, such as Pied Piper. Richard uses an Identity Provider to login. It doesn’t matter if the Identity Provider is a social provider like Facebook or an enterprise provider like an OIDC or SAML compatible identity server, the behavior is the same.

The FusionAuth hosted login pages are being used. Similar behavior is available via the Identity Provider API.

Disabled

Available since 1.37.0.

This is useful when you do not want to link automatically, and you wish to control all linking manually via the Link API. This provides you the greatest level of control of which users become linked from the identity provider to FusionAuth.

This is useful when the user has a different email or username in the remote identity provider than an existing FusionAuth identity. The user must know enough to link them. That is, they must remember the account they have in FusionAuth. This uses the linking strategy Create a Pending Link.

If the application configuration allows for self service registration, the user can register for an account in FusionAuth when a pending link strategy is chosen. Otherwise the user must exist in FusionAuth.

Richard is logging into Pied Piper. He has an account in FusionAuth with the email address richard@piedpiper.com. He also has an account at Hooli with the email address richard@hooli.com.

Screen prompting a user to connect their pending link account.

This is a useful option if you don’t want to create a full user account in FusionAuth. But see the Anonymous Account Limitations below. This uses the linking strategy Anonymous Link.

Richard is logging into Pied Piper. He doesn’t have an account in FusionAuth.

Admin view of a user who has linked anonymously.

Richard is logging into Pied Piper. He doesn’t have an account in FusionAuth. The identity provider is the Hooli XYZ server. This identity provider does not return a username or password in its response.

Anonymous Account Limitations

Users with an anonymous account may log in to applications using their IdP provided credentials.

They won’t have an email address, so can’t use any of the email based FusionAuth workflows like ‘forgot password’.

You also can’t modify the user using any FusionAuth APIs. If you try to modify the user using these, you must provide a username or email.

There are two strategies which link on an email address.

This uses the linking strategy Link On Email. Do not create the user if they do not exist..

Here, Richard is logging into Pied Piper. He has an account in FusionAuth with the email address richard@piedpiper.com.

This uses the linking strategy Link On Email. Do not create the user if they do not exist..

Richard is logging into Pied Piper. He doesn’t have an account in FusionAuth.

Here’s an example of the error page:

Error when a user must exist for successful linking.

This uses the linking strategy Link On Email. Create the user if they do not exist..

Richard is logging into Pied Piper. He doesn’t have an account in FusionAuth.

Similarly to linking on email, there are two options here.

This uses the linking strategy Link On Username. Do not create the user if they do not exist..

Richard is logging into Pied Piper. He has an account in FusionAuth with the username richard.

This uses the linking strategy Link On Username. Do not create the user if they do not exist..

Richard is logging into Pied Piper. He doesn’t have an account in FusionAuth.

This uses the linking strategy Link On Username. Create the user if they do not exist..

Richard is logging into Pied Piper. He doesn’t have an account in FusionAuth.