Management API によるアカウント設定
インテグレーション
Logto は、ユーザーアカウントを管理するためのさまざまな Management API を提供しています。これらの API を利用して、エンドユーザー向けのセルフサービス型アカウント設定ページを構築できます。
アーキテクチャ
- ユーザー：アカウント設定へアクセス・管理する認証済みエンドユーザー。
- クライアントアプリケーション：ユーザーにアカウント設定ページを提供するクライアントアプリケーション。
- サーバーサイドアプリケーション：クライアントにアカウント設定 API を提供するサーバーサイドアプリケーション。Logto Management API と連携します。
- Logto：認証 (Authentication) および認可 (Authorization) サービスとしての Logto。ユーザーアカウント管理用の Management API を提供します。
シーケンス図
- ユーザーがクライアントアプリケーションへアクセスします。
- クライアントアプリケーションが認証リクエスト (Authentication request) を Logto へ送り、ユーザーを Logto のサインインページへリダイレクトします。
- ユーザーが Logto へサインインします。
- 認証 (Authentication) 済みユーザーが認可コードとともにクライアントアプリケーションへリダイレクトされます。
- クライアントアプリケーションがセルフホスト型アカウント設定 API へのアクセス用に Logto からアクセス トークン (Access token) をリクエストします。
- Logto がクライアントアプリケーションへアクセス トークン (Access token) を発行します。
- クライアントアプリケーションがユーザーのアクセス トークン (Access token) を付与してサーバーサイドアプリケーションへアカウント設定リクエストを送信します。
- サーバーサイドアプリケーションがユーザーのアクセス トークン (Access token) からリクエスターのアイデンティティと権限を検証し、Management API 用のアクセス トークン (Access token) を Logto へリクエストします。
- Logto がサーバーサイドアプリケーションへ Management API 用のアクセス トークン (Access token) を発行します。
- サーバーサイドアプリケーションが Management API 用のアクセス トークン (Access token) を使って Logto からユーザーデータを取得します。
- Logto がサーバーのアイデンティティと Management API 権限を検証し、ユーザーデータを返します。
- サーバーサイドアプリケーションがリクエスターの権限に基づきユーザーデータを処理し、クライアントアプリケーションへユーザーアカウント詳細を返します。
Management API をサーバーサイドアプリケーションへ統合する
サーバーサイドアプリケーションへの Management API 統合方法については、Management API セクションを参照してください。
ユーザー管理 API
ユーザーデータスキーマ
Logto のユーザースキーマについて詳しくは、ユーザーデータとカスタムデータ セクションを参照してください。
ユーザープロファイルおよび識別子管理 API
ユーザープロファイルと識別子はユーザー管理に不可欠です。以下の API を利用してユーザープロファイルや識別子を管理できます。
| method | path | description |
|---|---|---|
| GET | /api/users/{userId} | ユーザー ID でユーザー詳細を取得します。 |
| PATCH | /api/users/{userId} | ユーザー詳細を更新します。 |
| PATCH | /api/users/{userId}/profile | ユーザー ID でユーザープロファイル項目を更新します。 |
| GET | /api/users/{userId}/custom-data | ユーザー ID でカスタムデータを取得します。 |
| PATCH | /api/users/{userId}/custom-data | ユーザー ID でカスタムデータを更新します。 |
| PATCH | /api/users/{userId}/is-suspended | ユーザー ID でユーザーの停止状態を更新します。 |
メールアドレスと電話番号の認証 (Verification)
Logto システムでは、メールアドレスと電話番号の両方がユーザー識別子として利用できるため、その認証 (Verification) は重要です。これをサポートするため、提供されたメールアドレスや電話番号を認証 (Verification) するための認証コード API を用意しています。
注記:
新しいメールアドレスや電話番号でユーザープロファイルを更新する前に、必ずメールアドレスまたは電話番号を認証 (Verification) してください。
| method | path | description |
|---|---|---|
| POST | /api/verifications/verification-code | メールアドレスまたは電話番号の認証コードを送信します。 |
| POST | /api/verifications/verification-code/verify | 認証コードでメールアドレスまたは電話番号を認証 (Verification) します。 |
ユーザーパスワード管理
| method | path | description |
|---|---|---|
| POST | /api/users/{userId}/password/verify | ユーザー ID で現在のパスワードを認証 (Verification) します。 |
| PATCH | /api/users/{userId}/password | ユーザー ID でパスワードを更新します。 |
| GET | /api/users/{userId}/has-password | ユーザー ID でパスワードの有無を確認します。 |
注記:
ユーザーのパスワードを更新する前に、必ず現在のパスワードを認証 (Verification) してください。
ユーザーソーシャルアイデンティティ管理
| method | path | description |
|---|---|---|
| GET | /api/users/{userId} | ユーザー ID でユーザー詳細を取得します。ソーシャルアイデンティティは identities フィールドに含まれます。 |
| POST | /api/users/{userId}/identities | 認証 (Authentication) 済みソーシャルアイデンティティをユーザー ID でリンクします。 |
| DELETE | /api/users/{userId}/identities | ユーザー ID でソーシャルアイデンティティのリンクを解除します。 |
| PUT | /api/users/{userId}/identities | ユーザー ID でリンクされたソーシャルアイデンティティを直接更新します。 |
| POST | /api/connectors/{connectorId}/authorization-uri | ソーシャルアイデンティティプロバイダーの認可 (Authorization) URI を取得します。この URI を使って新しいソーシャルアイデンティティ連携を開始します。 |
- ユーザーがクライアントアプリケーションへアクセスし、ソーシャルアイデンティティ連携をリクエストします。
- クライアントアプリケーションがサーバーへソーシャルアイデンティティ連携リクエストを送信します。
- サーバーが Logto へソーシャルアイデンティティプロバイダーの認可 (Authorization) URI を取得するリクエストを送信します。この際、独自の
stateパラメーターとredirect_uriをリクエストに含める必要があります。redirect_uriはソーシャルアイデンティティプロバイダーに事前登録してください。 - Logto がサーバーへ認可 (Authorization) URI を返却します。
- サーバーがクライアントアプリケーションへ認可 (Authorization) URI を返却します。
- クライアントアプリケーションがユーザーを IdP 認可 (Authorization) URI へリダイレクトします。
- ユーザーが IdP へサインインします。
- IdP が認可コード付きでユーザーを
redirect_uriへリダイレクトします。 - クライアントアプリケーションが
stateを検証し、IdP 認可レスポンスをサーバーへ転送します。 - サーバーが Logto へソーシャルアイデンティティをユーザーへリンクするリクエストを送信します。
- Logto が認可コードを使って IdP からユーザー情報を取得します。
- IdP がユーザー情報を Logto へ返却し、Logto がソーシャルアイデンティティをユーザーへリンクします。
注記:
新しいソーシャルアイデンティティをユーザーへリンクする際には、いくつかの制限事項があります：
- Management API にはセッションコンテキストがないため、ソーシャル認証状態を安全に維持するためにアクティブなセッションが必要なソーシャルコネクターは Management API 経由でリンクできません。サポートされないコネクターには apple、標準 OIDC、標準 OAuth 2.0 コネクターが含まれます。
- 同じ理由で、Logto は認可レスポンスの
stateパラメーターを検証できません。クライアントアプリでstateパラメーターを保存し、認可レスポンス受信時に必ず検証してください。 redirect_uriを事前にソーシャルアイデンティティプロバイダーへ登録する必要があります。登録しない場合、ソーシャル IdP はユーザーをクライアントアプリへリダイレクトしません。ソーシャル IdP には、ユーザーサインイン用とプロフィール連携ページ用の複数のコールバックredirect_uriを登録できる必要があります。
ユーザーエンタープライズアイデンティティ管理
| method | path | description |
|---|---|---|
| GET | /api/users/{userId}?includeSsoIdentities=true | ユーザー ID でユーザー詳細を取得します。エンタープライズアイデンティティは ssoIdentities フィールドに含まれます。API で includeSsoIdentities=true クエリパラメータを追加してください。 |
現在、Management API ではユーザーへのエンタープライズアイデンティティのリンク・解除はサポートしていません。ユーザーにリンクされたエンタープライズアイデンティティの表示のみ可能です。
パーソナルアクセストークン
| method | path | description |
|---|---|---|
| GET | /api/users/{userId}/personal-access-tokens | ユーザーのすべてのパーソナルアクセストークンを取得します。 |
| POST | /api/users/{userId}/personal-access-tokens | ユーザーに新しいパーソナルアクセストークンを追加します。 |
| DELETE | /api/users/{userId}/personal-access-tokens/{name} | 名前でユーザーのトークンを削除します。 |
| PATCH | /api/users/{userId\s}/personal-access-tokens/{name} | 名前でユーザーのトークンを更新します。 |
パーソナルアクセストークンは、ユーザーが認証情報やインタラクティブなサインインを使わずに アクセス トークン (Access token) を安全に付与する方法を提供します。詳しくは パーソナルアクセストークンの利用 をご覧ください。
ユーザー多要素認証 (MFA) 設定管理
| method | path | description |
|---|---|---|
| GET | /api/users/{userId}/mfa-verifications | ユーザー ID でユーザーの多要素認証 (MFA) 設定を取得します。 |
| POST | /api/users/{userId}/mfa-verifications | ユーザー ID で多要素認証 (MFA) 設定を追加します。 |
| DELETE | /api/users/{userId}/mfa-verifications/{verificationId} | ID でユーザーの多要素認証 (MFA) 設定を削除します。 |
ユーザーアカウント削除
| method | path | description |
|---|---|---|
| DELETE | /api/users/{userId} | ユーザー ID でユーザーを削除します。 |