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:

  • Not setting up an Identity Provider.
  • Limiting the applications for which an Identity Provider is configured.
  • Doing additional verification in a Reconcile Lambda to ensure that the email address or identifier provided by the Identity Provider is expected.
  • Using a Disabled linking strategy for an Identity Provider and managing links via the Links API. This allows business logic to execute before or during linking. Examples include disallowing any links to a certain domain or calling into another API for additional validation before creating a link.

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.

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…identities will be linked using the API. Use this when you want to manage linking explicitly using the Link API. Added in version 1.37.0.
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.

However, this strategy may not work if you do not have access to the identityProviderUserId, which is the immutable Id of the user in the upstream identity provider. See the Link API for more.

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.

  • Richard clicks on the ‘Login With Hooli’ button on the login screen.
  • He logs in to Hooli with richard@hooli.com, his account at Hooli.
  • He is redirected to FusionAuth.
  • He is prompted to log in to FusionAuth with his Pied Piper email and password.
  • He logs in with richard@piedpiper.com.
  • The FusionAuth account with the email richard@piedpiper.com is linked to the Hooli richard@hooli.com account.
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.

  • Richard clicks on the ‘Login With Hooli’ button on the login screen.
  • He logs in to Hooli with richard@hooli.com, his account at Hooli.
  • He is redirected to FusionAuth.
  • There is an account created in FusionAuth with no username or email address. It is not a full account.
  • Richard can interact with Pied Piper (a JWT is issued, etc), but cannot use FusionAuth workflows like ‘forgot password’.
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.

  • Richard clicks on the ‘Login With Hooli XYZ’ button on the login screen.
  • He logs in with richard@hoolixyz.com.
  • He is redirected to FusionAuth.
  • There is an account created in FusionAuth with no username or email address. It is not a full account.
  • Richard can interact with Pied Piper (a JWT is issued, etc), but cannot use FusionAuth workflows like ‘forgot password’.

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.

  • Link On Email. Create the user if they do not exist. creates a user if no matching account exists in FusionAuth.
  • Link On Email. Do not create the user if they do not exist. does not create a user if no matching account exists and treats such a login as an error. If a matching account exists, the login succeeds.

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.

  • Richard clicks on the ‘Login With Hooli’ button on the login screen.
  • He logs in to Hooli with the richard@piedpiper.com account.
  • He is redirected to FusionAuth and logs in successfully. Access is allowed.
  • The FusionAuth account with the email richard@piedpiper.com is linked to the Hooli richard@piedpiper.com account.

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.

  • Richard clicks on the ‘Login With Hooli’ button on the login screen.
  • He logs in to Hooli with the richard@piedpiper.com account.
  • He is redirected to FusionAuth but sees an error. No access is allowed.

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.

  • Richard clicks on the ‘Login With Hooli’ button on the login screen.
  • He logs in to Hooli with the richard@piedpiper.com account.
  • He is redirected to FusionAuth.
  • A new account is created in FusionAuth with the email richard@piedpiper.com.
  • The new FusionAuth account with the email richard@piedpiper.com is linked to the Hooli richard@piedpiper.com account.

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

  • Link On Username. Create the user if they do not exist. creates a user if no matching account exists in FusionAuth.
  • Link On Username. Do not create the user if they do not exist. does not create a user if no matching account exists and treats such a login as an error. If a matching account exists, the login succeeds.

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.

  • Richard clicks on the ‘Login With Hooli’ button on the login screen.
  • He logs in to Hooli with the richard account.
  • He is redirected to FusionAuth and logs in successfully. Access is allowed.
  • The FusionAuth account with the username richard is linked to the Hooli richard account.

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.

  • Richard clicks on the ‘Login With Hooli’ button on the login screen.
  • He logs in to Hooli with the richard account.
  • He is redirected to FusionAuth but sees an error. No access is allowed.

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.

  • Richard clicks on the ‘Login With Hooli’ button on the login screen.
  • He logs in to Hooli with the richard account.
  • He is redirected to FusionAuth.
  • A new account is created in FusionAuth with the username richard.
  • The new FusionAuth account with the username richard is linked to the Hooli richard account.

Limitations

Some Identity Providers, such as the Google and OIDC Identity Providers, request access tokens from a configured remote URL. Remote servers must respond within a certain time frame or the login workflow will fail.

The limit is currently 10 seconds. It is not configurable.