コネクターデータ構造

はじめに

コネクターとは？

コネクター は Logto において重要な役割を果たします。これにより、Logto はエンドユーザーがパスワードレス登録またはサインインを行い、ソーシャルアカウントでのサインイン機能を利用できるようにします。ウェブサイトやアプリケーションの人気が高まる中、パスワードレスおよびソーシャルサインインは、ユーザーが多数のアカウントやパスワードを管理する手間を省くことができます。

既存のコネクターを設定したい場合は、コネクターガイド を参照してください。設定したいコネクターが見つからない場合は、コネクターの開発 のガイドに従ってコネクターを開発することができます。

構成

コネクターデータには多くのプロパティがあります。

データの読み込みと更新をより効率的にするために、頻繁に変更される部分のコネクターデータを DB に保存し、残りをローカルに保存します。

• ローカルストレージ、別名 ConnectorMetadata は、ロゴやコネクタータイプなどの固定プロパティを含むオブジェクトです。 (:face_with_monocle: これらのプロパティを理解するのが難しいですか？心配ありません、詳細な説明が後であります！)
• リモートストレージ は、これらのデータの比較的頻繁な変更のために DB に保存されます。

コネクターのローカルストレージ: ConnectorMetadata

id

id は Logto 内でコネクターを識別するための 一意 の文字列型キーです。

各コネクターの開発者によって割り当てられ、DB にアップロードされます。

target (アイデンティティプロバイダー名)

target は、ソーシャルコネクターのソーシャルアイデンティティのソースを区別するための小文字の文字列です。

Logto ユーザーは、この変数を「アイデンティティプロバイダー名」として理解することができます。

例えば、Google アカウントで Logto にサインインする場合、target は google であるべきです。target の値は任意の非空文字列にすることができますが、一度設定すると変更できないため、簡潔に保つことをお勧めします。同じ target とプラットフォームを持つ複数のコネクターの存在は許可されていません。一方で、異なるプラットフォームのソーシャルコネクターが同じ target を共有することは可能です。例えば、ユーザーが電話で WeChat を介してログインしたい場合、WeChat の TOU に従ってネイティブ WeChat アプリが必要です。同時に、ウェブアプリケーションにログインするためにウェブ WeChat アプリも必要です。これらの 2 つの WeChat アプリは同じアイデンティティプロバイダーを共有し、同じターゲットを持つべきです。

target は複雑な概念であるため、異なるユースケースとユーザーへの提案をまとめました。

	例	シナリオ	結果	推奨
異なる IdP と異なる target	1. GitHub コネクター (target: github) 2. Google コネクター (target: google)	GitHub と Google アカウントの両方でログインをサポートするアプリ。	最も一般的なユースケース。	✅
異なる IdP と同じ target	1. GitHub コネクター (target: github) 2. Google コネクター (target: github)	該当なし	別のユーザーの GitHub アカウントを使用して作成された Logto アカウントにサインインすることが可能です。	❌
同じ IdP と異なる target	1. GitHub コネクター (target: github) 2. OAuth GitHub コネクター (target: github_oauth)	GitHub コネクターはアプリケーション A 用に使用され、OAuth GitHub コネクターはアプリケーション B 用に特別に作成されました。	これらの 2 つの異なるコネクターを使用して Logto にサインインすると、ユーザーが同じ GitHub アカウントを使用している場合でも、常に別々の Logto アカウントが作成されます。	ユーザープールを分割することが唯一のシナリオであり、この場合には両方のコネクターを使用する必要があります。ただし、このユースケースを処理するために 2 つの別々のテナントを作成することが最善の方法とされています。
同じ IdP と同じ target	1. GitHub コネクター (target: github) 2. OAuth GitHub コネクター (target: github)	該当なし	これらの 2 つのコネクターのいずれかを使用すると、まったく同じ結果が得られる可能性があります。	本質的に同じことを行う 2 つのコネクターを作成することは、エンドユーザーにとって混乱を招く可能性があり、あまり意味がありません。特定のユースケースに適した 1 つのコネクターを使用する方が良いです。

type

type はコネクターのタイプを記録するプロパティです。

その機能に基づいて、コネクターを 3 つの異なるタイプに分類します：

• Social：エンドユーザーの認可 (Authorization) により、任意のサードパーティのソーシャルメディアからユーザー情報にアクセスできるコネクター。
• SMS：エンドユーザーが携帯電話でテキストメッセージを受信できるようにするコネクター。
• Email：エンドユーザーにメールを送信するのを助けるコネクター。

platform

platform は、コネクターがどのプラットフォーム用に構築されているかを識別するために使用されます。

platform は null または次の文字列型の値のいずれかである必要があります：

• Native：ネイティブモバイルアプリでのみ動作するコネクター。
• Web：デスクトップウェブアプリケーションでのみ動作するコネクター。
• Universal：モバイルウェブアプリとデスクトップウェブアプリの両方で動作するコネクター。

注記:

email コネクター と SMS コネクター の platform は常に null であるべきです。
非 NULL の platform 値を持つことができるのは social コネクター のみです。

name

name は、キーが i18n 国コードで、値がコネクターの表示名であるオブジェクトです。

description

description も、キーが i18n 国コードで、値がコネクターの簡単な説明であるオブジェクトです。

注記:

クライアント側での i18n 表示をサポートするために、name（および description）プロパティをマップとして保存し、国コードをキーとして使用し、ローカル文字での名前（または説明）を値として使用します。

logo

logo はコネクターのロゴの URL または相対パスです。

logoDark

logoDark はコネクターのダークモードロゴの nullable な URL または相対パスです。

注記:

logo は常に必要であり、logoDark はオプションです。

light モードでは _logo を表示し、dark モードでは _logoDark を表示します。存在しない場合は、dark モードで _logo を表示します。

isStandard

isStandard は、ソーシャルコネクターが「標準」コネクターであるかどうかを識別するためのオプションのブール属性です。isStandard 属性が真であることで「標準」コネクターを識別できます。

注記:

Logto は「標準」ソーシャルコネクターのみをサポートしています。つまり、Logto のすべての Email または SMS コネクターは「標準」ではありません。

Logto は、オープンで標準的なプロトコル（例：OAuth、OIDC、SAML など）に基づいて構築されたコネクターを「標準」コネクターと呼びます。Logto のユーザーは、このコンテキストに基づいて各標準コネクターに複数のインスタンスを構築することが期待されています。例えば、Logto がすでに OAuth 標準コネクターを提供している場合、ユーザーは「OAuth GitHub コネクター」、「OAuth Google コネクター」、「OAuth Facebook コネクター」インスタンスを構築できます。これらはすべて Logto OAuth 標準コネクターに基づいています。

Logto のコネクターデザインに精通している場合、同時に存在できる Email または SMS コネクターは最大で 1 つであるため、Logto は現在の段階で「標準」Email または SMS コネクターを必要としません。

readme

readme は、コネクターの README マークダウンファイルの相対パスであり、そのコンテキストはコネクターのセットアップ中に「管理コンソール」に表示されます。

configTemplate

configTemplate は、コネクターの設定例の相対パスです。

コネクターのリモートストレージ: Connector DB

id

id は、コネクター DB の主キーとして機能し、DB 内でコネクターを識別するためのランダムに生成された文字列型キーです。

connectorId

connectorId は文字列型キーであり、Connector DB と ConnectorMetadata を一致させる唯一の橋渡しです。各一致するコネクター DB データとコネクターコードモジュールのペアに対して、connectorId は常にコードモジュールの metadata.id と等しいです。

metadata

metadata は、構成可能な属性を含む ConnectorMetadata のサブセットであり、すなわち logo、logoDark、target、name です。

syncProfile

syncProfile は、ユーザープロファイルの更新スキームを決定するブール値で、デフォルトは FALSE です。

syncProfile が FALSE の場合、Logto ユーザーの基本情報（名前やアバターを含む）は、このコネクターを介して初めて Logto にサインアップしたときにのみ更新されます。それ以外の場合、ユーザーがコネクターを介して Logto にサインインするたびに、Logto アカウントプロファイルが更新されます。

config

config は任意の非空オブジェクトです。

これはコネクターがその設定を保存する場所です。各コネクターは config に異なるプロパティを持ち、DB に保存される前に有効であることが義務付けられています（コネクターには「有効」のための異なる基準があります）。有効性チェックを通過した config のみが DB に更新されることができ、そうでなければエラーがスローされます。

独自のコネクターを開発する際には、config ガードを実装する必要があります。詳細については、コネクターの開発 を参照してください。

config サンプルを見たいですか？コネクター または各コネクターの設定ページに移動してください。

注記:

現在の Logto バージョンでは、同時に存在できる Email/SMS コネクターは 1 つだけであり、同じタイプの他のすべてのコネクターは自動的に削除されます。

このルール、つまり唯一の動作する Email または SMS コネクターは、Social コネクターには適用されません。
言い換えれば、複数の Social コネクターを追加することができます。

createdAt

createdAt は、DB にコネクターが作成された時刻を追跡するために自動生成されるタイムスタンプ文字列です。