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

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

許可フローは、以下のアクションを実行する許可を要求できます。

ユーザーのプロファイルからのデータ (E メール・アドレスなど) を共有します。この要求は、オプションで、データを共用する目的を示す情報で補足することができます。
寒い日にユーザーの車両と暖房を開始したり、支払いを開始したりするなど、ユーザーに代わってアクションを実行します。

通常、アプリケーションは scope パラメータの形式でアクションを要求します。しかし、時にはリクエストを修正する必要があるかもしれません。例えば、以下のとおりです。

ユーザーライセンス契約については、常にユーザーの認証状況を確認してください。
ユーザーの認証セッションに基づいて、特定のscope値をフィルターで除外します。
scope内でエンコードされているか (例: email_for_billing)、別の要求パラメーターの一部として使用できるか (例: authorization_details) に関係なく、データが要求される理由を示すコンテキストを追加します。

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

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

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

HTTP 要求コンテキスト

ユーザーがVerifyにログインすると、要求マッピング・ルールで着信 HTTP 要求コンテキストにアクセスできます。すべての OAuth 要求パラメーター (claims やscopeなど) は、このrequestContextで使用できます。の一般的な構造と使用法については、属性関数の requestContext 「 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"]
}

詳細については、属性関数を参照してください。

その他の関数および演算子

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

オブジェクトを返す

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

以下のコードは、戻りオブジェクトの例です。ユーザーが最初のリクエストオブジェクトに同意すると、 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`	ストリング	はい	プライバシー情報の目的の管理
`attribute`	ストリング	目的により異なる	属性の管理
`accessType`	ストリング	目的により異なる	アクセス・タイプは、データ・プライバシーの目的で構成されます。指定しない場合、デフォルトで`default`になります。
`value`	ストリング	いいえ	より具体的な同意要求を示します。例えば、特定の E メールの同意などです。
`custom`	JSON オブジェクト。 JSON プロパティー値のタイプはストリングです。	いいえ	同意に追加される追加のコンテキスト情報です。このプロパティーは、テンプレート・マクロの形式で同意ページに表示できます。
`claim`	JSON オブジェクト。 JSON プロパティー値のタイプはストリングです。	いいえ	要求が許可されると、対応するクレームが、発行された ID トークンに追加されます。
`scope`	ストリング	いいえ	要求が許可されている場合、この値は許可されたスコープに追加されます。
`required`	ブール	いいえ	`required` が true に設定されている場合、ユーザーは同意して応答する必要があります。プライバシー・ポリシーの決定で同意が受け入れられないことが示されている場合、この同意は必要ありません。
`autoGrant`	ブール	いいえ	`autoGrant` が true に設定されている場合、ユーザーに同意を求めるプロンプトは出されず、同意項目は自動的に許可されます。
`global`	ブール	いいえ	`global` が true に設定されている場合、記録された同意はすべてのアプリケーションにわたってグローバルになります。このプロパティは、ユーザーが一度だけ承諾する利用規約などの承諾事項に関連します。
`audience`	ストリング	いいえ	リクエストが認可されると、この値は、アプリケーションで設定されているオーディエンスのリストとデフォルトのクライアントIDとともに、認可されたオーディエンスに追加される。

スコープの追加と削除の例

この例では、新しい同意要求オブジェクトが追加され、スコープが削除されます。

[
   {
       "purpose": "defaultEula",
       "scope": "eula:default"
   }
] + requestContext.scope.filter(x, x != "badscope")

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

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