Logto Management API でアプリサービスをセットアップする

Logto では、強力な Management API を提供しており、アプリ内で独自の組織フローを作成・カスタマイズできます。その仕組みを理解することは、カスタムセットアップを設計する上で重要です。以下は、Management API を統合して組織体験を実装するための基本的なステップと概要です。

基本をすでに理解している場合は、チュートリアルへ進んでください。セットアップに慣れたら、他の API も活用してビジネスニーズに合わせてフローを調整できます。

マシン間通信接続の確立

Logto は、マシン間通信 (M2M) 認証 (Authentication) を使用して、バックエンドサービスと Logto Management API エンドポイントを安全に接続します。バックエンドサービスは、Management API を利用して 組織の作成、メンバーの追加や削除 など、組織関連のタスクを処理できます。

この流れは次の通りです：

Logto コンソールで マシン間通信 (M2M) アプリ を作成します。

Logto から M2M アクセストークン (Access token) を取得します。詳細はこちら。
バックエンドサービスから Logto Management API を呼び出します。例えば、すべての組織を一覧表示する場合：

curl \
 -X GET https://[tenant_id].logto.app/api/organizations \
 -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
 -H "Content-Type: application/json"

アプリサーバーの保護

エンドユーザーが自身で組織に関する操作を行える場合があるため、エンドユーザーとアプリサーバーの間に認可 (Authorization) レイヤーを追加することが重要です。このレイヤーは、利用する Logto Management API エンドポイントやプロダクトの API 構成に応じて、グローバルまたは組織単位で適用できます。サーバーはすべてのリクエストを仲介し、ユーザーの組織トークン (Organization token) と必要なスコープ (Scope) を検証した上で、サーバーが保持する M2M 資格情報を使って Management API を呼び出すべきです。

ユーザーが組織トークン (Organization token) を提示してアクション（例：組織の作成）をリクエストした場合、サーバーはまずトークン内のスコープ (Scope) を検証します。トークンに org:create など必要なスコープ (Scope) が含まれていれば、リクエストを認可 (Authorization) し、M2M フロー経由で Logto Management API を呼び出して組織を作成します。

必要なスコープ (Scope) がトークンに含まれていない場合は、403 Forbidden を返し、M2M ロジックをスキップします。これにより、適切な権限を持たないユーザーが組織を作成できないようにします。

以下は一般的な認可 (Authorization) パターンです。

組織権限の利用

まず、前のセクションで組織権限とロール (Role) を組織テンプレートに定義していることを確認してください。

次に、Logto 設定に UserScope.Organizations（値：urn:logto:organization）が含まれていることを確認します。React SDK の例：

// src/App.js
import { UserScope } from '@logto/react';

const config = {
  endpoint: 'https://<tenant-id>.logto.app/', // Logto エンドポイント
  appId: '40fmibayagoo00lj26coc', // アプリ ID
  resources: [
    'https://my.company.com/api', // グローバル API リソース識別子
  ],
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations, // 組織トークン (Organization token) をリクエスト
  ],
};

これにより、getOrganizationToken(organizationId) を呼び出す際、クライアント SDK はユーザーに割り当てられた組織権限を含む組織トークン (Organization token) をリクエストします。バックエンドサービスはこのトークンを検証し、これらの権限に基づいて後続のリクエストを認可 (Authorization) できます。

組織レベル（非 API）権限の保護については、完全ガイドを参照してください。

API レベル権限の利用

API リソースと権限がグローバルに登録されているが、ロール (Role) は組織単位で定義されている場合に適用されます（API レベル権限を組織テンプレート内の組織ロール (Role) に割り当て可能）。

実装方法は前述のセクションと同じです。常に組織 ID を指定し、getOrganizationToken(organizationId) を呼び出して組織トークン (Organization token) を取得してください。そうしないと、組織権限が含まれません。

組織レベルの API 権限の保護については、完全ガイドを参照してください。

グローバル RBAC の利用

この場合、Logto Management API を使ってシステムレベルのアクセス制御を実装できます。

マルチテナント環境では、スーパーユーザーやスーパー管理者ロール (Role) を持つパターンが一般的です。例えば、Logto で SaaS プラットフォームを構築する場合、Logto コンソールにログインせずに自社アプリ内で全クライアント組織を直接管理できるスーパーユーザーが必要になることがあります。

このスーパーユーザーは、単一の組織コンテキストを超えたシステム全体の権限が必要な、組織の一括作成や削除などの高度な操作を実行できます。これを実現するには、Logto で API リソースを登録し、Logto Management API を活用しつつ、グローバル RBAC でこれらの権限を管理します。

RBAC のアクセス制御統合と管理の詳細については、完全ガイドを参照してください。

マシン間通信接続の確立​

アプリサーバーの保護​

組織権限の利用​

API レベル権限の利用​

グローバル RBAC の利用​

マシン間通信接続の確立

アプリサーバーの保護

組織権限の利用

API レベル権限の利用

グローバル RBAC の利用