> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 認証連携ガイド：アーキテクチャと本番公開

> Didit Authenticationの本番連携の全体像を解説します。ホスト型画面か自社画面か、トークンの保管、バックエンドでの検証、セッション、ネイティブアプリ、本番公開までを扱います。

このガイドでは、本番環境におけるDidit Authenticationの連携が、最初のリダイレクトから本番稼働チェックリストまでどのように組み合わさるかを説明します。
まだユーザーのサインインを実装していない場合は、[クイックスタート](https://docs.didit.me/ja/authentication/quickstart.md)から始めてください。各SDKのコードについては、プラットフォームごとのクイックスタートを参照してください。

## アーキテクチャ

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

関係する要素は4つあります。

| 要素 | 担当 |
| - | - |
| あなたのアプリ | サインインの開始、PKCE verifierと`state`の保持、トークンの保管、アクセストークンのバックエンドへの送信を行います。これらはすべてSDKが担当します。 |
| サインインオリジン | `https://<slug>.auth.didit.me`（または[カスタムドメイン](https://docs.didit.me/ja/authentication/branding-and-custom-domain.md#カスタムドメイン)）です。ホスト型ページ、トークンエンドポイント、セッション、ディスカバリー、署名鍵を提供します。 |
| バックエンド | 保護されたすべてのリクエストでアクセストークンを検証し、機密性の高い操作の前にセッションを確認し、ユーザーに許可される操作を決定します。 |
| DiditコンソールとWebhook | 設定、ユーザーとそのセッション、サインインイベント、サーバーが購読する`auth.*` Webhookを管理します。 |

DiditのAPIキーもシークレットも、決してアプリに含めてはなりません。公開可能キーは公開される前提のキーであり、コード交換はクライアントシークレットではなくPKCEによって保護されます。

## ホステッドページか独自の画面か

メールアドレス、パスワード、コードを入力する場所を選択します。
設定は `sign_in_ui` で、既定値は `hosted` です。`own` を指定することもできます。設定はいつでも変更できます。

| | ホステッドページ（推奨） | 独自の画面 |
| - | - | - |
| 構築するもの | サインインボタンとコールバックページ。 | すべての画面と中間ステップ。 |
| 認証方法 | すべて利用できます（マジックリンク、企業SSO、パスキーを含みます）。 | パスワード、メールコード、電話番号コード、MFA、保護チャレンジを、SDKのヘッドレスメソッド経由で利用できます。マジックリンクはホステッドページでのみ動作します。 |
| 次のステップ | 自動で処理されます：MFA、MFA登録、保護チャレンジ、サインアップ時の認証。 | 独自の画面で `mfa_required`、`mfa_enrollment_required`、`protection_required`、`verification_required` を処理します。詳しくは[サインイン方法](https://docs.didit.me/ja/authentication/sign-in-methods.md)を参照してください。 |
| ブランド | [ブランディング](https://docs.didit.me/ja/authentication/branding-and-custom-domain.md)で、ロゴ、色、テキストを指定します。 | すべてお客様独自のものです。 |
| セットアップ | リダイレクトURL。 | リダイレクトURLと、ウェブオリジンを **Allowed origins** に設定します。 |

パスキーは、アプリケーションのサインインオリジンに紐づきます。
SDKのパスキーメソッドは、そのオリジンから配信されたページでのみ動作します。そのため、別のドメインにある独自の画面でパスキーを使う場合は、ユーザーをホステッドページに誘導してください。

## SDKの選び方

| アプリ | パッケージ | トークンの保存場所 |
| - | - | - |
| シングルページWebアプリ | [`@didit-protocol/auth`](https://docs.didit.me/ja/authentication/quickstarts/javascript) または [`@didit-protocol/auth-react`](https://docs.didit.me/ja/authentication/quickstarts/react) | ブラウザのWebストレージまたはメモリ。厳格なコンテンツセキュリティポリシーを維持してください。 |
| サーバーサイドレンダリングのWebアプリ | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/ja/authentication/quickstarts/nextjs) | サーバーが設定するHttpOnlyクッキー。ページからトークンが見えることはありません。 |
| iOS | [`DiditAuth`](https://docs.didit.me/ja/authentication/quickstarts/ios) | Keychain。 |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/ja/authentication/quickstarts/android) | Android Keystoreで保護されたストレージ。 |
| React NativeまたはFlutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/ja/authentication/quickstarts/react-native) または [`didit_auth`](https://docs.didit.me/ja/authentication/quickstarts/flutter) | ネイティブモジュールを経由した、プラットフォームの保護されたストレージ。 |
| 任意のバックエンド | [サーバーサイドSDK](https://docs.didit.me/ja/integration/server-sdks/overview.md)、`@didit-protocol/auth/server`の`verifyToken`、または任意のJWTライブラリ | 保存するものはありません。受け取ったトークンを検証するだけです。 |

SDKを使わない場合は、PKCE付きの認可コードフローを自前で実装してください。[JavaScriptクイックスタート](https://docs.didit.me/ja/authentication/quickstarts/javascript.md#sdkを使わない場合)に、仕様全体が示されています。

## バックエンドを保護する

フロントエンドでのセッション確認が制御できるのは、表示する内容だけです。
バックエンドは、すべての判断を検証済みのトークンに基づいて行います。

1. **すべてのリクエストでアクセストークンを検証してください。** 発行者のJWKSに対してES256署名を確認したうえで、`iss`、`aud`、`exp`、`typ: at+jwt` を確認してください。`act` が `null` ではないトークンは、そのルートが[AIエージェント](https://docs.didit.me/ja/authentication/agent-access.md)を受け付ける場合を除き、拒否してください。詳しくは[サーバーでトークンを検証する](https://docs.didit.me/ja/authentication/tokens-and-jwks.md#サーバーでトークンを検証する)をご覧ください。
2. **機密性の高い操作の前に、現在有効なセッションを確認してください。** アクセストークンは、期限が切れるまで有効です。その有効期間は最長5分間です。セッションが失効した場合、アイドル状態になった場合、期限切れになった場合、本人がブロックされた場合、またはセッションがMFAポリシーの要件を満たさなくなった場合、`GET /session/` は直ちに失敗します。詳しくは[セッションを確認する](https://docs.didit.me/ja/authentication/tokens-and-jwks.md#セッションを確認する)をご覧ください。
3. **操作にリスクがある場合は、ステップアップ認証を要求してください。** 支払い、新しい銀行口座の登録、メールアドレスや電話番号の変更の前に、本人が再検証を必要とするかどうかをDiditに問い合わせてください。バックエンドが自ら読み取った、`approved` のステップアップ結果に基づいてのみ処理を進めてください。詳しくは[機密操作の前のステップアップ](https://docs.didit.me/ja/authentication/verified-identity.md#機密性の高いアクションの前のステップアップ認証)をご覧ください。
4. **`vendor_data` は、検証済みのトークンから取得してください。** ブラウザが送信したフィールドから取得してはいけません。本人の認証と取引には、その値を使用してください。

## セッション

| イベント | 起きること |
| - | - |
| サインイン | セッションが開始されます。有効期間は`session_lifetime`で設定され(既定では30日)、`idle_timeout`(既定では1日)の間に操作がないと、それより前に終了します。 |
| 数分ごと | SDKがアクセストークンを更新します。アクセストークンの有効期間は最長5分です。リフレッシュトークンはローテーションされ、各トークンは1回だけ使えます。 |
| 使用済みのリフレッシュトークンが再送された場合 | Diditはこれを盗難とみなし、セッションを終了します。セッションごとに実行するリフレッシュは一度に1件にしてください。 |
| 別のデバイスからのサインイン | `multiple_sessions: false`の場合、その人のほかのセッションは終了します。 |
| パスワードのリセット | `revoke_on_password_change`が有効(既定値)の場合、すべてのセッションが終了します。 |
| サインアウト | `DELETE /session/`でセッションが終了し、アプリは本人を`post_logout_redirect_uri`に誘導します。 |
| チームによる対応 | コンソールでは、1つのセッションを失効させる、本人をすべてのセッションからサインアウトさせる、または本人をブロックできます。詳しくは[コンソールガイド](https://docs.didit.me/ja/authentication/console.md#サインインとセッション)をご覧ください。 |

有効期間は**Authentication > Security and sessions**で変更するか、[アプリケーション設定](https://docs.didit.me/ja/authentication/overview.md#アプリケーション設定)からAPIで変更できます。

![Didit Business ConsoleのActive sessions画面です。サインイン中のセッションを、デバイス、所在地、開始時刻、最終アクティビティ、終了時刻、Revokeボタンとともに一覧表示しています](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessionsの画面です。各セッションにRevokeボタンがあります。

## ネイティブアプリ

Didit はネイティブアプリへのリダイレクトを HTTPS リダイレクトでのみ行い、カスタムURLスキームは受け付けません。

* **iOS:** リダイレクトを関連付けられたドメインにし、`apple-app-site-association` に `webcredentials` を記載してください。
* **Android:** リダイレクトを App Link にし、`assetlinks.json` を用意してください。
* すべてのリダイレクトURLは、Web のコールバックと同様に **Authentication > Security and sessions** で登録してください。

アプリでパスキーを使う場合は、アプリケーションのパスキーを共有するアプリを [認証管理API](https://docs.didit.me/ja/authentication/set-up-by-api.md) の `PUT native-apps/` で登録してください。
Didit は、登録されたアプリを、サインインのオリジンで配信する `apple-app-site-association` と `assetlinks.json` に一覧として記載します。
`MANAGEMENT_BASE` はアプリケーションの管理APIのアドレスです。`authentication` スコープで **write** 権限を持つAPIキーで、この呼び出しを行えます。
この呼び出しは両方のリストを置き換えるため、両方を必ず送信してください。

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| フィールド | ルール |
| - | - |
| `ios_app_ids` | Team ID とバンドル識別子で構成される値を最大10件指定します。例: `ABCDE12345.com.example.app` |
| `android_apps` | 最大10アプリを指定します。各アプリには `package_name` と、1から5個のSHA-256署名証明書フィンガープリントを指定します。 |

アプリ側の設定は、[iOS](https://docs.didit.me/ja/authentication/quickstarts/ios.md) と [Android](https://docs.didit.me/ja/authentication/quickstarts/android.md) のクイックスタートで確認できます。

## 本人確認とトランザクションモニタリングの連携

ユーザーごとに`vendor_data`の値が1つあり、その値はトークンとセッションに含まれます。[本人確認セッションを作成する](https://docs.didit.me/ja/sessions-api/create-session.md)とき、または[取引を送信する](https://docs.didit.me/ja/transaction-monitoring/transactions.md)ときは、この値を`vendor_data`として使用してください。コンソールには、サインイン、本人確認、取引が同じユーザーとして表示されます。

* 登録時や支払いの前に再度、本人確認フローを構築せずに本人確認を行うには、[検証済みの本人情報](https://docs.didit.me/ja/authentication/verified-identity.md)を使用します。
* サインインイベントは、[イベントルール](https://docs.didit.me/ja/transaction-monitoring/event-rules.md)と不正対策の画面に自動的に送られます。同じサインインについて、独自に`auth.login`イベントを送信しないでください。
* サインインが成功しても、本人確認や取引が承認されることはありません。各製品の判定は、それぞれ個別に処理してください。

詳しくは[製品をまたいで同じユーザーを扱う](https://docs.didit.me/ja/authentication/overview.md#製品をまたいで同じユーザーとして扱う)をご覧ください。

## サインインイベントを受信する

[Webhookの送信先](https://docs.didit.me/ja/integration/webhooks.md)を、必要な`auth.*`タイプ（`auth.new_device`や`auth.account_locked`など）に登録してください。
`auth_event.event_id`で重複を排除し、すべてのDiditのWebhookと同様に署名を検証してください。
すべてのタイプとペイロードについては、[イベントとWebhook](https://docs.didit.me/ja/authentication/events-and-webhooks.md)を参照してください。

## 既存ユーザーの移行

ユーザーがすでに別の ID プラットフォームや自社データベースにアカウントを持っている場合は、サインインを切り替える前に[ユーザーをインポート](https://docs.didit.me/ja/authentication/migration.md)してください。
提供元がパスワードハッシュを提供している場合は、それもインポートしてください。ソーシャルアカウントの連携はそのまま維持し、自社のユーザーIDは`external_id`として保持します。これが各ユーザーの`vendor_data`になります。
アプリのサインインをDiditに切り替えるまで、ユーザーにとって変わることはありません。

## 本番運用前のチェックリスト

1. **Products**ページで、Liveアプリケーションの認証が有効になっていること。
2. 本番用の`https://`リダイレクトURLと許可するオリジンが、Liveアプリケーションに登録されていること。Liveアプリケーションは`http://`のアドレスを受け付けません。
3. 各ソーシャルサインインの方法で、お客様自身のアプリのクライアントIDとシークレットを使用していること。Diditのテスト用認証情報は、サンドボックスでのみ動作します。
4. 本番環境の設定に、Liveの公開キー（`pk_live_`）とLiveの発行者が含まれていること。
5. MFAポリシー、セッションの有効期間、アイドルタイムアウト、パスワードの長さ、サインアップポリシーが、希望どおりに設定されていること。[アプリケーション設定](https://docs.didit.me/ja/authentication/overview.md#アプリケーション設定)を参照してください。
6. [ボット対策](https://docs.didit.me/ja/authentication/bot-protection.md)が有効になっており、漏洩パスワードチェックも有効になっていること。
7. バックエンドがすべてのアクセストークンを検証し、重要な操作の前に`GET /session/`を呼び出していること。
8. ブランディング、ページのテキスト、利用規約とプライバシーポリシーのリンクが設定されていること。[カスタムドメイン](https://docs.didit.me/ja/authentication/branding-and-custom-domain.md#カスタムドメイン)を使用する予定がある場合は、ユーザーがパスキーを追加し始める前に有効化してください。
9. 処理する`auth.*`タイプについて、Webhookの送信先が購読していること。
10. Liveアプリケーションで、サインアップ、再訪時のサインイン、キャンセル、パスワードを忘れた場合の再設定、MFA、セッションの有効期限切れ、サインアウト、取り消されたセッションをテスト済みであること。

## トラブルシューティング

| 症状 | 原因と対処 |
| - | - |
| すべてのランタイムルートが `404` を返す | アプリケーションで認証が無効になっているか、アドレスがサンドボックスと本番環境のオリジンを混在させています。**Products** ページで有効にし、公開キーに記載されているオリジンを使用してください。 |
| サインインページが `400` を返し、アドレスの登録を求める、または `POST /authorize/` が `invalid_redirect_uri` を返す | `redirect_uri` が正確に登録されていません。スキーム、ホスト、ポート、パス、クエリは一文字ずつ完全に一致している必要があります。[リダイレクトURL](https://docs.didit.me/ja/authentication/overview.md#リダイレクトurl)を参照してください。 |
| ブラウザからサインインオリジンを呼び出すと `origin_not_allowed` を伴う `403` を返す | Webオリジンが **Allowed origins** に含まれていません。パスと末尾のスラッシュなしで追加してください。 |
| `POST /token/` が `invalid_grant` を返す | コードがすでに使用されているか、60秒より古いか、別のPKCEベリファイアまたは `redirect_uri` で送信されています。リフレッシュの場合は、リフレッシュトークンがすでに使用されており、それによりセッションが終了しています。サインインを最初からやり直してください。 |
| 正しいパスワードでのパスワードサインインが `invalid_credentials` を返す | メールアドレスが未確認であるか、アカウントがロックまたはブロックされています。Didit は意図的に同じ応答を返します。**Users** で該当ユーザーを確認してください。 |
| `GET /session/` が `401` を返す | セッションが取り消された、非アクティブまたは期限切れになった、ユーザーがブロックされた、トークンがリフレッシュで置き換えられた、またはセッションが MFA ポリシーを満たさなくなった、のいずれかです。トークンをリフレッシュするか、ユーザーに再度サインインしてもらってください。 |
| パスキーまたは認証器の追加が `403 reauthentication_required` を返す | これらには、過去5分以内に作成されたセッションが必要です。先にユーザーに再度サインインしてもらってください。 |
| 電話番号認証コードが `503 delivery_unavailable` を返す | コードを配信できませんでした。ユーザーに再試行してもらうか、別の方法を提示してください。 |
| 呼び出しが `429` を返す | レート制限に達しました。`Retry-After` に示された時間の後に再試行してください。[レート制限](https://docs.didit.me/ja/authentication/bot-protection.md#レート制限)を参照してください。 |
| APIキーを使ったセットアップ呼び出しが `409 product_disabled` を返す | アプリケーションで認証が無効になっています。担当者がコンソールで有効にする必要があります。 |
| 呼び出しが `403 plan_required` を返す | カスタム役割や企業SSOセットアップリンクなどの機能には、ScaleまたはEnterpriseプランが必要です。サンドボックスアプリケーションでは、どのプランでも利用できます。 |
| カスタムドメインを有効化した後、トークンが機能しなくなる | 発行者と公開キーが変わりました。新しいキーをアプリにコピーし、バックエンドが確認する発行者を更新してください。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.