🔌 Connectors
Introduction
What is a connector?
Connectors play a critical role in Logto. With their help, Logto enables end-users to use passwordless registration or sign-in and the capabilities of signing in with social accounts. With the increasing popularity of websites and applications, passwordless and social sign-ins allow users to avoid managing numerous accounts and passwords.
😯 Sounds fascinating, uh? See "Configure connectors" if you want to set up an existing connector. If you can not find the connector you want to set up, you may develop those connectors by following the guides in "Create your connector".
Compositions
There are lots of properties in connector data.
To make the data loading and updating more efficient, we store part of connector data which will be modified frequently to DB and the rest of that locally.
- Local storage, also known as ConnectorMetadata, is an object containing fixed properties such as logo, connector type, and so on. (:face_with_monocle: Having trouble understanding these properties? No worry, a detailed explanation comes later!)
- Remote storage is stored in DB for the sake of relatively frequent changes on those data.
Connector's local storage: ConnectorMetadata
id
id is an unique string-typed key to identify a connector in Logto.
It's assigned by the developers of each connector and will be uploaded to DB.
target
target is a lowercase string to distinguish the social identities source of the social connector.
Logto users can regard this variable as "Identity provider's name" for better understanding.
For example, your target should be google if you sign in to Logto with your google account. The value of target can be an arbitrary non-empty string, but we encourage you to keep it straightforward since you can not change it. We DO NOT allow the existence of multiple connectors with the same target and platform. On the other hand, you can have social connectors for different platforms sharing the same target. For example, if users want to log in via WeChat on their phone, a native WeChat app is required per WeChat’s TOU; at the same time, a web WeChat app is also needed to enable log in to web applications. These two WeChat apps share the same identity provider and should have the same target.
We have concluded different use cases and suggestions for users since target is a complicated concept.
| Example | Scenario | Result | Recommend? | |
Different IdPs and different targets |
| An app that support both login with GitHub and Google account. | Most common use cases. | ✅ |
Different IdPs and the same target |
| N/A | It's possible for a user to sign in to a Logto account that was created using another user's GitHub account. | ❌ |
The same IdP and different targets |
| The GitHub connector is used for Application A, while the OAuth GitHub connector was created specifically for Application B. | Signing in to Logto using these two different connectors will always create separate Logto accounts - even if the user is using the same GitHub account. | ➖ |
The same IdP and the same target |
| N/A | Using either of these two connectors can result in the exact same outcome. | ➖ |
type
type is the property that record the type of the connector.
We define the connectors into three different types, based on their functionalities:
- Social: Connectors that can access user information from arbitrary third-party social media with end-users authorization.
- SMS: Connectors enable end-users to receive text messages on their phones.
- Email: Connectors that can help send emails to end-users.
platform
platform is used to identify which platform the connector is built for.
platform should be either null or one of the following string-typed values:
- Native: Connectors that ONLY work for native mobile apps.
- Web: Connectors work ONLY on desktop web applications.
- Universal: Connectors can work on both mobile web apps and desktop web apps.
platform of email connectors and SMS connectors should always be null.
ONLY social connectors can have non-NULL platform values.
name
name is an object whose keys are i18n country codes and values are connectors' display name.
description
description is also an object whose keys are i18n country codes and values are brief connector descriptions.
To support i18n display at the client-side, we store the name (as well as description) props as a map, which uses country codes as its' key, name (or description) in local characters as the value.
logo
logo is an URL or relative path of connector's logo.
logoDark
logoDark is a nullable URL or relative path of connector's dark mode logo.
logo is always required, and logoDark is optional.
We display logo in light mode and logoDark in dark mode if it exists. Otherwise will fall back to show logo in dark mode.
isStandard
isStandard is an OPTIONAL boolean attribute to identify whether the social connector is a "standard" connector. You can identify a "standard" connector by its truthy isStandard attribute.
Logto only supports "standard" social connectors. That is to say, all Logto's Sms or Email connectors are NOT "standard".
Logto call connectors built upon open and standard protocols (e.g., OAuth, OIDC, SAML, etc.) as "standard" connectors. Logto's users are expected to construct multiple instances on each standard connector based on this context. For example, suppose that Logto has already provided an OAuth standard connector, users can build "OAuth GitHub connector", "OAuth Google connector" and "OAuth Facebook connector" instances. They are all based on the Logto OAuth standard connector.
If you are familiar with Logto's connector design, at most ONE Sms or Email connector can exist at the same time, which means Logto do not need "standard" Sms or Email connectors at the current stage.
readme
readme is a relative path of the connector's README markdown file whose contexts will show up in "Admin Console" during connectors' set-up.
configTemplate
configTemplate is a relative path of the connector's configuration example.
Connector's remote storage: Connector DB
id
id, which functions as connector DB's primary key, is an randomly generated string-typed key to identify connector in DB.
connectorId
connectorId is a string-typed key and is the ONLY bridge to align Connector DB and ConnectorMetadata. For each matched connector DB data and connector code module pair, connectorId always equals to metadata.id of the code module.
metadata
metadata is a subset of ConnectorMetadata, which contains configurable attributes i.e. logo, logoDark, target and name.
syncProfile
syncProfile is a boolean value to determine the user profile updating scheme, default to be FALSE.
If syncProfile is FALSE, the Logto user's basic information (including name and avatar) will be updated only when the user first signs up to Logto via this connector. Otherwise, every time users sign in to Logto through the connector, the Logto account profile will be updated.
config
config could be an arbitrary non-empty object.
It is where a connector store its configuration. Each connector have different properties in config and it obligated to be valid (connectors have different standard for "valid".) before being saved to DB. ONLY those config passed validity check can be updated to DB, or there would throw an error.
Developers are required to implement a config guard when developing their own connectors, see "Create your connector" for more details.
Want to have a glance at config samples? Go to "Configure connectors" or each connector's settings page.
In current Logto version, only one Sms/Email connector can exist at the same time, all other connectors with same type are automatically deleted.
The rule, unique working SMS or Email connector, is not applicable to Social connectors.
In other words, you can add multiple Social connectors.
createdAt
createdAt is an auto-generated timestamp string to track the time when a connector is created in DB.