CIBA でのメール通知

メール通知を使用して、クライアント主導のバックチャネル認証フローでユーザーを認証する方法を学びます。

クライアント主導のバックチャネル認証 (CIBA) 機能を使用するには、Enterprise プランまたは適切なアドオンが必要です。詳しくは Auth0 Pricing を参照してください。

CIBA でメール通知を使用すると、ユーザーには、ブラウザーで認証またはリクエストの承認を行うためのリンクを含むメールが送信されます。

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

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

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

• 前提条件
• ステップ 1: クライアントアプリケーションが CIBA リクエストを開始する
• ステップ 2: Auth0 テナントが CIBA リクエストを確認する
• ステップ 3: クライアントアプリケーションがレスポンスをポーリングする
• ステップ 4: Auth0 がユーザーのメールアドレスにリンクを送信する
• ステップ 5: ユーザーがブラウザーで認証する
• ステップ 6: ブラウザーがユーザーに同意の詳細を表示する
• ステップ 7: フロー完了後に Auth0 がユーザーの応答を受信する
• ステップ 8: Auth0 がクライアントアプリケーションにアクセストークンを返す

​

前提条件

Auth0 を使用して CIBA のメールリクエストを開始するには、次の設定が必要です。

• tenant とアプリケーションに対して、クライアント主導のバックチャネル認証を設定します。メール通知の設定も必要です。
• requested_expiry パラメーターを 301 ～ 259200 秒 (72 時間) の範囲で設定します。詳しくは、通知チャネルを設定するを参照してください。
• CIBA と Rich Authorization Requests (RAR) のメール通知をユーザー認可で使用する場合は、カスタマイズされた同意プロンプトを設定します。

​

ステップ 1: クライアントアプリケーションが CIBA リクエストを開始する

User Search APIs を使用して、CIBA リクエストを開始する対象の認可を行うユーザーを特定し、そのユーザー ID を取得します。

認可を行うユーザーのユーザー ID を取得したら、Authentication API または SDK を使用して、/bc-authorize エンドポイントに CIBA リクエストを送信します。

cURL

curl --location 'https://{YOUR_DOMAIN}.auth0.com/bc-authorize' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'login_hint={ "format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub": "{USER_ID}" }' \
  --data-urlencode 'scope={SCOPES}' \
  --data-urlencode 'binding_message={BINDING_MESSAGE}'

C#

var response = await authenticationApiClient.ClientInitiatedBackchannelAuthorization(
            new ClientInitiatedBackchannelAuthorizationRequest()
            {
                ClientId = "{YOUR_CLIENT_ID}",
                Scope = "{SCOPES}",
                ClientSecret = "{YOUR_CLIENT_SECRET}",
                BindingMessage = "{BINDING_MESSAGE}",
                LoginHint = new LoginHint()
                {
                    Format = "iss_sub",
                    Issuer = "https://{YOUR_DOMAIN}.auth0.com/",
                    Subject = "{USER_ID}"
                }
            }
        );

Go

resp, err := authAPI.CIBA.Initiate(context.Background(), ciba.Request{
    ClientID:     mgmtClientID,
    ClientSecret: mgmtClientSecret,
    Scope:        "openid",
    LoginHint: map[string]string{
      "format": "iss_sub",
      "iss":    "https://{YOUR_DOMAIN}.auth0.com/",
      "sub":    "{USER_ID}",
    },
    BindingMessage: "{BINDING_MESSAGE}",
  })

Java

//AuthClient インスタンスを作成
AuthAPI auth = AuthAPI.newBuilder(domain, clientId, clientSecret).build();

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

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

BackChannelAuthorizeResponse resp = request.execute().getBody();

パラメーター	説明
tenant	テナント名です。カスタムドメインを使用することもできます。iss_sub 形式を使用する場合、テナント名は iss クレーム内で渡されます。
client_id	クライアントアプリケーションの識別子です。
client_secret	CIBA でユーザー認証を行う際に使用するクライアント認証方式です。たとえば、Client Secret、Private Key JWT、mTLS Authentication などがあります。Private Key JWT または mTLS を使用している場合は、client secret を含める必要はありません。
scope	openid を含める必要があります。 必要に応じて、リフレッシュトークンを要求するために offline_access を含めることもできます。ただし、CIBA フローにおけるトランザクションの 1 回限りの認可では、リフレッシュトークンは不要であり、このコンテキストでは意味を持ちません。
user_id	login_hint 構造内で渡される、認可を行うユーザーのユーザー ID です。iss_sub 形式を使用する場合、ユーザー ID は sub クレーム内で渡されます。 ユーザー ID の形式は、外部プロバイダーによって異なる場合があります。
requested_expiry	CIBA セッションを有効にしておく最大期間 (秒) です。CIBA フローの有効期限は 1 秒から 259200 秒 (72 時間) の範囲で、デフォルトは 300 秒です。CIBA フローにカスタムの有効期限を設定するには、requested_expiry パラメーターを含めます。 requested_expiry パラメーターは、CIBA がどの通知チャネルを使用するかを判断するのに役立ちます。 requested_expiry を 300 秒以下に設定した場合、有効になっていれば CIBA はモバイルプッシュ通知チャネルを使用します。テナントに MFA が設定されていない場合、CIBA リクエストは失敗します。 requested_expiry を 301 秒から 259200 秒 (72 時間) の間に設定した場合、有効になっていれば CIBA はメール通知チャネルを使用します。
binding_message	認証デバイスと利用デバイスの間で CIBA フローを関連付けるために使用される、人が読めるメッセージです。binding message は必須で、64 文字以内である必要があります。使用できるのは英数字と +-_.,:# のみです。

認可を行うユーザーには、1 分あたり 5 件を超えるリクエストは送信されないというユーザーごとのレート制限があります。

​

ステップ 2: Auth0 テナントが CIBA リクエストを確認応答する

Auth0 テナントが POST リクエストを正常に受信すると、そのリクエストを参照する auth-req-id を含むレスポンスを受け取るはずです:

{
    "auth_req_id": "eyJh...",
    "expires_in": 300,
    "interval": 5
}

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

​

Step 3: クライアントアプリケーションがレスポンスをポーリングする

Authentication API または SDK を使用して、urn:openid:params:grant-type:ciba グラントタイプと /bc-authorize エンドポイントから受け取った auth_req_id を指定し、/token エンドポイントを呼び出します。

cURL

curl --location 'https://{YOUR_DOMAIN}.auth0.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'auth_req_id={AUTH_REQ_ID}' \
  --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'

C#

var token = await authenticationApiClient.GetTokenAsync(
            new ClientInitiatedBackchannelAuthorizationTokenRequest()
            {
                AuthRequestId = response.AuthRequestId,
                ClientId = "{YOUR_CLIENT_ID}",
                ClientSecret = "{YOUR_CLIENT_SECRET}"
            }
        );

Go

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{})

Java

Request<BackChannelTokenResponse> tokenRequest = auth.getBackChannelLoginStatus(authReqId, "grant-type");

BackChannelTokenResponse tokenResponse = tokenRequest.execute().getBody();

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

{
    "error": "authorization_pending",
    "error_description": "エンドユーザーの認証が保留中です"
}

ポーリングの待機間隔は約5秒です。短い間隔でポーリングしすぎると、次のレスポンスが返されます。説明はバックオフ間隔によって異なります。

{
"error": "slow_down",
"error_description": "You are polling faster than allowed. Try again in 10 seconds."
"interval": 10
}

このエラーを解消するには、次のポーリング間隔 (秒) が経過するまで待ってから、/token エンドポイントをポーリングしてください。

​

ステップ 4: Auth0 がユーザーのメールアドレスにリンクを送信する

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

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

​

ステップ5: ユーザーがブラウザーで認証する

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

認証するには、ユーザーは確認済みのメールアドレスとパスワードを入力します。ユーザーは、クライアントアプリケーションがCIBA リクエストを開始する際に /bc-authorize エンドポイントに送信した login_hint パラメーターで指定された資格情報を使用する必要があります。そうでない場合はエラーメッセージが表示され、ログアウトして再度やり直す必要があります。

通常のログインフローと同様に、CIBA with email フローでも post-login Actions トリガーが実行されるため、アクセス制御ポリシーを適用したり、追加の MFA 認証要素を求めたりするカスタムロジックを実装できます。CIBA 検証リンクから実行された場合、event.transaction.protocol の値は oidc-ciba-web-link になります。これにより、この種類のログインに対して固有のカスタムルールを適用できます。詳しくは、Login Trigger をご覧ください。

認証が完了すると、ブラウザーに Auth0 Consent API から取得した同意の詳細が表示されます。これには binding_message、scope、audience が含まれます。スコープは RBAC ポリシーに従ってフィルタリングされます。詳しくは、ロールベースのアクセス制御 をご覧ください。

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

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

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

​

ステップ 6: ブラウザーがユーザーの応答を Auth0 に返送する

ブラウザーはユーザーの応答を Auth0 に返送します。ユーザーが認証リクエストを承認するか拒否するかに応じて、Auth0 は次の同意画面を表示します。これらの画面は、同意プロンプトを設定することでカスタマイズする必要があります。

​

ユーザーが認証リクエストを承認する

​

ユーザーが認証リクエストを拒否した場合

​

ステップ 7: フロー完了後、Auth0 がユーザーの応答を受け取る

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

​

ステップ 8: Auth0 がクライアントアプリケーションにアクセストークンを返す

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

{
    "error": "access_denied",
    "error_description": "エンドユーザーが認証リクエストを拒否したか、有効期限が切れました"
}

ユーザーがメールによるリクエストを承認すると、Auth0 は次のような アクセストークン をクライアントアプリケーションに返します。

{
    "access_token": "eyJh...",
    "id_token": "eyJh...",
    "expires_in": 86400,
    "scope": "openid",
    "token_type": "Bearer"
}

refresh_token が含まれるのは、最初の /bc-authorize リクエストに offline_access スコープが含まれていた場合のみです。

​

詳細を見る

• クライアント主導のバックチャネル認証フロー
• クライアント主導のバックチャネル認証を設定する