FusionAuth Identity Providers

    Overview

    Identity Providers allow you to enable third-party login in FusionAuth.

    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.

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

    Identity Providers

    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 be 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.

    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.

    Strategy User must exist User linked on Use when the identity provider…​

    Create a Pending Link

    Depends on application, see note below

    User 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 Link

    No

    IdP id

    …​exposes neither username nor email.

    Link On Email. Create the user if they do not exist.

    No

    Email 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.

    Yes

    Email 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.

    No

    Username

    …​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.

    Yes

    Username

    …​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.

    • 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.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.