Connector data structure

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.

Follow our connector guides if you want to set up an existing connector. If you cannot find the connector you want to set up, you may develop those connectors by following the guides in developer 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	1. GitHub Connector (target: github) 2. Google Connector (target: google)	An app that supports both login with GitHub and Google account.	Most common use cases.	✅
Different IdPs and the same target	1. GitHub Connector (target: github) 2. Google Connector (target: github)	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	1. GitHub Connector (target: github) 2. OAuth GitHub Connector (target: github_oauth)	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.	Splitting your user pool is the only scenario where you would need to use both connectors. However, it's generally considered best practice to create two separate tenants to handle this use case.
The same IdP and the same target	1. GitHub Connector (target: github) 2. OAuth GitHub Connector (target: github)	N/A	Using either of these two connectors can result in the exact same outcome.	Creating two connectors that essentially do the same thing can be confusing for end-users and doesn't make much sense. It's better to use one connector that fits your specific use case.

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.

note

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.

note

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.

note

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.

note

Logto only supports "standard" social connectors. That is to say, all Logto's Email or SMS 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 Email or SMS connector can exist at the same time, which means Logto do not need "standard" Email or SMS 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 develop your connector for more details.

Want to have a glance at config samples? Go to connectors or each connector's settings page.

note

In current Logto version, only one Email/SMS connector can exist at the same time, all other connectors with same type are automatically deleted.

The rule, unique working Email or SMS 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.