組織メンバーの招待

マルチ組織アプリケーションでは、よくある要件として組織にメンバーを招待することがあります。このガイドでは、アプリケーションでこの機能を実装するための手順と技術的な詳細を説明します。

フロー概要

全体のプロセスは、以下の図で示されています：

組織ロールの作成

組織にメンバーを招待する前に、組織ロールを作成する必要があります。組織ロールと権限については組織テンプレートをご覧ください。

このガイドでは、典型的な組織ロールとして admin と member を作成します。

admin ロールは組織内のすべてのリソースへのフルアクセス権限を持ち、member ロールは限定的なアクセス権限を持ちます。例えば、各ロールには次のような権限セットを割り当てることができます：

admin ロール:
- read:data - 組織のすべてのデータリソースの読み取り権限
- write:data - 組織のすべてのデータリソースの書き込み権限
- delete:data - 組織のすべてのデータリソースの削除権限
- invite:member - 組織へのメンバー招待権限
- manage:member - 組織内メンバーの管理権限
- delete:member - 組織からメンバーを削除する権限
member ロール:
- read:data - 組織のすべてのデータリソースの読み取り権限
- write:data - 組織のすべてのデータリソースの書き込み権限
- invite:member - 組織へのメンバー招待権限

これらは Logto Console で簡単に設定できます。また、Logto Management API を使ってプログラム的に組織ロールを作成することも可能です。

メールコネクターの設定

招待はメールで送信されるため、メールコネクターが正しく設定されていることを確認してください。招待メールを送信するには、メールテンプレートの使用タイプとして OrganizationInvitation を設定する必要があります。メール内容には組織（例：組織名、ロゴ）や招待者（例：招待者のメールアドレス、名前）の変数を含めたり、多言語テンプレートをカスタマイズしたりできます。

OrganizationInvitation 用のサンプルメールテンプレートは以下の通りです：

{
  "subject": "Welcome to my organization",
  "content": "<p>Join {{organization.name}} by this <a href=\"{{link}}\" target=\"_blank\">link</a>.</p>",
  "usageType": "OrganizationInvitation",
  "type": "text/html"
}

メール本文の {{link}} プレースホルダーは、メール送信時に実際の招待リンクに置き換えられます。このガイドでは、例えば https://your-app.com/invitation/accept/{your-invitation-id} となります。

注記:

Logto Cloud の組み込み「Logto email service」は現時点で OrganizationInvitation 使用タイプをサポートしていません。代わりに、ご自身のメールコネクター（例：Sendgrid）を設定し、OrganizationInvitation テンプレートを用意してください。

Logto Management API で招待を処理する

注記:

Logto Management API のセットアップがまだの場合は、Management API との連携をご覧ください。

組織機能には招待関連の Management API が用意されています。これらの API を使って次のことができます：

POST /api/organization-invitations で組織招待を作成し、組織ロールを割り当てる
POST /api/organization-invitations/{id}/message で招待メールを送信する ※この API のペイロードには link プロパティがあり、招待 ID をもとに招待リンクを作成できます。例：
```
{
  "link": "https://your-app.com/invitation/accept/{your-invitation-id}"
}
```
招待者が招待リンクからアプリケーションにアクセスした際のランディングページを実装する必要があります。
GET /api/organization-invitations および GET /api/organization-invitations/{id} で全招待または特定の招待情報を取得ランディングページでこれらの API を使い、ユーザーが受け取った招待一覧や詳細を表示できます。
PUT /api/organization-invitations/{id}/status で招待の承諾または拒否を処理この API でユーザーの招待への応答を処理します。

組織ロールベースのアクセス制御 (RBAC) でユーザー権限を管理

上記の設定により、メールで招待を送信し、招待されたユーザーは割り当てられたロールで組織に参加できます。

異なる組織ロールを持つユーザーは、組織トークン内のスコープ（権限）が異なります。そのため、クライアントアプリやバックエンドサービスはこれらのスコープを確認し、表示する機能や許可される操作を判断してください。

組織トークンのスコープ更新を処理する

注記:

このセクションは、組織テンプレートや認可 (Authorization) シナリオの高度な内容を含みます。これらの概念に不慣れな場合は、まず認可 (Authorization) および組織テンプレートをご覧ください。

組織トークンのスコープ更新管理には以下が含まれます：

既存スコープの取り消し

例えば、管理者を一般メンバーに降格する場合、ユーザーからスコープを削除する必要があります。この場合、キャッシュされた組織トークンをクリアし、リフレッシュトークンで新しいトークンを取得するだけで十分です。縮小されたスコープは新しい組織トークンに即時反映されます。

新しいスコープの付与

これはさらに 2 つのシナリオに分けられます：

認証システムですでに定義済みの新しいスコープを付与

スコープの取り消しと同様に、新たに付与するスコープがすでに認証サーバーに登録されている場合は、新しい組織トークンを発行するだけで新しいスコープが即時反映されます。

認証システムに新たに追加されたスコープを付与

この場合、ユーザーの組織トークンを更新するために再ログインまたは再同意プロセスをトリガーする必要があります（例：Logto SDK の signIn メソッドを呼び出す）。

リアルタイム権限チェックと組織トークンの更新

Logto は Management API で組織内のユーザー権限をリアルタイムで取得できます。

GET /api/organizations/{id}/users/{userId}/scopes (API リファレンス)

ユーザーの組織トークン内のスコープとリアルタイム権限を比較し、昇格または降格があったかを判断できます。

降格された場合は、キャッシュされた組織トークンをクリアするだけで、SDK が自動的に新しいスコープでトークンを発行します。
```
const { clearAccessToken } = useLogto();

...
// 取得したリアルタイムスコープが組織トークンのスコープより少ない場合
await clearAccessToken();
```
この場合、再ログインや再同意プロセスは不要です。Logto SDK が自動的に新しい組織トークンを発行します。
新しいスコープが認証システムに追加された場合は、再ログインまたは再同意プロセスをトリガーして組織トークンを更新します。React SDK の例：
```
const { clearAllTokens, signIn } = useLogto();

...
// 取得したリアルタイムスコープが組織トークンのスコープより多い場合
await clearAllTokens();
signIn({
  redirectUri: '<your-sign-in-redirect-uri>',
  prompt: 'consent',
});
```
上記コードは同意画面へのページ遷移をトリガーし、同意後にアプリへ自動リダイレクトされ、ユーザーの組織トークンに更新されたスコープが反映されます。

マルチテナントアプリでのユーザーコラボレーション実装方法

フロー概要​

組織ロールの作成​

メールコネクターの設定​

Logto Management API で招待を処理する​

組織ロールベースのアクセス制御 (RBAC) でユーザー権限を管理​

組織トークンのスコープ更新を処理する​

既存スコープの取り消し​

新しいスコープの付与​

認証システムですでに定義済みの新しいスコープを付与​

認証システムに新たに追加されたスコープを付与​

リアルタイム権限チェックと組織トークンの更新​

関連リソース​