IBM OpenPages GRC REST API V2

使用此版本的 IBM OpenPages GRC REST API 进行新实施。

IBM OpenPages GRC REST API 提供对 IBM OpenPages® 数据和元数据的访问。 此以数据为中心的 API 是根据资源，其 URI 以及可对这些 URI 执行的操作来指定的。

有关如何使用 IBM OpenPages GRC REST API V2 的信息，请参阅 参考文档。

先决条件

要有效使用IBM OpenPagesGRC REST API，请确保您熟悉以下主题：
  • IBM OpenPages
  • Web Service ，例如 ASDL 和 REST
  • HTML 和 JavaScript 脚本语言 JSON
  • 编程语言和集成开发环境 (IDE) ，例如 Java™ 编程语言和 Eclipse IDE，或者 C# 编程语言和 Microsoft Visual Studio IDE。

SCIM 2.0 支持

IBM OpenPagesGRC REST API V2符合 SCIM2.0规范，可用于用户供应和管理。

更多信息，请参阅跨域身份管理系统。

安全性和认证

身份验证委托给 IBM® WebSphere® Application Server，因此每个入口点都不需要验证身份验证令牌。

使用基本身份验证、客户端证书身份验证和 OAuth2.0身份验证，在办公场所使用 "IBM OpenPages，在云上使用IBM OpenPages。

将基于令牌的认证与 IBM OpenPages for IBM Cloud Pak for Data配合使用。

基本认证

缺省情况下，通过 OpenPages 应用程序服务器配置基本认证。 基本授权方案遵循 RFC 2617 规范。 客户通过发送 HTTP头来实施基本授权方案。 基本授权包含文本 Basic ，后跟用户名，冒号 (:) 和密码。 文本必须Base64 编码。 例如，要发送用户名 Aladdin 和密码 open sesame ，请使用以下 HTTP头字段：

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

OpenPages GRC REST API 遵循 RESTful 系统的无国籍原则，因此发出的每个请求都必须提供用户的凭证。 如果将基本认证与某些外部安全系统 (例如 SSL) 配合使用，那么将其视为安全认证。 为了确保最大的安全性，请确保客户仅发送未加密的凭据，并通过 HTTPS 发送请求。

客户机证书认证

OpenPages 提供使用 WebSphere Liberty 概要文件 (WLP) 的客户机证书认证。

客户机证书认证是一种基于相互证书的认证方法，其中客户机向服务器提供其客户机证书以证明其身份。 只有在服务器对客户机进行认证之后，服务器才允许请求。 客户机必须提供用于标识客户机的人员的公用密钥证书。 要认证客户机，服务器必须信任证书。 可以将 WLP 配置为通过将其手动添加到其信任密钥库来信任任何客户机证书。 如果另一可信证书以数字方式签署客户机证书，那么 WLP 也可以信任客户机证书。 例如，如果知名的 SSL 证书颁发机构（如DigiCert,颁发了签署 ibm ibm.com® 客户证书的证书，WLP 就可以信任客户证书。

此流量通过SSL HTTPS ）传输，可确保连接和加密的安全性。 此外， API 级别的控件提供了一个选项，用于配置安全模型以仅允许某些预先核准的客户机向 REST API 发出请求。 要使 OpenPages 使用客户端认证而非基本认证，必须配置 WebSphere Liberty。 有关在 WebSphere Liberty 中配置应用程序以使用客户端证书认证的信息，请参阅如何设置Liberty以使用基于证书的认证。

OpenPages 与 IBM WebSphere Liberty 安全性集成需要进行配置更改。 有关详细信息，请参阅将OpenPages与IBM WebSphere Liberty安全性集成。

令牌认证

缺省情况下，通过 OpenPages 应用程序服务器在 IBM OpenPages for IBM Cloud Pak for Data下配置令牌认证。 令牌是微配置文件 JSON Web 令牌 (MP-JWT)，如Eclipse MicroProfileInteroperable JWT RBAC 中所述。 客户端发送HTTP授权报头，该报头以文本 Bearer 开头，后跟一个有效的MP-JWT令牌，例如 Authorization: Bearer <Valid MP-JWT Token> 。

要获取有效的令牌，请在安装OpenPages的服务器上使用生成授权令牌或 API 密钥中描述的其中一种身份验证 API。

IBM OpenPages GRC REST API 遵循 RESTful 系统的无国籍原则，因此发出的每个请求都必须提供用户的凭证。 缺省情况下， IBM OpenPages for IBM Cloud Pak for Data 下的所有通信都会实施 SSL。

配置 OAuth2.0身份验证

OAuth2.0允许用户在与应用程序共享特定数据时保持用户名、密码和其他信息的私密性。 您可以在本地的 "IBM OpenPages或云上的 "IBM OpenPages上为 "IBM OpenPagesREST APIV1和V2配置OAuth2.0身份验证。

在此配置中，"OpenPages在 OAuth2.0身份验证流中扮演资源服务器的角色。 您可以使用 OAuth2.0授权服务器或OpenIDConnect (OIDC) 提供商作为身份提供方IdP）。

开始之前

您的环境必须符合以下标准：

  • 设置并运行 OAuth2.0授权服务器或 OIDC 提供商。
  • 注册一个客户端账户，供 "OpenPages服务器用于执行自省或验证身份。 该账户必须在 OAuth2.0或 OIDC 提供商中创建。 OpenPages仅在授权服务器上使用客户 ID 和客户秘密来验证令牌。
  • 使用 "OpenPagesREST API 的每个外部客户端都必须在 OAuth2.0授权服务器中分配一个服务账户用户 ID，或者在 OIDC 提供商中拥有一个用户身份。 映射到每个客户端的服务账户或功能 ID 的用户名必须与 "OpenPages系统中的用户匹配。
  • 如有必要，在 "OpenPages中创建一个用户，用户名为 "service-account，并设置所需的权限，以便客户凭据流正常运行。 client_id来自 OIDC 提供商。
  • 已安装OpenPages99.0或更高版本，且 "OpenPages服务器正在运行。
  • 您可以从浏览器中登录到 OpenPages 应用程序。

关于本任务

在此任务中，您将配置IBM WebSphere Liberty服务器作为OpenIDConnect 客户端。 更多信息，请参阅OpenIDConnect Client (openidConnectClient)。

您可以使用任何支持 OAuth2.0或OpenIDConnect 协议的提供商。

过程

  1. 登录 "OpenPages应用服务器。
  2. 运行以下命令安装IBM WebSphere Liberty openidConnectClient-1.0和transportSecurity-1.0功能：
    <WLP_HOME>/bin/installUtility install openidConnectClient-1.0
<WLP_HOME>/bin/installUtility install transportSecurity-1.0
  3. 转到目录 "<WLP_USER_DIR>/servers/<server_name>Server<#>/configDropins/overrides。
    如果目录不存在，请创建。
  4. 创建一个 .xml 文件。 在文件中，将OAuth2_OIDC_provider变量（如 "<OAuth2_OIDC_provider_client_ID>）替换为 OIDC 提供商的信息后，插入以下几行。
    <server>
<featureManager>
    <feature>openidConnectClient-1.0</feature>
    <feature>transportSecurity-1.0</feature>
</featureManager>
<openidConnectClient id="providerClient" inboundPropagation="required"
                     clientId="<OAuth2_OIDC_provider_client_ID>"
                     audiences="<OAuth2_OIDC_provider_client_ID>, account"
                     clientSecret="<OAuth2_OIDC_provider_client_SECRET>"
                     jwtAccessTokenRemoteValidation="require"
                     userIdentityToCreateSubject="<OAuth2_OIDC_Provider_username_attribute>"
                     issuerIdentifier="<OAuth2_OIDC_provider_ISSUER_ENDPOINT_URL>"
                     jwksUri="<OAuth2_OIDC_provider_JWKS_ENDPOINT_URL>"
                     validationEndpointUrl="<OAuth2_OIDC_provider_INTROSPECTION_ENDPOINT_URL>"
>
    <authFilter id="oauthApiAuthFilter">
        <requestUrl id="apiCUrl" matchType="contains" urlPattern="/grc/api|/opgrc/api"/>
    </authFilter>
</openidConnectClient>
</server>

    确保 "<authFilter>元素不包含与之冲突的 "<requestUrl>过滤器。

    提示：要添加更多过滤器，请创建更多 "<requestUrl>元素。 Give each of them a unique id.
  5. 从授权服务器或 OIDC 提供商导出根证书机构和中间证书机构证书。

    如需了解更多信息，请联系您的医疗服务提供者。

  6. 将根证书颁发机构和中间证书颁发机构的证书导入 "OpenPages信任库。
    例如：
    keytool -importcert -v -alias <certificate_alias> -file <path_to_certificate> -keystore <OP_HOME>/wlp-usr/servers/<server_name>Server<#>/resources/security/key.p12 -storetype PKCS12
  7. 停止所有 "OpenPages服务。
  8. 重启所有 "OpenPages服务。

下一步操作

要在IBM OpenPagesGRC REST API公共身份验证中使用 OAuth2.0协议，请使用由授权服务器或OpenID提供商签发的 JSON Web 令牌 (JWT) 承载令牌。

客户机/服务器交互

客户机与 IBM OpenPages GRC REST API的交互 (包括事件序列) 取决于客户机的设计和交互目标。 交互检索元数据和配置信息，然后向服务器发送更多请求以收集更多数据或执行更新。

图 1。 用于创建类型为 LossEvent 的新 GRC 对象的交互
此图显示用于创建类型为 LossEvent的新 GRC 对象的交互。

将 "OpenPages与IBM WebSphere Liberty安全性相结合

OpenPages通过WebSphere LibertyProfile (WLP) 提供客户端证书验证。 要将 "OpenPages与自由安全集成，必须更改服务器配置。

开始之前

  • 您必须有访问OpenPages应用程序服务器的权限和修改服务器配置的权限。
  • 您必须拥有代表客户的x509公钥证书。 该证书需要一个主体（Subject），该主体可识别该客户端正在验证的 "OpenPages中的用户。 For example, a subject might be /CN=OpenPagesAdministrator for a user OpenPagesAdministrator, or /C=US/O=IBM/OU=WFSS/CN=brianl for another user with the name brianl. 这些用户名必须作为用户账户存在于 "OpenPages中。

关于本任务

本任务向您演示如何配置新安装的环境，以允许 REST API 使用客户证书验证。 如果修改了全局安全配置或 GRC 安全域（例如使用 SSO），可能需要根据环境调整这些步骤。

过程

  1. 将目录更改为 " <WLP_HOME>/usr/servers/<OP_SERVER>/configDropins/overrides.

    如果 "overrides目录不存在，请创建它。

  2. 创建一个包含以下内容的 ".xml文件：
    <server>
<feature>transportSecurity-1.0</feature>
<sslDefault sslRef="defaultSSLConfig" />
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="SSL_TLSv2" trustStoreRef="defaultTrustStore" clientAuthenticationSupported="true"/>
<keyStore id="defaultTrustStore" password="defaultPWD" />
<webAppSecurity allowFailOverToBasicAuth="true" />
</server>
    • <ssl>属性 "clientAuthenticationSupported可用于客户端证书验证。
    • <keyStore>元素必须指定要使用的有效信任库（如 "defaultTrustStore）和信任库密码（如 "defaultPWD）作为属性。 默认密钥存储位于 " <WLP_HOME>/usr/servers/<OP_SERVER>/resources/security/key.p12中。
    • 如果证书验证失败，"<webAppSecurity>属性 "allowFailOverToBasicAuth允许 API 使用基本验证。 更多信息，请参见https://www.ibm.com/docs/en/was-liberty/base?topic=configuration-webappsecurity
  3. 将 CA 签名证书添加到信任库。
    例如
    keytool -keystore <WLP_HOME>/usr/servers/<OP_SERVER>/resources/security/key.p12 -storepass <password> -importcert -alias <Certificate alias> -file <Path to CA certificate> -storetype PKCS12
  4. 在新创建的 ".xml文件中，在 "<server>元素内创建一个 "<openpagesUserRegistry/>元素。
  5. 根据客户证书主题为'<openpagesUserRegistry/>元素添加属性。 OpenPages自定义用户注册表使用这些属性从客户证书的 "主题 "条目中解析用户名。
    示例 1

    下面的示例是一种更简单的方法，它可以查找主题中首次出现的 CN=。

    <openpagesUserRegistry com.ibm.openpages.security.entry.user.key="CN" com.ibm.openpages.security.entry.user.delimiter="," com.ibm.openpages.security.cert.regex="true"/>
    示例 2

    您可以使用正则表达式（regex），以便更灵活地处理客户证书中不同格式的主题，具体取决于贵组织的政策和惯例。 使用 regex，您可以指定更精细的逻辑，从证书中更大的 "主题 "元素中解析出用户名。 证书的主题元素可包含多个部分。 下面的示例使用正则表达式解析主题为 ""/C=US/O=IBM/OU=WFSS/CN=brianl"的用户名。

    <openpagesUserRegistry com.ibm.openpages.security.entry.user.regex="(?:CN=)([^,]+),?" com.ibm.openpages.security.cert.regex="true"/>

    在 regex 中，组是将多个字符视为一个单元的方法。 将要分组的字符放在一组括号内即可创建。

    捕获组将括号内的 regex 匹配的文本捕获到一个编号组中。 编号组可以重复使用，并有编号的背面参考。 使用捕获组将 regex 操作符应用于整个分组 regex。

    非捕获分组是在正则表达式中对一组字符或表达式进行分组而不捕获匹配文本的一种方法。 非捕获组的语法是在开头的括号后加上问号和冒号，通知正则表达式引擎不要存储匹配的文本。

    在例 2 中，regex 表达式引擎会查找与 "CN=匹配的非捕获组。 找到匹配项后，将捕捉匹配项和逗号分隔符之间的文本。 当 Liberty 解释客户证书中的 "主题 "时，结果是 ""CN=brianl, OU=WFSS, O=IBM, C=US"。

    regex 表达式与 "CN=brianl匹配，从匹配中提取的用户名是正则表达式识别为 "brianl的捕获组 #1。

    下面的主题文本示例说明了一种不同的情况，"CN=的值是一个电子邮件地址，而不是用户名。

    Text "CN=brianl@us.ibm.com,
        OU=WFSS, O=IBM, C=US"

    下面的 regex 会匹配 "CN=和 "@符号之间的文本，从而给出主题中的用户名。

    (?:CN=)([^@]+),?
  6. 停止 "OpenPages应用服务器。
  7. 在 REST API 应用程序 "web.xml文件的 "<login-config>部分，更改 "<auth-method>元素，指定 "CLIENT-CERT身份验证方法，而不是 "BASIC身份验证方法。 文件位于目录 " <WLP_HOME>/usr/shared/apps/op-apps.ear/com.ibm.openpages.api.rest.war/WEB-INF.
    如果 "web_merged.xml文件存在于 " <WLP_HOME>/usr/shared/apps/op-apps.ear/com.ibm.openpages.api.rest.war/WEB-INF目录中，则对 "web_merged.xml文件做同样的更改。

    更改后，每个文件的 "<login-config>部分显示如下：

    <login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>OpenPagesRealm</realm-name>
    </login-config>
  8. 重新启动 "OpenPages应用服务器。

下一步操作

您可以使用支持这种身份验证方法的 REST 客户端来测试客户端证书身份验证的工作原理。 例如，UNIX 风格的cURL命令就支持这种方法。

例如，如果客户证书为 "client1.pem，服务器为 "my-op-server，请使用下面的 "cURL命令：

curl --tlsv1.2
        --no-alpn --verbose --cert /path-to-/client1.pem
        https://my-op-server:10111/opgrc/api/v2/types
该命令返回以下结果：
  • 由于包含 "--verbose选项，所有与 SSL 握手相关的输出。
  • 响应体包含描述 "OpenPages元数据模式的 JSON，因为请求指定要返回所有类型。

如果服务器没有使用有效的 SSL 证书，可以在命令中添加 "--insecure选项进行测试。 --no-alpn选项是在 "cURL版本 "7.36.0中引入的。 如果您的cURL版本早于7.36.0，请删除 "--no-alpn选项。

您可以使用此方法测试其他IBM OpenPagesGRC REST API端点。

将监管事件与任务、子任务和要求相对应

当您使用App Connect或IBM OpenPagesGRC REST API 导入监管事件时，您可以将摄入的监管事件映射到监管库对象：任务、子任务和要求。

关于本任务

要进行关联，请使用IBM OpenPagesGRC REST API调用。 本任务中的示例说明了需要将一个监管事件与现有任务和子任务关联起来的用例。

过程

  1. 获取监管事件的资源 ID。 
    https://<server_name>:<port_number>/opgrc/api/v2/query?q=SELECT * FROM [RegulatoryEvent] WHERE [RCM-RegulatoryEvent:Amended Citation] LIKE '<value>'
    请求类型：GET
    例如，查询 " RCM-RegulatoryEvent:Amended Citation 字段并查找 "12 CFR 1026值。
    https://server1.ibm.com:10111/opgrc/api/v2/query?q=SELECT * FROM [RegulatoryEvent] WHERE [RCM-RegulatoryEvent:Amended Citation] LIKE '%2512 CFR 1026%25'

    该查询返回的资源 ID 是 "12593。

  2. 获取关联要使用的任务的资源 ID。 
    https://<server_name>:<port_number>/opgrc/api/v2/query?q=SELECT [Resource ID] FROM [Mandate] where [RCM-Mand:Citation] = '<value>'
    请求类型：GET
    例如，查询 " RCM-Mand:Citation 字段并查找 "12 CFR 1026值。
    https://server1.ibm.com:10111/opgrc/api/v2/query?q=SELECT [Resource ID] FROM [Mandate] where [RCM-Mand:Citation] = '12 CFR 1026'

    该查询返回的资源 ID 是 "9946。

  3. 获取关联使用的子任务的资源 ID。 
    https://<server_name>:<port_number>/opgrc/api/v2/query?q=SELECT [Resource ID] FROM [Submandate] where [RCM-SubMand:Citation] = '<value>'
    请求类型：GET
    例如，查询 " RCM-SubMand:Citation 字段并查找 "12 CFR 1026.8值。
    https://server1.ibm.com:10111/opgrc/api/v2/query?q=SELECT [Resource ID] FROM [Submandate] where [RCM-SubMand:Citation] = '12 CFR 1026.8'

    该查询返回的资源 ID 是 "9981。

  4. 调用 OpenPages ，将监管事件与两个父级关联，即授权和子授权，使用之前步骤中检索到的资源ID URL
    https://<server_name>:<port_number>/opgrc/api/v2/contents/<id>/associations/parents

    请求类型POST

    JSON 格式的帖子参数： {"associations":[{"id": "<id_of_mandate>"}, {"id": "<id_of_sub-mandate>"}]}

    例如
     https://server1.ibm.com:10111/opgrc/api/v2/contents/12593/associations/parents

    JSON 格式的帖子参数： {"associations":[{"id": "9946"}, {"id": "9981"}]}