client-security

client-security 策略可用于扩展 API 的客户机认证访问权。

网关支持

表 1. 该表显示了支持此策略的网关以及对应的策略版本
网关 策略版本
DataPower® API Gateway 2.0.0

本主题描述如何在 OpenAPI 源中配置策略; 有关如何在组合件用户界面中配置策略的详细信息，请参阅 客户机安全性。

关于

您可以使用 client-security 策略来创建独立于 OpenAPI 规范的组合件操作，以允许使用更多选项来认证应用程序。 请注意，不能使用 client-security 策略来执行速率限制实施。

在客户机安全操作中，定义以下设置。
  • 控制在客户机安全失败时是否停止处理。 客户机安全失败时，停止组合件处理并返回错误。
  • 控制是否需要客户机密钥。 如果需要，系统会将此密钥与客户机标识所标识的应用程序上注册的密钥进行比较。
  • 定义用于从请求抽取客户机凭证的方法。
    • 对于除 http以外的所有方法，请使用 id-name 和 secret-name 属性来指定包含标识的位置以及包含私钥的位置。
      • 当 cookie时，指定哪个 cookie。
      • 当 context-var时，指定运行时上下文变量。
      • 当 form时，指定表单数据。
      • 当 header时，指定哪个头。
      • 当 query时，指定哪个查询参数。
    • 对于 http 方法，请使用 http-type 属性来指定 Authorization 头的格式，该格式需要 basic base64_id:secret 格式的 basic 表单。
  • 定义用于认证抽取客户机凭证的方法。 受支持的方法为 native (这意味着使用 IBM® API Connect) 或使用指定的 third-party 用户注册表。
    • 如果 third-party，请使用 user-registry 属性指定用户注册表以认证抽取的客户机凭证。 受支持的注册表类型为 LDAP 和认证 URL。

属性

client-security 策略具有以下格式:

- client-security:  
    version: version
    title: title
    description: description
    stop-on-error: is_processing_stopped_on_client_security_failure
    secret-required: is_client_secret_required_in_request
    extract-credential-method: method_for_supplying_credentials
    id-name: parameter_that_specifies_client_id
    secret-name: parameter_that_specifies_client_secret
    http-type: authentication_type
    client-auth-method: method_for_client_authentication
    user-registry: user_registry_for_client_authentication
表 2. client-security 策略属性
属性 必需 描述 数据类型
version 是 策略版本号。 字符串
title False 策略的标题。 字符串
description False 对策略的描述。 字符串
stop-on-error 是 如果设置为 true，那么在客户机安全性失败时将停止组合件处理，并会返回错误。 布尔型
secret-required 是 如果设置为 true，那么必须在请求中发送客户机密钥。 该秘钥与客户机标识所识别的应用程序上的已注册秘钥进行比较。 布尔型
extract-credential-method 是 指定以下值之一以定义调用应用程序的认证方式：
  • header: 必须在请求头中提供客户机标识和客户机密钥凭证。
  • query：客户ID和客户密钥必须作为查询参数在URL 中提供。
  • form: 必须以 POST 请求中发送的表单数据形式提供客户机标识和客户机密钥凭证。
  • cookie: 必须在名为 Cookie的头中提供客户机标识和客户机密钥凭证。
  • http: 调用应用程序必须使用基本认证进行认证。
  • context-var: 用于认证客户机的凭证是从在客户机安全策略之前的组合件流中设置的上下文变量中获取的，例如，使用 gatewayscript 策略。 这些上下文变量的名称由在 client-security 策略的 id-name 和 secret-name 属性中提供的值确定。
 字符串
id-name 是（除非 extract-credential-method 设置为 http） 其值可指定客户机标识的参数的名称。 对于除 context-var 和 http以外的 extract-credential-method 的所有值，调用应用程序必须在 extract-credential-method 设置定义的位置中提供具有此名称的参数。 对于 context-var，此属性指定上下文变量的名称。

如果 extract-credential-method 属性设置为 http，那么此选项不适用。

 字符串
secret-name 是（如果 secret-required 设置为 true，并且 extract-credential-method 不是 http） 其值可指定客户机密钥的参数的名称。 对于除 context-var 和 http以外的 extract-credential-method 的所有值，调用应用程序必须在 extract-credential-method 设置定义的位置中提供具有此名称的参数。 对于 context-var，此属性指定上下文变量的名称。

如果 extract-credential-method 属性设置为 http，那么此选项不适用。

 字符串
http-type 是（如果 extract-credential-method 设置为 http） 认证类型。 目前，必须将此类型设置为 basic。 字符串
client-auth-method 是 请指定下列其中一个值：
  • native：仅使用客户机标识和客户机密钥对请求进行认证。 如果 extract-credential-method 设置为 http，那么调用应用程序必须将客户机标识提供为用户名，并将客户机密钥提供为密码。
  • third-party：使用用户注册表对客户机进行认证。 如果 extract-credential-method 设置为除 http 以外的值，那么调用应用程序必须将用户名提供为客户机标识，并将密码提供为客户机密钥。
 字符串
user-registry 是（如果 client-auth-method 设置为 third-party） 选择将用于对客户机进行认证的用户注册表的 name 属性值。 受支持的注册表类型为 LDAP 和认证 URL。 字符串

client-security 策略示例


- client-security:
    version: 2.0.0
    title: client-security
    stop-on-error: true
    secret-required: true
    extract-credential-method: cookie
    id-name: my-client-id
    secret-name: my-client-secret
    client-auth-method: third-party
    user-registry: myauthurl