REST API Client Certificate Authentication method
Brian Laskey 270003US2W Visits (10432)
The authentication method out of the box for GRC
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.
Note: These steps will guide you from taking a newly installed 126.96.36.199 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 > Node
3. Import the client certificate's CA signer certificate (see prerequisites) or the client certificate itself into the trust store set in Node
4. Optional: Global Security > Authentication > Web and SIP security > General Settings
5. Find Security > Security Domains > GRC Security Domain > User Realm > Standalone custom registry > Configure
-or- for more complex regular expression (example):
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.
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_
for both web.xml AND web_merged.xml (if present)
10. Repeat changes for web.xml AND web_merged.xml (if present) in
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 /pat
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: http
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=
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=
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.