CIBA によるユーザーの認可

クライアント主導のバックチャネルフローで Rich Authorization Requests を使用する方法を学びます。

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

クライアント主導のバックチャネル認証 (CIBA) は、クライアントアプリケーションが、開始元のアプリケーションでユーザーの直接的な操作を必要とせずに、認証および/または 認可フロー を開始できるようにする OAuth 2.0 の仕様です。Rich Authorization Requests (RAR) は OAuth 2.0 の拡張機能であり、クライアントアプリケーションが認可リクエストで標準の OAuth 2.0 スコープを超える、より複雑な権限をリクエストできるようにします。

CIBA と RAR を組み合わせることで、バックチャネルリクエストで きめ細かな認可 データを 認可サーバー に渡せます。authorization_details パラメーターにはリクエストの詳細が含まれており、その内容はユーザーに表示する同意プロンプトでカスタマイズできます。

CIBA では、次の通知チャネルを使用してユーザーを認可できます。

• Auth0 Guardian アプリと、Auth0 Guardian SDK を統合したカスタムアプリを使用するモバイルプッシュ通知。
• カスタマイズした同意プロンプトの設定が必要なメール通知。

​

一般的なユースケース

よりきめ細かなリソースアクセス制御が必要なユースケースでは、RAR を CIBA フローと組み合わせて使用します。一般的なユースケースには、次のようなものがあります。

1. 支払いアプリが、送金の確認をユーザーに求めます。authorization_details は、トランザクションの詳細を表示するようにカスタマイズできます。
2. AI エージェントが、予約変更された診察の詳細をユーザーに提示します。authorization_details は、新しい日時を表示するようにカスタマイズできます。

​

仕組み

CIBA を使用したユーザー認可フローは、CIBA を使用したユーザー認証フローと似ており、RAR をサポートしているため、クライアントは /bc-authorize エンドポイントを介して authorization_details を認可サーバーに渡すことができます。

次のシーケンス図は、CIBA を使用したユーザー認可フローのエンドツーエンドの流れを示しています。

以下のセクションでは、CIBA におけるユーザー認可の仕組みを順を追って説明します。

• 前提条件
• ステップ 1: クライアントアプリケーションが CIBA リクエストを開始する
• ステップ 2: Auth0 テナントが CIBA リクエストを受け付ける
• ステップ 3: クライアントアプリケーションが応答をポーリングする
• ステップ 4: 認証デバイスがプッシュ通知を受信する
• ステップ 5: 認証デバイスが同意の詳細を取得する
• ステップ 6: 認証デバイスが同意の詳細をユーザーに提示する
• ステップ 7: 認証デバイスがユーザーの応答を Auth0 に送り返す
• ステップ 8: フローの完了後、Auth0 がユーザーの応答を受信する
• ステップ 9: Auth0 がクライアントアプリケーションにアクセストークンを返す

​

前提条件

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

• テナントとアプリケーションに対して、クライアント主導のバックチャネル認証を設定します。これには、通知チャネルの設定も含まれます。
• リソースサーバーに対して、Rich Authorization Requests を設定します。これには、authorization_details のタイプの登録が含まれます。
• RAR を使用する CIBA でメール通知を使用する場合は、カスタマイズされた同意プロンプトを設定します。

​

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

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

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

curl --location 'https://{YOUR_DOMAIN}.auth0.com/bc-authorize' \
  --request POST \
  --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 'audience=https://api.example.com' \
  --data-urlencode 'binding_message=Confirm payment of 2500' \
  --data-urlencode 'authorization_details=[{
      "type": "money_transfer", 
      "instructedAmount": {
        "amount": 2500, 
        "currency": "USD"
      }, 
      "sourceAccount": "xxxxxxxxxxx1234", 
      "destinationAccount": "xxxxxxxxxxx9876", 
      "beneficiary": "Hanna Herwitz", 
      "subject": "A Lannister Always Pays His Debts"
    }]'

Parameters	説明
tenant	login_hint 構造内で渡されるテナント名です。カスタムドメインを指定することもできます。iss_sub 形式を使用する場合、テナント名は iss クレーム内で渡されます。 例: login_hint={"format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub":"{USER_ID"}
client_id	クライアントアプリケーションの識別子です。
client_secret	CIBA でユーザーを認証する際に使用するクライアント認証方式です。たとえば、Client Secret、Private Key JWT、mTLS 認証があります。Private Key JWT または mTLS を使用する場合は、client secret を含める必要はありません。
scope	openid を含める必要があります。 必要に応じて、スコープに offline_access を含めてリフレッシュトークンを要求することもできます。ただし、CIBA フローでトランザクションを一度だけ認可する場合、リフレッシュトークンは不要であり、この文脈では意味を持ちません。
user_id	login_hint 構造内で渡される、認可を行うユーザーのユーザー ID です。iss_sub 形式を使用する場合、ユーザー ID は sub クレーム内で渡されます。 例: login_hint={"format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub":"{USER_ID}"} ユーザー ID の形式は、外部プロバイダーによって異なる場合があります。
requested_expiry	CIBA フローの要求有効期限は 1 ～ 259200 秒 (72 時間) で、デフォルトは 300 秒です。CIBA フローにカスタムの有効期限を設定するには、requested_expiry パラメーターを含めます。 requested_expiry パラメーターは、CIBA がどの通知チャネルを使用するかを判断するのに役立ちます: requested_expiry を 300 秒以下に設定すると、有効になっている場合、CIBA はモバイルプッシュ通知チャネルを使用します。テナントに MFA を設定していない場合、CIBA リクエストは失敗します。 requested_expiry を 301 ～ 259200 秒に設定すると、有効になっている場合、CIBA はメール通知チャネルを使用します。
binding_message	認証を行うデバイスと利用側デバイスの間で CIBA フローを関連付けるために使用される、人が読めるメッセージです。binding message は必須で、64 文字以内である必要があります。使用できるのは英数字と +-_.,:# のみです
audience	発行される token の audience を一意に識別する値です。
authorization_details	認可する権限を記述する省略可能な JSON オブジェクトの配列です。各オブジェクトの type 値は、リソースサーバーの authorization_details パラメーターを使用してリソースサーバーに登録する必要があります。詳しくは、Configure Rich Authorization Requests を参照してください。

​

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

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

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

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

​

ステップ 3: クライアントアプリケーションが応答をポーリングする

Authentication API を使用して、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 は、Auth0 Guardian アプリまたは Auth0 Guardian SDK を組み込んだカスタムモバイルアプリに通知を送信します。
• メール通知: Auth0 は、ユーザーの確認済みメールアドレスに通知を送信します。

​

Step 5: 認証デバイスが同意の詳細を取得する

認証デバイスは、Auth0 Consent API から同意の詳細、つまり binding_message の内容を取得します。

• Mobile push notification: Auth0 Guardian アプリ、または Auth0 Guardian SDK を組み込んだカスタムアプリが Auth0 Consent API を呼び出し、同意の詳細を取得します。
• Email notification: ユーザーが確認リンクをクリックするとブラウザーにリダイレクトされ、そのブラウザーが Auth0 Consent API から同意の詳細を取得します。

​

ステップ 6: 認証デバイスが同意の詳細をユーザーに提示する

Auth0 Consent API は、認証デバイスに同意の詳細を返します。これには、設定されている場合、binding_message、scope、audience、authorization_details が含まれます。モバイルアプリケーションに返されるスコープは、RBAC ポリシーに従ってフィルタリングされます。詳しくは、ロールベースのアクセス制御を参照してください。

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

{
  "id": "cns_2309dsfsd098",
  "requested_details": {
    "audience": "https://api.example.com",
    "scope": ["read:profile", "write:profile"],
    "binding_message": "abc123",
    "authorization_details": [
      {
        "type": "money_transfer",
        "instructedAmount": {
          "amount": 2500,
          "currency": "USD"
        },
        "sourceAccount": "xxxxxxxxxxx1234",
        "destinationAccount": "xxxxxxxxxxx9876",
        "beneficiary": "Hanna Herwitz",
        "subject": "A Lannister Always Pays His Debts"
      }
    ]
  },
  "created_at": 1632739200,
  "expires_at": 1632739200
}

認証デバイスは、authorization_details とともに同意の詳細をユーザーに表示します。

• モバイルプッシュ通知: Auth0 Guardian アプリは、プッシュ通知を使用して同意画面に authorization_details をレンダリングします。
• メール通知: ブラウザーは、カスタム同意画面に authorization_details をレンダリングします。同意画面をカスタマイズする方法については、カスタマイズされた同意プロンプトを設定する を参照してください。

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

​

Step 7: 認証デバイスがユーザーの応答を Auth0 に返送する

ユーザーが認可リクエストを承諾または拒否すると、認証デバイスはその応答を Auth0 に返送します。

• モバイルプッシュ通知: Auth0 Guardian アプリ、または Auth0 Guardian SDK を統合したカスタムアプリケーションが、ユーザーの応答を Auth0 に返送します。
• メール通知: ブラウザーがユーザーの応答を Auth0 に返送します。

​

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

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

​

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

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

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

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

{
  "id_token": "...",
  "access_token": "...",
  "expires_in": "...",
  "scope": "{SCOPES}",
  "authorization_details": [{
      "type": "money_transfer", 
      "instructedAmount": {
        "amount": 2500, 
        "currency": "USD"
      }, 
      "sourceAccount": "xxxxxxxxxxx1234", 
      "destinationAccount": "xxxxxxxxxxx9876", 
      "beneficiary": "Hanna Herwitz", 
      "subject": "A Lannister Always Pays His Debts"
    }]
}

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

​

authorization_details を照会する

コンパイル時には、JSON を動的に照会するのと同じように、authorization_details の型やオブジェクトを同意の詳細から厳密な型で照会できます。

iOS

let requestedDetails: ConsentRequestedDetails = payload.requestedDetails
let myAuthorizationDetailsTypes = requestedDetails.authorizationDetails[0].objectValue!;
let type = myAuthorizationDetailsTypes["type"]?.stringValue // 事前登録した type 値
let stringProperty = myAuthorizationDetailsTypes["string_property"]?.stringValue
let boolProperty = myAuthorizationDetailsTypes["bool_property"]?.boolValue
let numericProperty = myAuthorizationDetailsTypes["numeric_property"]?.doubleValue
let nestedObjectProperty = myAuthorizationDetailsTypes["nested_property"]?.objectValue
let nestedArrayProperty = myAuthorizationDetailsTypes["nested_array_property"]?.arrayValue

Android

RichConsentRequestedDetails requestedDetails = consentDetails.getRequestedDetails();
Map<String, Object> authorizationDetails = requestedDetails.getAuthorizationDetails().get(0);
String type = (String) myAuthorizationDetailsTypes.get("type");
String stringProperty = (String) myAuthorizationDetailsTypes.get("string_property");
boolean booleanProperty = (boolean) myAuthorizationDetailsTypes.get("boolean_property");
int numericProperty = (int) myAuthorizationDetailsTypes.get("numeric_property");
Object nestedObjectProperty = myAuthorizationDetailsTypes.get("nested_property");
List<Object> nestedArrayProperty = (List<Object>) myAuthorizationDetailsTypes.get("nested_array_property");

オブジェクトを表すカスタム型を定義している場合は、filterAuthorizationDetailsByType() 関数を使用して、目的の型に一致する authorization_details オブジェクトをすべて返せます。

次のコードサンプルでは、payment 型の authorization_details を照会しています。

iOS

// AuthorizationDetailsType を実装する必要があります
struct Payment : AuthorizationDetailsType { 
static let type = "payment"; 
let amount: Double; 
let currency: String; 
} 

... 

let requestedDetails: ConsentRequestedDetails = payload.requestedDetails 
let payments = requestedDetails.filterAuthorizationDetailsByType(Payment.self) 
let firstPayment = payments.first!
let type: String = firstPayment.type // "payment" 
let amount: Double = firstPayment.amount 
let currency: String = firstPayment.currency

Android

@AuthorizatioDetailsType("payment")
class Payment {
    private String type;
    private int amount;
    private String currency;

    public Payment(String type, int amount, String currency) {
        this.type = type;
        this.amount = amount;
        this.currency = currency;
    }

    public String getType() {
        return type;
    }

    public int getAmount() {
        return amount;
    }

    public String getCurrency() {
        return currency;
    }
}

...

RichConsentRequestedDetails requestedDetails = consentDetails.getRequestedDetails();
List<Payment> payments = requestedDetails.filterAuthorizationDetailsByType(Payment.class);
Payment firstPayment = payments.get(0);
String type = firstPayment.getType();
int amount = firstPayment.getAmount();
String currency = firstPayment.getCurrency();

filterAuthorizationDetailsByType() は、指定した authorization_details 型に一致するオブジェクトのみを返します。そのため、モバイル アプリケーションでは、リクエストの内容をユーザーが完全に理解できるよう、型に関係なく関連するすべての authorization_details を同意のために提示する必要があります

AI エージェントまたはアプリケーションが応答を取得するために /oauth/token エンドポイントをポーリングするときにも、authorization_details を照会できます。

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

パラメータ	説明
grant_type	CIBA のグラントタイプ urn:openid:params:grant-type:ciba を設定します。
client_id	アプリケーションのクライアント ID を設定します。
client_secret	アプリケーションのクライアントシークレットを設定します。
auth_req_id	Auth0 テナントが CIBA リクエストを受理した際に返されます。CIBA リクエストを参照する ID です。

認可を行うユーザーがリクエストを承認すると、Auth0 はユーザーの応答を受け取り、CIBA フローが完了して、アクセストークンと authorization_details 配列が返されます。

{ 
  "access_token": "ey...ZQ", 
  "expires_in": 86400, 
  "authorization_details": [{ 
    "type": "money_transfer", 
    "instructedAmount": {
      "amount": 2500, 
      "currency": "USD"
    }, 
    "sourceAccount": "xxxxxxxxxxx1234", 
    "destinationAccount": "xxxxxxxxxxx9876", 
    "beneficiary": "Hanna Herwitz", 
    "subject": "A Lannister Always Pays His Debts" 
  }], 
  "token_type": "Bearer" 
}

​

制限事項

Auth0 は以下をサポートしていません。

• CIBAフローで Actions 内の RAR を変更すること。
• クライアントが検出できるように RAR タイプを公開すること。つまり、クライアントが送信できる authorization_details のタイプを事前に登録しておく必要があります。
• API で許可されているタイプに一致する type プロパティを持っているかどうかの確認を超えて、RAR オブジェクトを検証すること。authorization_details 内の内容をきめ細かく検証する責任は、リソースサーバーにあります。詳しくは、RARを構成 を参照してください。

​

詳しく見る

• Rich Authorization Requests (RAR) を設定する
• Rich Authorization Requests (RAR) を使用する認可コードフロー
• クライアント主導のバックチャネル認証を設定する