同意要求の OpenID Connect 要求マッピング

オンラインで編集

OAuth と Open ID Connect の許可フローでは、許可を要求する同意プロンプトがユーザーに表示される場合があります。

許可フローは、以下のアクションを実行する許可を要求できます。
  • ユーザーのプロファイルからのデータ (E メール・アドレスなど) を共有します。 この要求は、オプションで、データを共用する目的を示す情報で補足することができます。
  • 寒い日にユーザーの車両と暖房を開始したり、支払いを開始したりするなど、ユーザーに代わってアクションを実行します。
通常、アプリケーションはパラメータの scope 形式でそのアクションをリクエストします。 ただし、場合によっては、そのリクエストを変更する必要があるかもしれません。 例えば、以下のとおりです。
  • ユーザー使用許諾契約については、必ずユーザーの認証状況を確認してください。
  • ユーザーの認証セッションに基づいて、特定のscope値をフィルターで除外します。
  • scope内でエンコードされているか (例: email_for_billing)、別の要求パラメーターの一部として使用できるか (例: authorization_details) に関係なく、データが要求される理由を示すコンテキストを追加します。

このタイプの変更は、同意要求パラメーターのカスタム・ルールを使用して行うことができます。 r_attr_functions.html を参照してください。 このルールは、単純な単一行の式言語を使用して作成することも、より高度な複数行の YAML ベースの文書として作成することもできます。 複数行ルール実行プログラムを参照してください。

使用可能な入力オブジェクト

このカスタム・ルールは認証の後、許可の前に実行されるため、使用可能な情報には、可能なすべてのドメイン・オブジェクトが含まれているわけではありません。 以下のタイプに限定されます。

HTTP 要求コンテキスト
ユーザーがVerifyにログインすると、要求マッピング・ルールで着信 HTTP 要求コンテキストにアクセスできます。 すべての OAuth 要求パラメーター (claims やscopeなど) は、このrequestContextで使用できます。 の requestContext 一般的な構造と使用方法については、『 r_attr_functions.html 』の「 HTTP リクエストコンテキスト」のセクションに記載されています。
簡単にアクセスできるように、requestContextでは特定の値が事前計算されています。 リクエストパラメータは claims 、次の例のようにJSON形式で表されます。
{
    "id_token": { 
        "claim_name": { 
            "essential": false, 
            "value": "some_value"
        }
    },
    "userinfo": {
        "claim_name": { 
            "essential": false, 
            "value": "some_value"
        }
    }
}

この JSON はアクセスが煩雑になる可能性があるため、requestContextで使用されるキーの形式はclaims_claimType_claimNameになります。 claimTypeは、userinfoまたはidtokenのいずれかです。 欠落している下線に注意してください。 したがって、前の例では、requestContext.getValue('claims_idtoken_claim_name')を使用してclaim_name値を取得できます。

同様に、scopeは、ストリング配列を作成するために計算され、スペースで分割されます。

ID ソースの資格情報

ユーザーがVerifyにログインすると、ID ソース資格情報属性がログイン・セッションに追加され、要求マッピング・ルールでアクセスできるようになります。

idsuserドメイン・オブジェクトは、ストリング・キーとストリング配列値を持つマップとして使用できます。 例えば、以下のとおりです。
{
  "realmName": ["cloudIdentityRealm"],
  "displayName": ["Jessica J. Hill"],
  "phone": ["+12324321234"]
}
詳細については、 r_attr_functions.html をご覧ください。
その他の関数および演算子

マッピング・ルールでは、標準の演算子と関数を使用できます。 HTTP クライアントは、アウトバウンド要求を行うためにも使用できます。 サポートされるその他の機能には、ハッシュおよびタイム・スタンプが含まれます。 『 r_attr_functions.html 』の関連箇所を参照してください。

オブジェクトを返す

カスタム・ルールは、ストリングまたはオブジェクトを含む配列を返すことが予期されています。 ストリングはスコープですが、オブジェクトはプライバシーの目的に関連付けるための追加情報を持つスコープです。 こちらをご覧ください… /tasks/t_manage_purposes.html.

以下のコードは、戻りオブジェクトの例です。 marketingユーザーが最初のリクエストオブジェクトに同意すると、の email 属性に対する同意が作成されます。 さらに、personal:emailスコープが付与され、personal_email_allowedクレームが ID トークンに追加されます。

[
	{
		"purpose": "marketing",
		"attribute": "email",
		"accessType": "read",
		"value": "jhill@ibm.com",
		"custom": {
			"type": "personal"
		},
		"claims": {
			"personal_email_allowed": true
		},
		"scope": "personal:email"
	},
    {
        "purpose": "defaultEULA"
    },
	"profile",
	"email"
] + requestContext.scope
注:

このリストは、要求されたスコープを完全に置き換え、同意ページを作成するために使用されます。 「 OpenID ページのシングルサインオンを変更する」 を参照してください。 ユーザーにさらに同意を求める場合は、スコープの追加と削除の例に示すように、requestScope.scopeを追加する必要があります。

この例では、配列は 2 つのタイプを取ることができます。1 つはストリングとしての OAuth スコープで、もう 1 つはより多くのコンテキストを持ち、より詳細な同意許可レコードを生成するオブジェクトです。 これらのプロパティーは、オブジェクトで許可されるプロパティーです。

プロパティー タイプ 必須かどうか 説明
purpose ストリング はい ../tasks/t_manage_purposes.html
attribute ストリング 目的により異なる 属性の管理
accessType ストリング 目的により異なる アクセス・タイプは、データ・プライバシーの目的で構成されます。 指定しない場合、デフォルトでdefaultになります。
value ストリング いいえ より具体的な同意要求を示します。 例えば、特定の E メールの同意などです。
custom JSON オブジェクト。 JSON プロパティー値のタイプはストリングです。 いいえ 同意に追加される追加のコンテキスト情報です。 このプロパティは、テンプレートマクロとして同意ページに表示することができます。
claim JSON オブジェクト。 JSON プロパティー値のタイプはストリングです。 いいえ 要求が許可されると、対応するクレームが、発行された ID トークンに追加されます。
scope ストリング いいえ 要求が許可されている場合、この値は許可されたスコープに追加されます。
required ブール いいえ が true に設定されている場合 required 、ユーザーは承諾の意思表示をしなければなりません。 プライバシーポリシーの決定において、同意が決して受け入れられないことが明記されている場合、この同意は不要です。
autoGrant ブール いいえ が true に設定されている場合 autoGrant 、ユーザーに同意を求めるプロンプトは表示されず、同意項目は自動的に承認されます。
global ブール いいえ が true に設定されている場合 global 、記録された同意はすべてのアプリケーションで共通となります。 このプロパティは、ユーザーが一度だけ同意する利用規約などの同意事項に関連しています。
audience ストリング いいえ リクエストが承認された場合、この値は、アプリケーションで設定されたオーディエンスのリストおよびデフォルトのクライアントIDとともに、許可されたオーディエンスに追加されます。
スコープの追加と削除の例
この例では、新しい同意要求オブジェクトが追加され、スコープが削除されます。
[
   {
       "purpose": "defaultEula",
       "scope": "eula:default"
   }
] + requestContext.scope.filter(x, x != "badscope")

このルールは、スコープeula:defaultに許可を付与し、それを EULA 同意に関連付けます。 また、要求されたスコープからbadscope をフィルターで除外します。

同意ページをカスタマイズして、このマッピング・ルールによって追加された同意要求の詳細を表示することができます。 例については、 OpenID の「ConnectリクエストのマッピングとオープンバンキングのインテントID」をご覧ください。