FusionAuth Connectors

    Overview

    Available since 1.18.0

    Connectors allow you to connect other sources of user data to your FusionAuth instance. Once the connection is created, you may either:

    • Authenticate the user against the external data source, or

    • Authenticate and migrate the user from the external data source to FusionAuth

    The following Connectors are currently available:

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

    Find the FusionAuth Identity Providers in the administrative user interface by navigating to Settings → Connectors or use the Connectors APIs.

    Choose what type of Connector to create.

    Authentication

    Using a Connector for authentication alone results in similar functionality to using the data source as an OIDC Identity Provider. Subsequent logins continue to use the external source as the System of Record, including for user data such as registrations and group membership.

    In contrast to the typical usage of an Identity Provider, with a Connector the user doesn’t choose their identity provider; the administrator does. (Though an administrator can use the idp_hint parameter to force certain Identity Provider.) In addition, if the data source contains additional user profile information, a Connector allows you to map that into your user object. Finally, the identity data provider doesn’t have to implement the OIDC or SAML specification.

    Using a Connector for authentication allows you to use an external user management system as another data source for FusionAuth. If the data source can speak LDAP or HTTP, you can authenticate users against it.

    The user will be placed into the same tenant as the application they are authenticating against.

    Required Fields

    If you are authenticating a user, you must provide the following fields in the user object you return.

    • user.username or user.email

    • user.id: a FusionAuth compatible UUID

    If you are using the generic connector, you are building the user object, so ensure these fields are in the JSON. If you are using the LDAP connector, make sure you set these fields in the configured LDAP Reconcile lambda.

    In addition, ensure that the same user.id is returned each time a user is retrieved. If you have an LDAP attribute in the form of a UUID or a value that can be translated to a UUID, using that attribute or its translation is recommended. If you have to generate a UUID, ensure that you are able to return the same value each time the user authenticates. Doing so ensures that FusionAuth knows which user is being referenced, even if the username or email address changes.

    Suggested Fields

    If you are authenticating a user, you likely want to populate these fields:

    • user.registrations: the applications to which this user should have access. Providing at least one entry in this array will associate a user with an application in FusionAuth, authorizing them to access the application. At a minimum, you likely want to add the application the user is logging into.

    Migration

    In this scenario, the user data is migrated from the external data source to FusionAuth. Subsequent logins will authenticate against FusionAuth, not the external data store. The external data store is never again consulted for any login of the migrated user. In addition, any future changes in the external data store will not be propagated to FusionAuth.

    Using a Connector in this way allows for a phased migration. Let your users sign in and migrate their data as they do so. All changes to user data like group membership should then be made in FusionAuth. You can run the old system for a time, then shut it off and remove its configuration, then relying on FusionAuth for all user authentication.

    The user will be placed into the same tenant as the application they are authenticating against.

    Required Fields

    If you are migrating a user, you must provide the following fields in the user object you return.

    • user.username or user.email

    • user.id: a FusionAuth compatible UUID

    If you are using the generic connector, you are building the user object, so ensure these fields are in the JSON. If you are using the LDAP connector, make sure you set these fields in the lambda.

    If you don’t have a UUID to associate with this user, you may create a random one, as the source datastore won’t be consulted after the user is initially migrated.

    Suggested Fields

    If you are migrating a user, you likely want to populate these fields:

    • user.registrations: the applications to which this user should have access. Providing at least one entry in this array will associate a user with an application in FusionAuth, authorizing them to access the application. At a minimum, you likely want to add the application the user is logging into.

    • user.data: arbitrary data associated with the user. This can be application or migration specific. For example, you could indicate the migration date of a user for subsequent searches.

    Connector Policies

    Connectors can be enabled on a per tenant basis. This is done with a Connector policy. These may change over time.

    In the following screenshot you will see that we have enabled two custom Connectors for the Default tenant. The default Connector is present as well.

    The Tenant Connector policy configuration tab.

    The order of operations matters for Connectors. The Connector policy rules are applied in order when a user authenticates for the first time.

    In the above system, first time users who have an email address with a domain example.com will be authenticated against the Active Directory Connector. If they are not found, they’ll be authenticated against the Legacy User API Connector. If they are not found in that system, the user will be authenticated against the FusionAuth Connector.

    Users who have an email address with any other domain will be authenticated against the Legacy User API Connector the first time they log in. If they are not found in that system, the user will be authenticated against the FusionAuth Connector.

    On authentication the Connector creates the user object and stores it into FusionAuth. Once a user is authenticated against a Connector, they will always be authenticated against that same data source. If a Connector is deleted, users will be authenticated against the Connectors in the order defined by the current policy.

    Domains

    A domain may be either be the string * in which case the Connector policy applies to all users, or one or more valid email domains such as example.com or piedpiper.com. If more than one domain is entered, they must be separated by newlines.

    Connectors Vs Identity Providers

    Connectors share many features with Identity Providers. Both can connect FusionAuth to an external system of record for user identity.

    How can you decide between them? While they each have strengths, these questions may be helpful in choosing:

    • Are you looking to migrate users into FusionAuth? A Connector is a better option.

    • Does your external system support a standard such as OIDC or SAML? An Identity Provider is what you want.

    • Are you looking to connect to a system which only supports LDAP? A Connector is the better fit.

    • Will the external system remain the system of record for the users? An Identity Provider is typically a better choice.

    • Does your existing identity store expose no standard way to share identity data? A Connector is the better option.

    Related Posts

    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.