IBM OpenPages GRC REST API V2

Use this version of the IBM OpenPages GRC REST API for new implementations.

The IBM OpenPages GRC REST API provides access to IBM OpenPages® data and metadata. This data-centric API is specified in terms of resources, their URIs, and actions that can be performed on these URIs.

For information about how to use the IBM OpenPages GRC REST API V2, see the reference documentation.

Prerequisites

To use the IBM OpenPages GRC REST API effectively, ensure that you are familiar with the following topics:
  • IBM OpenPages
  • Web services such as ASDL and REST
  • HTML and the JavaScript scripting language JSON
  • Programming languages and integrated development environments (IDEs), such as the Java™ programming language and the Eclipse IDE, or the C# programming language and the Microsoft Visual Studio IDE.

Security and authentication

Authentication is delegated to the IBM® WebSphere® Application Server, so each entry point doesn't need to verify the authentication token.

Use basic authentication, client certificate authentication, and OAuth 2.0 authentication with IBM OpenPages on premises or IBM OpenPages on Cloud.

Use token-based authentication with IBM OpenPages for IBM Cloud Pak for Data.

Basic authentication

Basic authentication is configured by default through your OpenPages application server. The basic authorization scheme follows the RFC 2617 specification. The client implements the basic authorization scheme by sending an HTTP request header. Basic authorization contains the text Basic followed by the username, colon (:), and password. The text must be encoded in Base64. For example, to send the username Aladdin and password open sesame, use the following HTTP header field:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The OpenPages GRC REST API adheres to the RESTful systems principle of statelessness, so each request made must provide the credentials of the user. Basic authentication is considered secure if it is used with some external secure system such as SSL. For the greatest security, ensure that clients send only unencrypted credentials and that requests are sent over HTTPS.

Client certificate authentication

OpenPages offers client certificate authentication with WebSphere Liberty Profile (WLP).

Client certificate authentication is a mutual certificate-based authentication method, where the client provides its client certificate to the server to prove its identity. The server allows requests only after it authenticates the client. The client must provide a public key certificate that identifies who the client is. For the client to be authenticated, the server must trust the certificate. WLP can be configured to trust any client certificate by adding it manually to their trust keystore. WLP can also trust the client certificate if another trusted certificate digitally signs the client certificate. For example, WLP can trust the client certificate if a well-known SSL Certificate Authority, such as DigiCert, issues a certificate that signs the client certificate for ibm.com® .

This traffic is over SSL (HTTPS), which ensures the security of the connection and encryption. Also, the control at the API level provides an option to configure your security model to allow only certain pre-approved clients to make requests to the REST API. To allow the IBM OpenPages GRC REST API to use client authentication rather than basic authentication, you must configure IBM WebSphere Liberty. For information about configuring an application in IBM WebSphere Liberty to use client certificate authentication, see How to Set up Liberty to Use Certificate-Based Authentication.

OpenPages integration with IBM WebSphere Liberty security requires configuration changes. For more information, see Integrating OpenPages with IBM WebSphere Liberty security.

Token authentication

Token authentication is configured by default through your OpenPages application server under IBM OpenPages for IBM Cloud Pak for Data. The token is a Microprofile JSON Web Token (MP-JWT) as described in Eclipse MicroProfile Interoperable JWT RBAC. The client sends an HTTP request Authorization header that starts with the text Bearer followed by a valid MP-JWT token such as Authorization: Bearer <Valid MP-JWT Token> .

To get a valid token, use one of the authentication APIs described in Generating an authorization token or API key on the server where OpenPages is installed.

The IBM OpenPages GRC REST API adheres to the RESTful systems principle of statelessness, so each request made must provide the credentials of the user. All communications under IBM OpenPages for IBM Cloud Pak for Data enforce SSL by default.

Configuring OAuth 2.0 authentication

OAuth 2.0 allows users to keep their usernames, passwords, and other information private when they share specific data with an application. You can configure OAuth2.0 authentication for IBM OpenPages REST API V1 and V2 on IBM OpenPages on premises or IBM OpenPages on Cloud.

In this configuration, OpenPages performs the role of resource server in OAuth 2.0 authentication flows. You can use an OAuth 2.0 authorization server or an OpenID Connect (OIDC) provider as the Identity Provider (IdP).

Before you begin

Your environment must meet the following criteria:

  • An OAuth 2.0 authorization server or OIDC provider is set up and running.
  • Register a client account to be used by the OpenPages server to perform introspection or validate identity. This account must be created in the OAuth 2.0 or OIDC provider. OpenPages uses the client ID and client secret for validation of tokens with the authorization server only.
  • Each external client that uses the OpenPages REST APIs must either be assigned a service account user ID in the OAuth 2.0 authorization server, or have a user identity in the OIDC Provider. The username of the service account or functional ID that is mapped to each client must match a user in the OpenPages system.
  • If needed, create a user in OpenPages with the username service-account and required permissions for the flow of client credentials to work correctly. The client_id comes from the OIDC provider.
  • OpenPages 9.0 or later is installed and the OpenPages servers are running.
  • You can log in to the OpenPages application from your browser.

About this task

In this task, you configure an IBM WebSphere Liberty server to act as an OpenID Connect Client. For more information, see OpenID Connect Client (openidConnectClient).

You can use any provider that supports OAuth 2.0 or OpenID Connect protocols.

Procedure

  1. Log on to the OpenPages application server.
  2. Install the IBM WebSphere Liberty openidConnectClient-1.0 and transportSecurity-1.0 features by running the following commands: 
    <WLP_HOME>/bin/installUtility install openidConnectClient-1.0
<WLP_HOME>/bin/installUtility install transportSecurity-1.0
  3. Go to the directory <WLP_USER_DIR>/servers/<server_name>Server<#>/configDropins/overrides.
    If the directory does not exist, create it.
  4. Create an .xml file. In the file, insert the following lines after you replace the OAuth2_OIDC_provider variables, such as <OAuth2_OIDC_provider_client_ID>, with the information from your OIDC provider. 
    <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>

    Make sure that the <authFilter> element does not contain <requestUrl> filters that conflict.

    Tip: To add more filters, create more <requestUrl> elements. Give each of them a unique id.
  5. Export the root and intermediate certificate authority certificates from your authorization server or OIDC provider.

    For more information, contact your provider.

  6. Import the root and intermediate certificate authority certificates to the OpenPages truststore.
    For example:
    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. Stop all OpenPages services.
  8. Restart all OpenPages services.

What to do next

To use the OAuth 2.0 protocol for IBM OpenPages GRC REST API public authentication, use JSON Web Token (JWT) Bearer Tokens that are issued by the Authorization Server or OpenID Provider.

Client/server interactions

Client interaction with the IBM OpenPages GRC REST API, including the sequence of events, depends on the design of the client and the interaction objectives. An interaction retrieves Metadata and Configuration information, and then it sends further requests to the server to gather more data or perform updates.

Figure 1. Interaction to create a new GRC Object of type LossEvent
This diagram shows the interaction to create a new GRC Object of type LossEvent.

Integrating OpenPages with IBM WebSphere Liberty security

OpenPages offers client certificate authentication with WebSphere Liberty Profile (WLP). To integrate OpenPages with Liberty security, you must change your server configuration.

Before you begin

  • You must have access to the OpenPages application server and permission to modify the server configuration.
  • You must have an x509 public key certificate that represents your client. This certificate requires a Subject that identifies the user in OpenPages that this client is authenticating as. 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. These usernames must exist as user accounts within OpenPages.

About this task

This task shows you how to configure a newly installed environment to allow client certificate authentication for the REST API. If you modified the Global Security configuration or GRC Security Domains (for instance for using SSO), you might need to adjust these steps for your environment.

Procedure

  1. Change directories to <WLP_HOME>/usr/servers/<OP_SERVER>/configDropins/overrides.

    If the overrides directory doesn't exist, create it.

  2. Create an .xml file that contains the following elements: 
    <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>
    • The <ssl> attribute clientAuthenticationSupported enables client certificate authentication.
    • The <keyStore> element must specify a valid truststore to use, such as defaultTrustStore, and the truststore password, such as defaultPWD, as attributes. The default keystore can be found in <WLP_HOME>/usr/servers/<OP_SERVER>/resources/security/key.p12.
    • If certificate authentication fails, the <webAppSecurity> attribute allowFailOverToBasicAuth allows the API to use basic authentication. For more information, see https://www.ibm.com/docs/en/was-liberty/base?topic=configuration-webappsecurity.
  3. Add the CA signer certificate to the truststore.
    For example,
    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. In the newly created .xml file, create an <openpagesUserRegistry/> element within the <server> element.
  5. Add attributes to the <openpagesUserRegistry/> element, depending on your client certificate subjects. These attributes are used by the OpenPages custom user registry to parse a username from the Subject entry in the client certificate.
    Example 1

    The following example is a simpler approach that looks for the first occurrence of the CN= within a subject.

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

    You can use regular expressions (regex) to give you more flexibility to handle different formats of Subjects in client certificates depending on your organization’s policies and practices. Using regex, you can specify more granular logic for parsing out a username from the larger Subject element of a certificate. The Subject element of a certificate can contain many parts. The following example uses a regular expression to parse a username when a Subject has the form "/C=US/O=IBM/OU=WFSS/CN=brianl".

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

    In regex, a group is a way to treat multiple characters as a single unit. They are created by placing the characters to be grouped inside a set of parentheses.

    A capturing group captures the text that is matched by the regex inside the parentheses into a numbered group. The numbered group can be reused with a numbered back reference. Use a capturing group to apply regex operators to the entire grouped regex.

    A non-capturing group is a way to group a set of characters or expressions in a regular expression without capturing the matched text. The syntax for a non-capturing group, a question mark and colon after the opening parenthesis, informs the regular expression engine not to store the matched text.

    In Example 2, the regex expression engine looks for a non-capturing group that matches occurrences of CN=. When a match is found, the text between the matching occurrence and the comma delimiter is captured. When Liberty interprets the Subject from the client certificate, the result is "CN=brianl, OU=WFSS, O=IBM, C=US".

    The regex expression matches with CN=brianl, and the username that is taken from the match is the capture group #1 identified by the regular expression as brianl.

    The following example of text from the Subject illustrates a different scenario, where the value of CN= is an email address instead of the username.

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

    The following regex matches the text between the CN= and the @ symbol to give you the username from the Subject.

    (?:CN=)([^@]+),?
  6. Stop the OpenPages application server.
  7. In the <login-config> section of the REST API application's web.xml file, change the <auth-method> element to specify the CLIENT-CERT authentication method rather than the BASIC authentication method. The file is in the directory <WLP_HOME>/usr/shared/apps/op-apps.ear/com.ibm.openpages.api.rest.war/WEB-INF.
    If the web_merged.xml file exists in the <WLP_HOME>/usr/shared/apps/op-apps.ear/com.ibm.openpages.api.rest.war/WEB-INF directory, make the same change to the web_merged.xml file.

    After you make the change, the <login-config> section of each file appears as follows:

    <login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>OpenPagesRealm</realm-name>
    </login-config>
  8. Restart the OpenPages application server.

What to do next

You can test how the client certificate authentication works by using a REST client that has support for this authentication method. For example, the UNIX-style cURL command supports this method.

For example, if the client certificate is in client1.pem and the server is my-op-server, use the following cURL command:

curl --tlsv1.2
        --no-alpn --verbose --cert /path-to-/client1.pem
        https://my-op-server:10111/opgrc/api/v2/types
This command returns the following results:
  • All output that is related to the SSL handshake because of the inclusion of the --verbose option.
  • A response body that contains the JSON that describes the OpenPages metadata schema because the request specifies that all types are to be returned.

If your server is not using a valid SSL certificate, you can add the --insecure option to the command for testing purposes. The --no-alpn option was introduced in cURL version 7.36.0. If your cURL version is earlier than 7.36.0, remove the --no-alpn option.

You can use this method to test other IBM OpenPages GRC REST API endpoints.

Mapping Regulatory Events to Mandates, Sub-Mandates, and Requirements

When you import Regulatory Events by using App Connect or the IBM OpenPages GRC REST API, you can map the ingested Regulatory Events to the Regulatory Library objects: Mandates, Sub-Mandates, and Requirements.

About this task

To make the association, use a IBM OpenPages GRC REST API call. The examples in this task illustrate the use case where you have one Regulatory Event that needs to be associated to an existing Mandate and Sub-Mandate.

Procedure

  1. Get the Resource ID of the Regulatory Event. 
    https://<server_name>:<port_number>/opgrc/api/v2/query?q=SELECT * FROM [RegulatoryEvent] WHERE [RCM-RegulatoryEvent:Amended Citation] LIKE '<value>'
    Request Type: GET
    For example, query on the RCM-RegulatoryEvent:Amended Citation field and look for a value of 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'

    The Resource ID returned from this query is 12593.

  2. Get the Resource ID of the Mandate to use for the association. 
    https://<server_name>:<port_number>/opgrc/api/v2/query?q=SELECT [Resource ID] FROM [Mandate] where [RCM-Mand:Citation] = '<value>'
    Request Type: GET
    For example, query on the RCM-Mand:Citation field and look for a value of 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'

    The Resource ID returned from this query is 9946.

  3. Get the Resource ID of the Sub-Mandate to use for the association. 
    https://<server_name>:<port_number>/opgrc/api/v2/query?q=SELECT [Resource ID] FROM [Submandate] where [RCM-SubMand:Citation] = '<value>'
    Request Type: GET
    For example, query on the RCM-SubMand:Citation field and look for a value of 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'

    The Resource ID returned from this query is 9981.

  4. Call the IBM OpenPages GRC REST API to associate the Regulatory Event to two parents, a Mandate and a Sub-Mandate, by using the Resource ID's retrieved in previous steps URL: 
    https://<server_name>:<port_number>/opgrc/api/v2/contents/<id>/associations/parents

    Request Type: POST

    Post Parameters in JSON Format: {"associations":[{"id": "<id_of_mandate>"}, {"id": "<id_of_sub-mandate>"}]}

    For example, 
     https://server1.ibm.com:10111/opgrc/api/v2/contents/12593/associations/parents

    Post Parameters in JSON Format: {"associations":[{"id": "9946"}, {"id": "9981"}]}