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

> Client-Initiated Backchannel Authentication フローでメール通知を使ってユーザーを認証する方法を学びます。

# CIBA を使用したメール通知

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Client-Initiated Backchannel Authentication (CIBA) 機能を使用するには、Enterprise プランまたは該当するアドオンが必要です。詳細は [Auth0 Pricing](https://auth0.com/pricing/) を参照してください。
</Callout>

CIBA とメール通知を併用すると、ユーザーは、ブラウザーでリクエストを認証または承認するためにリダイレクトされるリンクが記載されたメールを受信します。

メール通知付きの CIBA を使用する場合、ユーザーはコンシューマーデバイスでログインしますが、認証の完了は、検証済みメールアドレス宛に送信されたリンクをクリックすることで行います。ユーザーが検証リンクをクリックするとブラウザーにリダイレクトされ、Auth0 が認証プロセスを追跡しユーザーの本人確認を行うために使用するセッションが作成されます。このセッションは、この例ではブラウザーである認証デバイスと、Smart TV などのコンシューマーデバイスとの間のギャップを埋めるために必要です。

次の図は、メール通知を用いた CIBA のエンドツーエンドフローを説明します。

<Frame>
  <img src="https://mintcdn.com/generaltranslationinc/md6b8ua1hdYa2pM7/docs/images/ciba/email_notifications_with_ciba_diagram.png?fit=max&auto=format&n=md6b8ua1hdYa2pM7&q=85&s=a2fa365a1763abab859191a08326849c" alt="" width="1390" height="692" data-path="docs/images/ciba/email_notifications_with_ciba_diagram.png" />
</Frame>

次のセクションでは、メール通知を使用した CIBA におけるユーザー認証の仕組みをステップごとに詳しく説明します。

* [前提条件](#prerequisites)
* [ステップ 1: クライアントアプリケーションが CIBA リクエストを開始する](#step-1%3A-client-application-initiates-a-ciba-request)
* [ステップ 2: Auth0 テナントが CIBA リクエストを受領する](#step-2%3A-auth0-tenant-acknowledges-the-ciba-request)
* [ステップ 3: クライアントアプリケーションがレスポンスをポーリングする](#step-3%3A-client-application-polls-for-a-response)
* [ステップ 4: Auth0 がユーザーのメールアドレスにリンクを送信する](#step-4%3A-auth0-sends-a-link-to-the-user’s-email-address)
* [ステップ 5: ユーザーがブラウザーで認証する](#step-5%3A-user-authenticates-in-the-browser)
* [ステップ 6: ブラウザーがユーザーに同意内容を提示する](#step-6%3A-browser-sends-the-user-response-back-to-auth0)
* [ステップ 7: フロー完了後に Auth0 がユーザーの応答を受信する](#step-7%3A-auth0-receives-user-response-after-the-flow-completes)
* [ステップ 8: Auth0 がクライアントアプリケーションにアクセストークンを返す](#step-8%3A-auth0-returns-access-token-to-client-application)

<div id="prerequisites">
  ## 前提条件
</div>

Auth0 を使用して CIBA メールリクエストを開始するには、次の条件を満たす必要があります。

* テナントとアプリケーションについて、[Client-Initiated Backchannel Authentication を設定](/docs/ja-JP/get-started/applications/configure-client-initiated-backchannel-authentication)し、[メール通知](/docs/ja-JP/get-started/applications/configure-client-initiated-backchannel-authentication/#configure-email-notifications)も構成します。
* `requested_expiry` パラメータを 301〜259200 秒（72 時間）の値に設定します。詳細については、[通知チャネルの構成](/docs/ja-JP/get-started/applications/configure-client-initiated-backchannel-authentication#configure-notification-channel)を参照してください。
* CIBA と Rich Authorization Requests (RAR) を使用した[ユーザー認可](/docs/ja-JP/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authorization-with-ciba)でメール通知を利用する場合は、[カスタマイズした同意プロンプトを設定](/docs/ja-JP/get-started/apis/configure-rich-authorization-requests#set-customized-consent-prompt)します。

<div id="step-1-client-application-initiates-a-ciba-request">
  ## ステップ 1: クライアント アプリケーションが CIBA リクエストを開始する
</div>

[User Search API](/docs/ja-JP/manage-users/user-search) を使用して、CIBA リクエストを開始したい認可ユーザーを検索し、そのユーザー ID を取得します。

認可ユーザーのユーザー ID を取得したら、Authentication API または Auth0 の [SDK](/docs/ja-JP/libraries) を使用して、`/bc-authorize` エンドポイントに CIBA リクエストを送信します。

<Tabs>
  <Tab title="cURL">
    ```bash lines theme={null}
    curl --location 'https://{yourDomain}.auth0.com/bc-authorize' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id=<CLIENT_ID>' \
      --data-urlencode 'client_secret=<CLIENT_SECRET>' \
      --data-urlencode 'login_hint={ "format": "iss_sub", "iss": "https://{yourDomain}.auth0.com/", "sub": "<USER_ID>" }' \
      --data-urlencode 'scope=<SCOPES>' \
      --data-urlencode 'binding_message=<BINDING_MESSAGE>'
    ```
  </Tab>

  <Tab title="C#">
    ```csharp lines theme={null}
    var response = await authenticationApiClient.ClientInitiatedBackchannelAuthorization(
                new ClientInitiatedBackchannelAuthorizationRequest()
                {
                    ClientId = "<CLIENT_ID>",
                    Scope = "<SCOPES>",
                    ClientSecret = "<CLIENT_SECRET>",
                    BindingMessage = "<BINDING_MESSAGE>",
                    LoginHint = new LoginHint()
                    {
                        Format = "iss_sub",
                        Issuer = "https://{yourDomain}.auth0.com/",
                        Subject = "<USER_ID>"
                    }
                }
            );
    ```
  </Tab>

  <Tab title="Go">
    ```go lines theme={null}
    resp, err := authAPI.CIBA.Initiate(context.Background(), ciba.Request{
        ClientID:     mgmtClientID,
        ClientSecret: mgmtClientSecret,
        Scope:        "openid",
        LoginHint: map[string]string{
          "format": "iss_sub",
          "iss":    "https://{yourDomain}.auth0.com/",
          "sub":    "<USER_ID>",
        },
        BindingMessage: "<BINDING_MESSAGE>",
      })
    ```
  </Tab>

  <Tab title="Java">
    ```java lines theme={null}
    // AuthClient インスタンスの作成
    AuthAPI auth = AuthAPI.newBuilder(domain, clientId, clientSecret).build();

    // 認可を実行
    Map<String, Object> loginHint = new HashMap<>();
            loginHint.put("format", "iss_sub");
            loginHint.put("iss", "https://{yourDomain}.auth0.com/");
            loginHint.put("sub", "<USER_ID>");

    Request<BackChannelAuthorizeResponse> request = auth.authorizeBackChannel("openid", "<BINDING_MESSAGE>", loginHint);

    BackChannelAuthorizeResponse resp = request.execute().getBody();
    ```
  </Tab>
</Tabs>

<table class="table">
  <thead>
    <tr>
      <th><strong>パラメーター</strong></th>
      <th><strong>説明</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>tenant</code></td>
      <td>テナント名。カスタムドメイン名の場合もあります。<code>iss\_sub</code> フォーマットが使用されている場合、テナント名は <code>iss</code> クレーム内で渡されます。</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>クライアントアプリケーションの識別子。</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>CIBA でユーザー認証を行うために使用されるクライアント認証方法。例として、クライアントシークレット、Private Key JWT、mTLS 認証などがあります。Private Key JWT または mTLS を使用している場合は、クライアントシークレットを含める必要はありません。</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td><code>openid</code> を必ず含める必要があります。<br /><br />スコープには任意で <code>offline\_access</code> を含めてリフレッシュトークンを要求できます。ただし、CIBA フローを用いたトランザクションの一度きりの認可では、リフレッシュトークンは不要であり、このコンテキストでは意味を持ちません。<br /></td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td><code>login\_hint</code> 構造内で渡される、認可を行うユーザーのユーザー ID。<code>iss\_sub</code> フォーマットが使用されている場合、ユーザー ID は <code>sub</code> クレーム内で渡されます。<br /><br />ユーザー ID は外部プロバイダーによって異なるフォーマットになることがあります。<br /></td>
    </tr>

    <tr>
      <td><code>requested\_expiry</code></td>
      <td>CIBA セッションが有効となる最大期間（秒）。CIBA フローの requested expiry は 1 ～ 259200 秒（72 時間）の範囲で指定でき、デフォルトは 300 秒です。CIBA フローに対してカスタムの有効期限を設定するには、<code>requested\_expiry</code> パラメーターを含めます。<br /><br /><code>requested\_expiry</code> パラメーターは、CIBA が使用する通知チャネルを決定するのに役立ちます。<ul><li><code>requested\_expiry</code> を 300 以下（秒）に設定した場合、有効になっていれば CIBA はモバイルプッシュ通知チャネルを使用します。テナントに対して MFA を構成していない場合、CIBA リクエストは失敗します。</li><li><code>requested\_expiry</code> を 301 ～ 259200 秒（72 時間）の範囲に設定した場合、有効になっていれば CIBA はメール通知チャネルを使用します。</li></ul></td>
    </tr>

    <tr>
      <td><code>binding\_message</code></td>
      <td>認証デバイスと利用デバイス間で CIBA フローを関連付けるために使用される、人が読めるメッセージ。binding message は必須で、最大 64 文字まで指定できます。英数字と <code>+-\_.,:#</code> の各文字のみを使用してください。</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  認可を行うユーザーごとにレート制限があり、そのユーザーには 1 分あたり 5 件を超えるリクエストは送信されません。
</Callout>

<div id="step-2-auth0-tenant-acknowledges-the-ciba-request">
  ## ステップ 2: Auth0 テナントが CIBA リクエストを受け付ける
</div>

Auth0 テナントが `POST` リクエストを正常に受信すると、そのリクエストを参照する `auth-req-id` を含むレスポンスが返されます。

```json lines theme={null}
{
    "auth_req_id": "eyJh...",
    "expires_in": 300,
    "interval": 5
}
```

`auth_req_id` の値は、CIBA フローの完了を確認するためポーリングを行う `/token` エンドポイントに渡されます。

<div id="step-3-client-application-polls-for-a-response">
  ## ステップ 3: クライアントアプリケーションがレスポンスをポーリングする
</div>

Authentication API または [SDK](/docs/ja-JP/libraries) を使用して、grant\_type に `urn:openid:params:grant-type:ciba` を指定し、`/bc-authorize` エンドポイントから受け取った `auth_req_id` を使用して `/token` エンドポイントを呼び出します:

<Tabs>
  <Tab title="cURL">
    ```bash lines theme={null}
    curl --location 'https://{yourDomain}.auth0.com/oauth/token' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id=<CLIEND_ID>' \
      --data-urlencode 'client_secret=<CLIENT_SECRET>' \
      --data-urlencode 'auth_req_id=<AUTH_REQ_ID>' \
      --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'
    ```
  </Tab>

  <Tab title="C#">
    ```csharp lines theme={null}
    var token = await authenticationApiClient.GetTokenAsync(
                new ClientInitiatedBackchannelAuthorizationTokenRequest()
                {
                    AuthRequestId = response.AuthRequestId,
                    ClientId = "<CLIENT_ID>",
                    ClientSecret = "<CLIENT_SECRET>"
                }
            );
    ```
  </Tab>

  <Tab title="Go">
    ```go lines theme={null}
    token, err := authAPI.OAuth.LoginWithGrant(context.Background(),
          "urn:openid:params:grant-type:ciba",
          url.Values{
            "auth_req_id":   []string{resp.AuthReqID},
            "client_id":     []string{clientID},
            "client_secret": []string{clientSecret},
          },
          oauth.IDTokenValidationOptions{})
    ```
  </Tab>

  <Tab title="Java">
    ```java lines theme={null}
    Request<BackChannelTokenResponse> tokenRequest = auth.getBackChannelLoginStatus(authReqId, "grant-type");

    BackChannelTokenResponse tokenResponse = tokenRequest.execute().getBody();
    ```
  </Tab>
</Tabs>

認可を行うユーザーがこのトランザクションを承認するまでの間は、次のようなレスポンスが返されます:

```json lines theme={null}
{
    "error": "authorization_pending",
    "error_description": "エンドユーザーの認可が保留中です"
}
```

ポーリング間隔はおおよそ 5 秒です。ポーリングを頻繁に行いすぎると、次のようなレスポンスが返されます。description の内容はバックオフ間隔に応じて変化します。

```json lines theme={null}
{
"error": "slow_down",
"error_description": "許可された頻度を超えてポーリングしています。10秒後に再試行してください。"
"interval": 10
}
```

Error を解消するには、次のポーリング間隔（秒）になるまで待ってから `/token` エンドポイントをポーリングしてください。

<div id="step-4-auth0-sends-a-link-to-the-users-email-address">
  ## ステップ 4: Auth0 がユーザーのメールアドレスにリンクを送信する
</div>

Auth0 認可サーバーは、認可対象ユーザーのユーザー ID を含む `login_hint` を使用して、認証デバイス上でユーザー認証を開始します。

* Auth0 認可サーバーは、ユーザーの確認済みメールアドレスにメールを送信します。
* メールには、ユーザーがクリックして認証を完了する必要がある検証リンクが含まれます。`binding_message` はリクエストコードとして表示されます。
* リンクは `/bc-verify` エンドポイントへのリクエストを通じてユーザーのブラウザーにリダイレクトし、そこで `consent` クエリパラメーターが同意待ちの CIBA リクエストを参照します。

<Frame>
  <img src="https://mintcdn.com/generaltranslationinc/md6b8ua1hdYa2pM7/docs/images/ciba/ciba_with_email_verification_link.png?fit=max&auto=format&n=md6b8ua1hdYa2pM7&q=85&s=7b8c551dcbddd9424ea54541be146e2e" alt="Auth0 がユーザーの確認済みメールアドレスにメールを送信する" style={{ width: '300px', height: 'auto' }} width="944" height="1098" data-path="docs/images/ciba/ciba_with_email_verification_link.png" />
</Frame>

<div id="step-5-user-authenticates-in-the-browser">
  ## ステップ 5: ブラウザーでユーザーが認証を行う
</div>

アクティブなセッションが見つからない場合、検証リンクによってユーザーに認証が求められます。ユーザーはリンクをクリックして認証処理を進めます。

認証するには、ユーザーは検証済みのメールアドレスとパスワードを入力します。ユーザーは、クライアントアプリケーションが [CIBA リクエストを開始](#step-1%3A-client-application-initiates-a-ciba-request)した際に `/bc-authorize` エンドポイントへ送信した `login_hint` パラメーターで指定された資格情報を使用する必要があります。そうしない場合はエラーメッセージが表示され、ログアウトしてやり直す必要があります。

<Frame>
  <img src="https://mintcdn.com/generaltranslationinc/md6b8ua1hdYa2pM7/docs/images/ciba/user_authenticates_in_browser.png?fit=max&auto=format&n=md6b8ua1hdYa2pM7&q=85&s=87c6fedddeb1662d616156328410a832" alt="ブラウザーでユーザーが認証を行う" style={{ width: '300px', height: 'auto' }} width="636" height="994" data-path="docs/images/ciba/user_authenticates_in_browser.png" />
</Frame>

認証が完了すると、ブラウザーは Auth0 Consent API から取得した同意内容をユーザーに提示します。ここには `binding_message`、`scope`、`audience` が含まれます。スコープは RBAC ポリシーに従ってフィルタリングされます。詳細については、[ロールベースのアクセス制御](/docs/ja-JP/manage-users/access-control/rbac)を参照してください。

次のコードサンプルは、Auth0 Consent API からのレスポンス例です。

```json lines theme={null}
{
  "id": "cns_abc123",
  "requested_details": {
    "audience": "https://$tenant.auth0.com/userinfo",
    "scope": ["openid"],
    "binding_message": "21-49-38"
  },
  "created_at": 1746693720
  "expires_at": 1746693750
}
```

この時点で、ユーザーは認証リクエストを承認するか拒否するかを選択できます。

<div id="step-6-browser-sends-the-user-response-back-to-auth0">
  ## ステップ 6: ブラウザーがユーザーの応答を Auth0 に送信する
</div>

ブラウザーはユーザーからの応答を Auth0 に送り返します。ユーザーが認証リクエストを承諾するか拒否するかに応じて、Auth0 は次の同意画面を表示します。これらの画面は、[同意プロンプトを設定](/docs/ja-JP/get-started/apis/configure-rich-authorization-requests#set-customized-consent-prompt)してカスタマイズする必要があります。

<div id="user-accepts-the-authentication-request">
  ### ユーザーが認証リクエストを承認する
</div>

<Frame>
  <img src="https://mintcdn.com/generaltranslationinc/md6b8ua1hdYa2pM7/docs/images/ciba/user_accepts_the_authentication_request.png?fit=max&auto=format&n=md6b8ua1hdYa2pM7&q=85&s=ff19dbb878a0ed96ecf19ce3b0924988" alt="User accepts the authentication request" style={{ width: '300px', height: 'auto' }} width="730" height="982" data-path="docs/images/ciba/user_accepts_the_authentication_request.png" />
</Frame>

<div id="user-rejects-the-authentication-request">
  ### ユーザーが認証リクエストを拒否する
</div>

<Frame>
  <img src="https://mintcdn.com/generaltranslationinc/md6b8ua1hdYa2pM7/docs/images/ciba/user_rejects_authentication_request.png?fit=max&auto=format&n=md6b8ua1hdYa2pM7&q=85&s=cb2422bad333a7c1450ec8d17accb26f" alt="ユーザーが認証リクエストを拒否する" style={{ width: '300px', height: 'auto' }} width="774" height="1038" data-path="docs/images/ciba/user_rejects_authentication_request.png" />
</Frame>

<div id="step-7-auth0-receives-user-response-after-the-flow-completes">
  ## ステップ 7: フロー完了後に Auth0 がユーザーの応答を受信する
</div>

クライアントアプリケーションは、`/token` エンドポイントからの応答を受信するとポーリングを終了します。CIBA フローでは常に、認可を行うユーザーからの承認または却下のいずれかの応答が必要であり、既存のグラントは参照されません。

<div id="step-8-auth0-returns-access-token-to-client-application">
  ## ステップ 8: Auth0 がアクセストークンをクライアントアプリケーションに返す
</div>

ユーザーがメールのリクエストを拒否した場合、Auth0 は次のようなエラーレスポンスをクライアントアプリケーションに返します。

```json lines theme={null}
{
    "error": "access_denied",
    "error_description": "エンドユーザーが認可リクエストを拒否したか、リクエストの有効期限が切れています"
}
```

ユーザーがメールによるリクエストを承認すると、Auth0 はクライアントアプリケーションに次のような<Tooltip tip="Access Token（アクセストークン）：不透明な文字列または JWT 形式の認可クレデンシャルで、API へのアクセスに使用されます。" cta="用語集を表示" href="/docs/ja-JP/glossary?term=access+token">アクセストークン</Tooltip>を返します。

```json lines theme={null}
{
    "access_token": "eyJh...",
    "id_token": "eyJh...",
    "expires_in": 86400,
    "scope": "openid",
    "token_type": "Bearer"
}
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `refresh_token` が含まれるのは、初回の `/bc-authorize` リクエストに `offline_access` スコープが含まれている場合のみです。
</Callout>

<div id="learn-more">
  ## さらに詳しく
</div>

* [Client-Initiated Backchannel Authentication フロー](/docs/ja-JP/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow)
* [Client-Initiated Backchannel Authentication の設定](/docs/ja-JP/get-started/applications/configure-client-initiated-backchannel-authentication)