OpenID Connect 请求映射 Open Banking 意向标识

在线编辑

当第三方应用程序要发起需要用户授权的交易（例如，支付转账）时，它会使用金融机构或银行提供的 API 来登记交易的详细信息。 例如，它会登记交易的金额以及货币类型。 这个过程有时被称为“提出意向”。 API 使用意向标识符进行响应，在英国开放银行规范中也称为同意标识。 应用程序启动 OAuth 授权代码流以获取记录为用户同意的用户授权。

由于表示事务的有效负载以及在授权请求中包含意向标识的过程没有明确定义，因此管理员可以使用 IBM® Verify 通过定制规则编写以下操作的脚本。
  • 从请求中抽取意向标识。
  • 获取意向上下文信息（通常通过调用银行的 API）。
  • 选择如何将 id_token 中的授权表示为声明或范围值。
该定制规则基于多行规则执行程序中描述的语法。 更简单的规则可以是单行规则并且不必以 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 已计算并用空格分割以构建字符串数组。

身份源凭证

用户登录 Verify 时，身份源凭证属性被添加到登录会话中，并且可以在请求映射规则中访问。

idsuser 域对象以具有字符串键和字符串数组值的映射形式提供。 例如，

{
  "realmName": ["cloudIdentityRealm"],
  "displayName": ["Jessica J. Hill"],
  "phone": ["+12324321234"]
}
有关更多信息，请参阅 “属性函数 ”。
其他函数和运算符

标准运算符和函数在映射规则中可用。 也可以使用 HTTP 客户机来发出出站请求。 其他受支持的功能包括散列和时间戳记。 请参阅 “属性函数 ”中的相关章节。

返回对象

由于必须解释此定制规则以构建授权上下文，因此此规则的返回值必须是 JSON 对象，该对象必须包含以下必需属性：

属性 类型 是否必需？ 描述
type 字符串 是 该类型指示要执行的事务的类型。 例如，启动支付。 这在 Verify 中表示为数据隐私用途。 由系统提供或生成的用途标识是 type 的值。
intentID 字符串 是 必须提供该意向标识。 它通常是根据 requestContext计算而得。
claims JSON 对象。 JSON 属性值可以是任何类型。 否 通常，在用户授权时，生成的标识令牌包含一些指示，表明用户授权了由意向标识所标识的交易。 claims 是 JSON 对象或映射，其中键是声明名称，值可以是任何与 JSON 兼容的结构，例如字符串、整数、另一个对象、数组或其他结构。 还可以指定多个声明。
scope 字符串 否 如果请求已授权，那么会将此值添加到被授权的范围。

任何其他属性（例如，金额或货币）都被视为定制属性。 它们可以通过使用稍后描述的相应模板宏显示在用户同意页面中。

UK Open Banking 示例

要发起支付，必须先提出意向。 在此场景中涉及以下参与者：
  • 驻留在第三方提供者上并启动支付交易的支付启动服务提供者 (PISP)。
  • 帐户信息服务提供者 (ASPSP) 授权服务器。 在此场景中，ASPSP 为 Verify。
  • 用于托管支付启动 API 的 ASPSP 资源服务器。
PISP 会重定向用户以针对授权服务器执行授权，并提供意向标识。 授权服务器需要执行下列任务：
  1. 抽取意向标识。
  2. 从资源服务器检索有关此事务的信息。
此定制规则两个操作。
从请求中抽取意向标识
此示例遵循通过 claims 发送意向标识的 UK Open Banking 标准。 传入授权请求中在声明中包含 openbanking_intent_id。

{
	"id_token": {
		"openbanking_intent_id": {
			"value": "b508f9df-799b-4120-a13e-5d09f2931fa6",
			"essential": true
		}
	}
}
这些声明将在请求上下文中抽取并提供。 用于检索该值的代码为：

requestContext.getValue('claims_idtoken_openbanking_intent_id')
检索交易信息
交易信息存储在帐户服务支付服务提供者 (ASPSP) 资源服务器中，同意或意向标识将在此服务器中生成。 使用 HTTP 客户机向资源服务器发出请求。 以下请求是一个示例。
hc.getAsJSON("https://resource.myaspsp.com/internal/intents/" + context.intentID
将交易映射到隐私用途和声明
要捕获 Open Banking 支付启动和帐户访问许可，必须创建相关隐私用途。 例如，必须为任何支付启动同意请求创建 payment_initiation隐私用途。 然后，此用途将映射到返回对象中的 type 属性。
此外，对于 UK Open Banking，需要创建 openbanking_intent_id 声明。 还可以将有关交易的剩余信息添加到返回对象中。

{
   "type": "payment_initiation",
   "intentID": "b508f9df-799b-4120-a13e-5d09f2931fa6",
   "currency": "USD",
   "amount": "1200.35",
   "merchant": "Merchant A",
   "claims": {
      "openbanking_intent_id": "b508f9df-799b-4120-a13e-5d09f2931fa6"
   }
}
样本映射规则

statements:
- if:
    match: "!has(requestContext.claims_idtoken_openbanking_intent_id)"
    return: null
- context: "intentID := requestContext.getValue('claims_idtoken_openbanking_intent_id')"
- context: 'intentContext := hc.getAsJSON("https://resource.myaspsp.com/internal/intents/" + context.intentID, { "Authorization": "apikey supersecretapikey" })'
- return: >-
    {
        "type": context.intentContext.type,
        "intentID": context.intentID,
        "currency": context.intentContext.instructedAmount.currency,
        "amount": context.intentContext.instructedAmount.amount,
        "merchant": context.intentContext.creditorName,
        "claims": {
            "openbanking_intent_id": context.intentID
        }
    }

定制同意页面

由于交易授权的同意用户体验与标准的 OAuth 和Open ID Connect范围同意有所不同，因此可以在同意页面模板中创建一个自定义部分，请参阅《 修改 OpenID 页面的单点登录设置 》。

例如，

[RPT purpose_payment_initiation]
<input type="hidden" name="@PRIVACY_SCOPE_PNAME_REPEAT@"
    value="@PRIVACY_SCOPE_REPEAT@" privacy-readonly="true" />
<input type="hidden" id="@PRIVACY_SCOPE_PNAME_REPEAT@_state" name="@PRIVACY_SCOPE_PSTATE_REPEAT@"
    value="CONSENT_ALLOW" privacy-required="@PRIVACY_SCOPE_REQUIRED_REPEAT@" />
<div id="@PRIVACY_SCOPE_PNAME_REPEAT@_widget" class="bx--form-item" style="width:350px;"></div>
<div class="bx--grid" style="padding-left:0">
    <div class="bx--row" style="padding-bottom:6px;">
    <div class="bx--col-sm-1">Amount</div>
    <div class="bx--col">@PRIVACY_SCOPE_CUSTOM_currency@ @PRIVACY_SCOPE_CUSTOM_amount@</div>
    </div>
    <div class="bx--row" style="padding-bottom:6px;">
    <div class="bx--col-sm-1">Merchant</div>
    <div class="bx--col">@PRIVACY_SCOPE_CUSTOM_merchant@</div>
    </div>
    <div class="bx--row" style="padding-bottom:6px;">
    <div class="bx--col-sm-1">Reference</div>
    <div class="bx--col">@PRIVACY_SCOPE_ATTRVALUE_REPEAT@</div>
    </div>
</div>
[ERPT purpose_payment_initiation]
请注意以下方面。
  • 这是一个新的可重复部分，用于特定数据隐私用途。 所使用的名称采用格式 purpose_{purposeID}。 purposeID 是数据隐私用途标识。 此用途标识可以是系统生成的标识，也可以是用户提供的标识。
  • 两个 HTML 表单字段是必需的，分别名为 @PRIVACY_SCOPE_PNAME_REPEAT@ 和 @PRIVACY_SCOPE_PNAME_REPEAT@_state。 第一个字段包含该同意记录的 Verify 标识。 第二个字段包含同意的状态。
  • 可以通过使用宏 @PRIVACY_SCOPE_CUSTOM_{attributeName}@ 来引用高级规则所返回的定制属性。 例如，@PRIVACY_SCOPE_CUSTOM_currency@ 将替换为在意向高级规则中返回的货币值。