コネクター (Connector) のデータ構造
はじめに
コネクター (Connector) とは？
コネクター (Connector) は Logto で重要な役割を果たします。コネクター (Connector) の助けを借りて、Logto はエンドユーザーにパスワードレス登録やサインイン、ソーシャルアカウントでのサインイン機能を提供します。Web サイトやアプリケーションの普及に伴い、パスワードレスやソーシャルサインインは、多数のアカウントやパスワードを管理する手間を省くことができます。
既存のコネクター (Connector) を設定したい場合は、 コネクターガイド をご覧ください。希望するコネクター (Connector) が見つからない場合は、 コネクター開発ガイド に従って独自に開発できます。
構成要素
コネクター (Connector) データには多くのプロパティがあります。
データの読み込みや更新を効率化するため、頻繁に変更されるコネクター (Connector) データの一部は DB に保存し、それ以外はローカルに保存しています。
- ローカルストレージ（ConnectorMetadata とも呼ばれる）は、ロゴやコネクタータイプなどの固定プロパティを含むオブジェクトです。(:face_with_monocle: これらのプロパティが分かりにくい場合もご安心ください。詳細な説明は後ほど登場します！)
- リモートストレージ は、これらのデータが比較的頻繁に変更されるため、DB に保存されます。
コネクター (Connector) のローカルストレージ: ConnectorMetadata
id
id は、Logto 内でコネクター (Connector) を識別するための 一意 な文字列型キーです。
各コネクター (Connector) の開発者によって割り当てられ、DB にアップロードされます。
target（アイデンティティプロバイダー (IdP) 名）
target は、ソーシャルコネクター (Connector) のソーシャルアイデンティティソースを区別するための小文字の文字列です。
Logto ユーザーは、この変数を「アイデンティティプロバイダー (IdP) 名」として理解できます。
例えば、Google アカウントで Logto にサインインする場合、target は google である必要があります。target の値は任意の非空文字列にできますが、一度設定すると変更できないため、分かりやすい名前にすることを推奨します。同じ target とプラットフォームを持つ複数のコネクター (Connector) の存在は許可されていません。一方で、異なるプラットフォームで同じ target を共有するソーシャルコネクター (Connector) を持つことは可能です。例えば、ユーザーがスマートフォンで WeChat を使ってログインしたい場合、WeChat の TOU に従いネイティブ WeChat アプリが必要です。同時に、Web アプリケーションでのログインを有効にするために Web WeChat アプリも必要です。これら 2 つの WeChat アプリは同じアイデンティティプロバイダー (IdP) を共有し、同じ target を持つべきです。
target は複雑な概念であるため、さまざまなユースケースと推奨事項をまとめました。
| 例 | シナリオ | 結果 | 推奨度 | |
|---|---|---|---|---|
| 異なる IdP かつ異なる target | 1. GitHub コネクター (target: github) 2. Google コネクター (target: google) | GitHub と Google アカウントの両方でログインをサポートするアプリ。 | 最も一般的なユースケース。 | ✅ |
| 異なる IdP かつ同じ target | 1. GitHub コネクター (target: github) 2. Google コネクター (target: github) | N/A | 他のユーザーの GitHub アカウントで作成された Logto アカウントにサインインできてしまう可能性があります。 | ❌ |
| 同じ IdP かつ異なる target | 1. GitHub コネクター (target: github) 2. OAuth GitHub コネクター (target: github_oauth) | GitHub コネクターはアプリケーション A 用、OAuth GitHub コネクターはアプリケーション B 専用。 | これら 2 つの異なるコネクター (Connector) で Logto にサインインすると、同じ GitHub アカウントを使っていても常に別々の Logto アカウントが作成されます。 | ユーザープールを分割したい場合のみ両方のコネクター (Connector) を使う必要がありますが、このユースケースには 2 つのテナントを作成するのが一般的なベストプラクティスです。 |
| 同じ IdP かつ同じ target | 1. GitHub コネクター (target: github) 2. OAuth GitHub コネクター (target: github) | N/A | どちらのコネクター (Connector) を使っても全く同じ結果になります。 | 本質的に同じことをする 2 つのコネクター (Connector) を作成するのはエンドユーザーにとって混乱を招き、意味がありません。特定のユースケースに合った 1 つのコネクター (Connector) を使うのが良いでしょう。 |
type
type はコネクター (Connector) の種類を記録するプロパティです。
機能に基づき、コネクター (Connector) を 3 種類に分類しています：
- Social：エンドユーザーの認可により、任意のサードパーティソーシャルメディアからユーザー情報にアクセスできるコネクター (Connector)。
- SMS：エンドユーザーが携帯電話でテキストメッセージを受信できるコネクター (Connector)。
- Email：エンドユーザーにメールを送信できるコネクター (Connector)。
platform
platform は、コネクター (Connector) がどのプラットフォーム向けに作られているかを識別するために使われます。
platform は null または次のいずれかの文字列型値である必要があります：
- Native：ネイティブモバイルアプリ専用で動作するコネクター (Connector)。
- Web：デスクトップ Web アプリケーション専用で動作するコネクター (Connector)。
- Universal：モバイル Web アプリとデスクトップ Web アプリの両方で動作するコネクター (Connector)。
email コネクター (Connector) および SMS コネクター (Connector) の platform は常に null である必要があります。
non-NULL の platform 値を持てるのは social コネクター (Connector) のみです。
name
name は、キーが i18n 国コード、値がコネクター (Connector) の表示名となるオブジェクトです。
description
description も同様に、キーが i18n 国コード、値がコネクター (Connector) の簡単な説明となるオブジェクトです。
クライアント側での i18n 表示をサポートするため、name（および description）プロパティは、国コードをキー、現地語の名前（または説明）を値とするマップとして保存しています。
logo
logo はコネクター (Connector) のロゴの URL または相対パスです。
logoDark
logoDark は、コネクター (Connector) のダークモード用ロゴの null 許容 URL または相対パスです。
logo は必須、logoDark は任意です。
light モードでは logo を、dark モードでは logoDark を表示します（存在しない場合は dark モードでも logo を表示します）。
isStandard
isStandard は、そのソーシャルコネクター (Connector) が「標準」コネクター (Connector) かどうかを識別するためのオプションのブール属性です。isStandard 属性が真であれば「標準」コネクター (Connector) です。
Logto は「標準」ソーシャルコネクター (Connector) のみをサポートしています。つまり、Logto の Email または SMS コネクター (Connector) は「標準」ではありません。
Logto は、オープンかつ標準的なプロトコル（例：OAuth、OIDC、SAML など）に基づいて構築されたコネクター (Connector) を「標準」コネクター (Connector) と呼びます。Logto ユーザーは、このコンテキストに基づき各標準コネクター (Connector) 上に複数のインスタンスを構築できます。例えば、Logto がすでに OAuth 標準コネクター (Connector) を提供している場合、ユーザーは「OAuth GitHub コネクター (Connector)」、「OAuth Google コネクター (Connector)」、「OAuth Facebook コネクター (Connector)」のインスタンスを構築できます。これらはすべて Logto OAuth 標準コネクター (Connector) に基づいています。
Logto のコネクターデザインに詳しい方はご存知の通り、同時に存在できる Email または SMS コネクター (Connector) は最大 1 つです。つまり、現時点では「標準」Email または SMS コネクター (Connector) は必要ありません。
readme
readme は、コネクター (Connector) の README マークダウンファイルの相対パスです。セットアップ時に「管理コンソール」で内容が表示されます。
configTemplate
configTemplate は、コネクター (Connector) の設定例の相対パスです。
コネクター (Connector) のリモートストレージ: Connector DB {#connectors-remote-storage-connector-db}
id
id はコネクター DB の主キーとして機能し、DB 内でコネクター (Connector) を識別するためのランダム生成された文字列型キーです。
connectorId
connectorId は文字列型キーで、Connector DB と ConnectorMetadata を結びつける唯一の橋渡しです。各対応するコネクター DB データとコネクターコードモジュールのペアについて、connectorId は常にコードモジュールの metadata.id と等しくなります。
metadata
metadata は ConnectorMetadata のサブセットで、設定可能な属性、すなわち logo、logoDark、target、name を含みます。
syncProfile
syncProfile は、ユーザープロファイルの更新方式を決定するブール値で、デフォルトは FALSE です。
syncProfile が FALSE の場合、このコネクター (Connector) で初めて Logto にサインアップしたときのみ、Logto ユーザーの基本情報（名前やアバターなど）が更新されます。TRUE の場合は、ユーザーがこのコネクター (Connector) で Logto にサインインするたびに Logto アカウントプロファイルが更新されます。
config
config は任意の非空オブジェクトです。
コネクター (Connector) の設定情報を保存する場所です。各コネクター (Connector) は config 内に異なるプロパティを持ち、DB に保存する前に有効（コネクター (Connector) ごとに「有効」の基準は異なります）である必要があります。有効性チェックを通過した config のみが DB に保存され、そうでない場合はエラーが発生します。
独自のコネクター (Connector) を開発する際は、config ガードの実装が必要です。詳細は コネクター開発ガイド を参照してください。
config のサンプルを見たい場合は、 コネクター (Connector) または各コネクター (Connector) の設定ページをご覧ください。
現在の Logto バージョンでは、同時に存在できる Email/SMS コネクター (Connector) は 1 つのみで、同じタイプの他のコネクター (Connector) は自動的に削除されます。
このルール（唯一動作する Email または SMS コネクター (Connector)）は Social コネクター (Connector) には適用されません。
つまり、複数の Social コネクター (Connector) を追加できます。
createdAt
createdAt は、コネクター (Connector) が DB に作成された時刻を記録する自動生成のタイムスタンプ文字列です。