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 or use the Connectors APIs.
This is a paid edition feature and is unavailable in the community edition. Please visit our pricing page to learn more about paid editions.
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 using an OIDC Identity Provider, with a Connector the user doesn’t choose their identity provider; the administrator does. In addition, if the data source contains additional user profile information, a Connector allows you to map that into your user object. Finally, the data provider doesn’t have to implement the OIDC 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.usernameoruser.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. In addition, any 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.usernameoruser.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. -
user.insertInstant: the timestamp the user was created, useful for retaining history.
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 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.