Rich Authorization Requests (RAR) を設定する

リソースサーバー向けに Rich Authorization Requests (RAR) を設定する方法を学びます。

Rich Authorization Requests (RAR) を使用すると、クライアントは プッシュ型認可リクエスト (PAR) を使用した認可コードフロー および クライアント主導のバックチャネル認証フロー で、エンドユーザーなどの リソース所有者 から きめ細かな認可 データをリクエストして取得できます。

Rich Authorization Requests では authorization_details パラメータを使用します。このパラメータは JSON のオブジェクト配列を受け取り、リクエストしている認可に関する詳細情報 (たとえば、クライアントがユーザーに代わってアクセスしたい特定のリソースやアクションなど) を含めることができます。

リクエストされた authorization_details は、次のいずれかの方法でユーザーにレンダリングできます。

• ブラウザーで、カスタマイズされた同意プロンプト を使用する
• モバイルアプリケーションで、Auth0 Guardian SDK または Auth0 Guardian app のプッシュ通知を使用する

リソースサーバー に対して Rich Authorization Requests を設定するには、次の作業が必要です。

1. リソースサーバーの authorization_details タイプを登録 する。
2. アプリがそれらのタイプをリクエストできるように、API Access ポリシーを設定 する。
3. authorization_details をレンダリングするために、カスタマイズされた同意プロンプトを設定 する。
4. 任意: リソースサーバーの同意ポリシーを設定 する。

​

authorization_details タイプを登録する

JSON配列内の各オブジェクトには、オブジェクトの構造を示す type フィールドが必要です。authorization_details 配列には、同じ type のエントリを複数含めることができます。

​

Auth0 Guardian app

Auth0 Guardian app を使用している場合、authorization_details パラメータの値には、配列内に 1 つのオブジェクトのみを含める必要があり、そのオブジェクトは次の Auth0 スキーマに準拠している必要があります。

Field	Description	Example
type	認可リクエストのタイプを指定します。 urn:auth0:schemas:authorization-details: リクエストで Auth0 スキーマを使用することを示す Auth0 URN です。 v1: スキーマのバージョンです。 user-profile: このリクエストがユーザープロファイル情報を対象としていることを示す、顧客指定の値です。	urn:auth0:schemas:authorization-details:v1:user-profile
instruction	リクエストの承認を求める、ユーザー向けの人が読んで理解しやすいメッセージです。	Please approve the request.
properties	要求されている特定のユーザー属性またはクレームを含む JSON オブジェクトです。各キー (例: email、full_name) は、ユーザープロファイルの特定のフィールドを表します。 display: そのプロパティを同意ダイアログでユーザーに表示するかどうかを決定するブール値です。true の場合は表示され、false の場合はユーザーには表示されない内部専用のプロパティになります。 name: プロパティの人が読んで理解しやすい名前です (例: “Email Address”) 。 display_order: 同意ダイアログでプロパティを表示する順序を指定する整数です。 description: プロパティの目的についての省略可能な短い説明です。 value: プロパティの実際のデータ値です (例: “[e-mail]”、“John Doe”) 。データ型は文字列、整数、ブール値などさまざまです。	"properties": { "stringPropertyForDisplay": { "display": true, "name": "A String:", "display_order": "1", "value": "Value 1"} }

以下は、Auth0 スキーマを使用した authorization_details タイプの例です。

{
    "type": "urn:auth0:schemas:authorization-details:v1:user-profile",
    "instruction": "An instruction to the user",
    "properties": {
        "stringPropertyForDisplay": {
            "display": true,
            "name": "A String:",
            "display_order": 1,
            "value": "Value 1"
        },
        "numericPropertyForDisplay": {
            "display": true,
            "name": "A Number:",
            "display_order": 2,
            "description": "An optional description",
            "value": 100.00
        },
        "booleanPropertyForDisplay": {
            "display": true,
            "name": "A Boolean:",
            "display_order": 3,
            "value": true
        },
        "hiddenProperty": {
            "display": false,
            "value": "This value should not be displayed"
        }
    }
}

​

その他の通知チャネル

Auth0 Guardian app を使用していない場合、authorization_details の type で Auth0 スキーマ を使用する必要はありません。authorization_details をカスタマイズされた同意プロンプト、または Auth0 Guardian SDK を使用する独自のモバイルアプリに表示する場合は、次の要件が適用されます。

• 最大 5Kb
• 有効な JSON であること
• オブジェクトの配列であること
• 配列内のエントリ数は最大 5
• すべてのオブジェクトに type プロパティが必要 (API に事前登録されているもの)
• オブジェクトごとのプロパティ数は最大 10
• プロパティ名の最大文字数は 255
• プロパティ値の最大文字数は 255
• ネストされたオブジェクトは最大 5 階層
• プロパティ名に使用できる文字は次のとおりです: a-zA-Z0-9_.-

以下は、Auth0 スキーマ を使用しない money_transfer type の authorization_details の例です。これには次のオブジェクト フィールドが含まれます。

• instructedAmount: 送金される USD 建ての金額。
• sourceAccount: 資金の送金元となる銀行口座。
• destinationAccount: 資金の送金先となる銀行口座。
• beneficiary: 送金の受取人。
• subject: 送金の件名。

{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}

authorization_details type は、許可するスコープを登録するのと同様に、リソースサーバーに登録する必要があります。authorization_details type は、Auth0 Dashboard または Management API で登録できます。

Auth0 Dashboard

Auth0 Dashboard で authorization_details を追加するには、次の手順を行います。

1. Auth0 Dashboard > Applications > APIs に移動します。
2. Permissions タブを選択します。
3. Add an Authorization Details type で、リソースサーバーに複数の authorization_details type を追加できます。authorization_details type を入力します。
4. +Add オプションを選択します。

リソースサーバーの authorization_details type は、List of Authorization Details Types で確認できます。

Management API

既存のリソースサーバーに authorization_details type を登録するには、Update a resource server エンドポイントに PATCH リクエストを送信します。

次のコードサンプルは、リソースサーバーの authorization_details に payment_initiation type と money_transfer type を追加します。

curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "authorization_details": [{"type": "payment_initiation"}, {"type": "money_transfer"}]
  }'

登録済みの authorization_details type を持つ新しいリソースサーバーを作成するには、/resource-servers エンドポイントに POST リクエストを送信します。

次の POST リクエストは、authorization_details type payment_initiation を持つ新しいリソースサーバーを作成します。

curl --location --request POST 'https://$tenant/api/v2/resource-servers' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Payments API",
  "identifier": "https://payments.api/",
  "authorization_details": [{"type": "payment_initiation"}]
  }'

​

API Accessポリシーを設定する

API Access Policies for Applications では、どのアプリケーションが API にアクセスできるか、また、どのスコープまたは authorization_details タイプへのアクセスが許可されるかを制御できます。

Management API を使用すると、API の現在のポリシーを確認できます。リソースサーバーを取得するエンドポイントに GET リクエストを送り、レスポンスの subject_type_authorization プロパティを確認してください。

curl --location --request GET 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json'

subject_type_authorization プロパティには、client.policy と user.policy の値を設定できます。

• policy の値が allow_all の場合、アプリケーションまたはユーザーは、その API に登録されているすべての authorization_details タイプをリクエストできます。
• policy の値が require_client_grant の場合、そのアプリケーションでは、各 authorization_details タイプがクライアントグラントによって明示的に許可されている必要があります。
• policy の値が deny_all の場合、どのアプリケーションまたはユーザーも、その API に登録されている authorization_details タイプを一切リクエストできません。

アプリケーションのクライアントグラントの管理方法について詳しくは、API へのアプリケーションアクセス: クライアントグラント を参照してください。

​

カスタマイズされた同意プロンプトを設定する

同意プロンプトに、Rich Authorization Request の authorization_details をレンダリングできます。これを行うには、適切な template partials を使用して customized-consent prompt を設定します。

Auth0 CLI または Management API を使用して、カスタマイズされた同意プロンプトを設定できます。

​

Auth0 CLI

Customized Consent の partials を設定するには、ターミナルで適切なフラグを指定して auth0 ul customize コマンドを実行します。

auth0 ul customize

詳しくは、auth0 universal-login customize のドキュメントをお読みください。

​

Management API

Customized Consent の partials を設定するには、/prompts/customized-consent/partials エンドポイントに PUT リクエストを送信します:

curl --location --request PUT "https://$tenant/api/v2/prompts/customized-consent/partials" \
  --header "Authorization: Bearer $management_access_token" \
  --header "Content-Type: application/json" \
  --data '{
    "customized-consent": {
      "form-content": "<div style=\"font-size: 1.3em; font-weight: bold;\">Operation Details</div><hr style=\"margin: 10px 0;\"><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Transaction Type</div><div>{{ transaction.params.authorization_details[0].type }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Amount</div><div>{{ transaction.params.authorization_details[0].instructedAmount.amount }} {{ transaction.params.authorization_details[0].instructedAmount.currency }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Recipient</div><div>{{ transaction.params.authorization_details[0].beneficiary }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Destination Account</div><div>{{ transaction.params.authorization_details[0].destinationAccount }}</div><div style=\"margin-bottom: 20px;\"></div>"
    }
  }'

Customized Consent テンプレートは、Auth0 がエンドユーザーに表示する次の同意プロンプト内で authorization_details をレンダリングします。

CIBA と RAR フローでのメール通知では、ユーザーに承認画面または拒否画面を表示するため、同意プロンプトをカスタマイズする必要があります。

同意プロンプトをカスタマイズする方法について詳しくは、以下を参照してください。

• Universal Login ページをカスタマイズする
• No-Code Editor で Universal Login をカスタマイズする
• プロンプトに partials を設定する API ドキュメント

​

任意: リソースサーバーの同意ポリシーを設定する

リソースサーバーの同意ポリシーでは、Auth0 が authorization_details の値を保存し、プッシュ通知の送信時にそれらをモバイルアプリケーションで利用できるようにするかどうかを決定します。

authorization_details を含むリクエストに対する、Auth0 の標準の同意ポリシーの動作を確認してください。

フロー	プッシュ通知の送信	動作
すべて	いいえ	カスタマイズされた同意プロンプトが表示されます。
PAR を使用する認可コードフロー	はい	同意プロンプトは表示されません。同意は、プッシュ通知チャレンジを受け取るモバイルアプリケーション側で表示する必要があります。 Auth0 Guardian app を使用している場合、authorization_details は自動的にユーザーに表示されます。 カスタムモバイルアプリを使用している場合、authorization_details は Auth0 Guardian SDK を使用して取得できます。
クライアント主導のバックチャネル認証フロー	はい	CIBA リクエストの認可に Auth0 Guardian app を使用している場合、authorization_details は自動的に取得されて表示されます。 CIBA リクエストの認可にカスタムモバイルアプリを使用している場合、authorization_details は Auth0 Guardian SDK を使用して取得できます。 CIBA リクエストを Web リンク (たとえばメール内のリンク) で認可している場合は、カスタマイズされた同意プロンプトが表示されます。 ユーザーが Web リンクで承認する際に、お客様が CIBA リクエストの第 2 認証要素としてプッシュ通知をトリガーすることもできます。その場合の動作は上記と同じです。Auth0 Guardian app は authorization_details を再度自動的にユーザーへ表示し、カスタムモバイルアプリは必要に応じて Auth0 Guardian SDK を使用して authorization_details を取得できます。

お客様は、consent_policy を transactional-authorization-with-mfa に設定することもできます。この場合の動作は次のとおりです。

フロー	プッシュ通知の送信	動作
PAR を使用する認可コードフロー	いいえ	カスタマイズされた同意プロンプトが表示されます。
PAR を使用する認可コードフロー	はい	同意プロンプトは表示されません。お客様のソリューションで、独自のユーザーインターフェースを使って同意を表示する必要があります。Auth0 はリクエストに一意の ID を割り当て、event.transaction.requested_authorization_details とともに event.transaction.linking_id として Post-Login Action に公開します。 Auth0 Guardian app を使用している場合、authorization_details は表示されません。 カスタムモバイルアプリを使用している場合、プッシュ通知には linking_id が含まれ、必要に応じてアプリケーション開発者が独自の API から authorization_details を取得できます。
クライアント主導のバックチャネル認証フロー	すべて	transactional-authorization-with-mfa 同意ポリシーでは CIBA フローはサポートされていません

リソースサーバーの同意ポリシーは、Auth0 Dashboard または Management API で設定できます。

Auth0 Dashboard

Auth0 Dashboard を使用して、API の設定で同意ポリシーを設定します。

1. Auth0 Dashboard > Applications > APIs に移動します。
2. 設定 タブを選択します。
3. Access Settings で、Standard 同意ポリシーを選択します。
4. 変更を保存します。

Management API

Management API を使用してリソースサーバーまたは API の同意ポリシーを設定するには、Update a resource server エンドポイントに PATCH リクエストを送信します。PATCH リクエストでは、consent_policy を standard に設定します。

curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{ "consent_policy": "standard" }'