The authentication method out of the box for GRC REST API is Basic authentication. Sometimes we receive inquiries about having a more secure method to authenticate requests to our APIs. The good news is that now, starting with IBM OpenPages GRC v8.0.0.1, we offer at least one other authentication method for the API: Client Certificate Authentication.

 

Client Certificate authentication is a method where the server only allows requests after authenticating the client which must provide a public key certficate that identifies who the client is, and that must be trusted by the server (or signed by a trusted certificate) client authentication. This traffic is over over SSL (HTTPS) which insures the security of the connection and encryption. Having control at the API level of what client certificates you trust also provides an option to configure your security model to only allow certain pre-approved clients to make requests to the REST API. In order for the OpenPages GRC REST API to use client authentication instead of Basic authentication you must do some additional configuration in WebSphere.

 

For the official IBM Websphere documentation around configuring client authentication see Secure Sockets Layer client certificate authentication which will go into the general steps for configuring any application in WebSphere to use this method. For OpenPages our particular integration with WebSphere security requires some additional configuration changes.

 

Prerequisites

• OpenPages v8.0.0.1 or higher
• A x509 public key certificate that represents your client. This certificate will need a Subject which in some way identifies the user in OpenPages this client is authenticating as. For example a subject may be "/CN=OpenPagesAdministrator" for a user 'OpenPagesAdministrator' or "/C=US/O=IBM/OU=WFSS/CN=brianl" for another user with name 'brianl'. These user names must exist as user accounts within OpenPages before you begin. Note creating a valid certificate yourself is beyond the scope of this blog. But you can read about how to do it using open source tools for example here http://veewee.github.io/blog/authenticating-with-x509-client-certificates/
• Access to the OpenPages application server, permission to modify the server configuration, and access to the WAS admin console web interface.

 

Setup Steps

Note: These steps will guide you from taking a newly installed 8.0.0.1 environment and configuring it to allow Client Certificate authentication for the REST API. If you've already modified the Global Security configuration or GRC Security Domains (for instance for using SSO), you may need to adjust these steps for your environment.

1. Login to WebSphere admin console as the admin user

2. Find Global Security > SSL Configuration > NodeDefaultSSLSettings > QoP and Update Client certificates: Supported

3. Import the client certificate's CA signer certificate (see prerequisites) or the client certificate itself into the trust store set in NodeDefaultSSLSettings e.g. CellDefaultTrustStore

Example:

1. Copy root cert .pem file to application server file system
2. In CellDefaultTrustStore, Signer Certificates, click Add
3. Choose any alias, “my-root-ca”
4. File, “<path to .pem file on app server>”
5. Click OK and Save

4. Optional: Global Security > Authentication > Web and SIP security > General Settings
If you want continue to allow Basic authentication if client certificate not provided, then check: Default to basic authentication when certificate authentication for the HTTPS client fails

5. Find Security > Security Domains > GRC Security Domain > User Realm > Standalone custom registry > Configure
Add new Custom Properties and enter the following depending on your client certificate subjects.

• com.ibm.openpages.security.entry.user.key   CN
• com.ibm.openpages.security.entry.user.delimiter   ,
• com.ibm.openpages.security.cert.regex   true

-or- for more complex regular expression (example):

• com.ibm.openpages.security.entry.user.regex (?:CN=)([^,]+),?
• com.ibm.openpages.security.cert.regex   true

These properties inform the OpenPages custom user registry how to parse a username from the Subject entry in the client certificate. The first option is a simpler approach that looks for the first occurrence of the CN= within a subject. The second approach uses a regular expression to parse a username from the Subject with additional rules.

6. Optional: If you required to use a regular expression in step 5. Then additionally you must find Security > Security Domains > GRC Security Domain > JAAS System Logins > System Logings > WEB_INBOUND > com.ibm.openpages.security.server.jaas.OpenPagesCredentialModule and Add a Custom Property with the same regular expression.

com.ibm.openpages.security.client.name.regex (?:CN=)([^,]+),?

7. Save and Apply all configuration changes.

8. Stop All OpenPages application server nodes and the dmgr

9. Next, modify REST API application's web.xml files for each server: Found under the path <OP_HOME>/profiles/OpenPagesDmgr/config/cells/OpenPagesCell/applications/op-apps.ear/deployments/op-apps/com.ibm.openpages.api.rest.war/WEB-INF

for both web.xml AND web_merged.xml (if present)

Change:

     <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>OpenPagesRealm</realm-name>
    </login-config>

To:

    <login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>OpenPagesRealm</realm-name>
    </login-config>

10. Repeat changes for web.xml AND web_merged.xml (if present) in
<OP_HOME>/profiles/<server-OPNode>/installedApps/OpenPagesCell/op-apps.ear/com.ibm.openpages.api.rest.war/WEB-INF

11. Next Start only Dmgr, And run WebSphere's syncNodes on all application servers to synchronize the WebSphere security configuration across all nodes.

12. Now you may restart all OpenPages application servers

 

Testing Client Certificate Authentication

You can test 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.

Example supposing my client certificate is in a clien1.pem:

curl --tlsv1.2 --no-alpn --verbose --cert /path-to-/client1.pem https://my-op-server:10111/grc/api/types

This should be expected to return some results that include a lot of output related to the SSL handshake (thanks to --verbose), and the end result should be a response body containing JSON describing the OpenPages metadata schema (since we are requesting everything from /grc/api/types ). You can play around using other API end-points. Note, if your server is not using a valid SSL certificate then you can add the  --insecure  parameter to the command for testing purposes.

You can test this with other REST clients as well. For example one popular client is PostMan which also supports client certificates through additional configuration: https://www.getpostman.com/docs/v6/postman/sending_api_requests/certificates

 

Regular Expressions

The usage of regular expressions allows you to perform more granular logic for parsing out a username from the larger Subject element of a certificate which can contain many parts. The example above shows how we might extract a username from a case where a Subject has the form of "/C=US/O=IBM/OU=WFSS/CN=brianl".

Regex: (?:CN=)([^,]+),?

Essentially what this does is first is a non-capturing group that matches occurences of "CN=" and capture the text after that until the delimiter of ",". This is because when WebSphere interprets the Subject from the client certificate the format the Subject is represented as will look like: "CN=brianl, OU=WFSS, O=IBM, C=US"

The Regex will match with "CN=brianl", and the username we take from the match will be the capture group #1 identified by the regular expression as "brianl" in this case.

 

Another example is what if the CN= was not a simple username but an email address and I needed to map to an OpenPages username?

Then the text we get from the Subject may be: Text "CN=brianl@us.ibm.com, OU=WFSS, O=IBM, C=US"

The Regex could be: (?:CN=)([^@]+),?

Again this matches the username from the CN= until the @ symbol, whch parses just the part we want from Subject.

This gives you more flexibility to handle different formats of Subjects in client certificates depending on your organizations policies and practices.

Tags:  grc websphere v8 security api