Configuring client certificate authentication with the REST API and IBM MQ Console

You can map client certificates to principals to authenticate IBM® MQ Console and REST API users.

Before you begin

Configure users, groups, and roles to be authorized to use the IBM MQ Console and REST API. For more information, see Configuring users and roles.
When you use the REST API, you can query the credentials of the current user by using the HTTP GET method on the login resource, providing the client certificate to authenticate the request. This request returns information about the username, and the roles that the user is assigned. For more information, see GET /login.
When you map client certificates to principals to authenticate users, the distinguished name of the client certificate is used to match against users in the configured user registry:
- For a basic registry, the Common Name (CN) is matched against the user. For example, CN=Fred, O=IBM, C=GB is matched against a username of Fred.
- For an LDAP registry, by default the full distinguished name is matched against LDAP. You can set up filters and mappings to customize the matching. For more information, see Liberty:LDAP certificate map mode in the WebSphere® Liberty documentation.

About this task

When a user authenticates by using a client certificate, the certificate is used in place of a username and password. For the REST API, the client certificate is provided with each REST request to authenticate the user. For the IBM MQ Console, when a user logs in with a certificate, the user cannot then be logged out.

On AIX®, Linux®, or Windows systems, the procedure assumes the following information:

That your mqwebuser.xml file is based on either the basic_registry.xml, local_os_registry.xml, or ldap_registry.xml sample XML files.
That you are a privileged user.

[z/OS] To configure client certificate authentication with a RACF® key ring on z/OS® systems, follow the procedure in Configuring TLS for the REST API and IBM MQ Console on z/OS.

Note: The following procedure outlines the steps necessary to use client certificates with the IBM MQ Console and REST API. For developer convenience, the steps detail how to create and use self-signed certificates. However, for production, use certificates that are obtained from a certificate authority.

Procedure

Create a certificate by using the runmqktool command:
```
runmqktool -genkeypair -keystore filename -storepass password -storetype PKCS12
           -alias label -dname distinguished_name 
           -sigalg signature_algorithm
```
filename

Specifies the keystore name, for example user.p12. If the keystore does not exist, it is created when the command runs.

password

Specifies the keystore password.

label

Specifies the certificate label. For example, user1.

distinguished_name

Specifies the X.500 Distinguished Name for the certificate. Enclose the Distinguished Name in double quotation marks.

If you are using a basic user registry, enter the name of a user from your user registry in the Common Name (CN) part of the Distinguished Name. For example, for a user mqadmin, use the Distinguished Name "CN=mqadmin".

If you are using a local OS registry, enter the name of a local OS user ID in the Common Name (CN) part of the Distinguished Name. For example, for a user mqadmin, use the Distinguished Name "CN=mqadmin".

If you are using an LDAP user registry, enter a Distinguished Name that matches the Distinguished Name in the LDAP registry.

signature_algorithm

Specifies the algorithm to use to sign the certificate. For more information, see Signature algorithms
Optional: Obtain a certificate from a certificate authority (CA). Alternatively, to use a self-signed certificate, continue to step 3.
1. To obtain a certificate from a certificate authority, create a certificate request by using the runmqktool command:
```
runmqktool -certreq -keystore filename -storepass password -alias label
           -file filename
```
  filename
  
  Specifies the keystore name from step 1.
  
  password
  
  Specifies the keystore password.
  
  label
  
  Specifies the certificate label from step 1.
  
  filename
  
  Specifies the fully qualified file name for the certificate request.
2. Send the certificate request file to a certificate authority (CA).
3. When you have the certificate from the CA, import the certificate into your keystore by using the runmqktool command:
```
runmqktool -importcert -keystore filename -storepass password
           -alias label -file filename
```
  filename
  
  Specifies the keystore name from step 1.
  
  password
  
  Specifies the keystore password.
  
  label
  
  Specifies the certificate label from step 1.
  
  filename
  
  Specifies the fully qualified file name of the CA certificate.
Extract the public part of the certificate by using the runmqktool command:
```
runmqktool -exportcert -keystore filename -storepass password
           -alias label -file filename -rfc
```
filename

Specifies the keystore name from step 1.

password

Specifies the keystore password.

label

Specifies the certificate label from step 1.

filename

Specifies the fully qualified file name for the extracted certificate.
Import the public part of the certificate into the mqweb server trust keystore as a signer certificate so that the server can validate the client certificate by using the runmqktool command:
```
runmqktool -importcert -keystore  MQ_DATA_DIRECTORY/web/installations/installationName/servers/mqweb/resources/security/trust.jks -storepass password
           -alias label -file filename
```
password

Specifies the trust.jks keystore password. You can specify either a password for an existing trust.jks keystore, or a new password for a new trust.jks keystore.

label

Specifies the certificate label from step 1.

filename

Specifies the fully qualified file name of the extracted certificate.
Configure the mqweb server to use client certificate authentication:
1. Open the mqwebuser.xml file.
  
  The mqwebuser.xml file can be found on the following path: MQ_DATA_PATH/web/installations/installationName/servers/mqweb
2. Turn off the default security configuration by commenting out the following line:
```
<sslDefault sslRef="mqDefaultSSLConfig"/>
```
  If you configured the mqweb server to present a CA certificate to the browser, this line is already commented out.
3. Uncomment the section in the mqwebuser.xml file that enables client certificate authentication. The section contains the following text:
```
<keyStore id="defaultKeyStore" location="key.jks" type="JKS" password="password"/>
    <keyStore id="defaultTrustStore" location="trust.jks" type="JKS" password="password"/>
    <ssl id="thisSSLConfig" clientAuthenticationSupported="true" keyStoreRef="defaultKeyStore" 
           trustStoreRef="defaultTrustStore" sslProtocol="TLSv1.2" serverKeyAlias="default"/>
    <sslDefault sslRef="thisSSLConfig"/>
```
  If you configured the mqweb server to present a CA certificate to the browser, this section is already uncommented. However, you might need to uncomment the defaultTrustStore line.
4. Change the value for password for the defaultTrustStore to match the password for the trust.jks keystore:
  1. From the MQ_INSTALLATION_PATH/web/bin directory, enter the following command:
```
securityUtility encode password
```
  2. Place the output of this command in the password field for the defaultTrustStore.
Stop the mqweb server by using the endmqweb command.
Start the mqweb server by using the strmqweb command.
Use the client certificate to authenticate:
- To use the client certificate with the IBM MQ Console, install the client certificate into the web browser that is used to access the IBM MQ Console.
- To use the client certificate with the REST API, provide the client certificate with each REST request. When you use HTTP POST, PATCH, or DELETE methods, you must provide extra authentication with the client certificate to prevent cross-site request forgery attacks. That is, the extra authentication is used to confirm that the credentials that are being used to authenticate the request are being used by the owner of the credentials.
  This extra authentication is provided by the ibm-mq-rest-csrf-token HTTP header. Set the value of the ibm-mq-csrf-token header to anything, including blank, then submit the request.

Example

Important: In the example, not all cURL implementations support self-signed certificates, so you must use a cURL implementation that does.

The following cURL example shows how to create a new queue Q1, on a queue manager QM1, with client certificate authentication. The exact configuration of this cURL command depends on the libraries that cURL was built with. The example is based on a Windows system with cURL built against OpenSSL.

Use the HTTP POST method with the mqsc resource, authenticating with the client certificate and including the ibm-mq-rest-csrf-token HTTP header with an arbitrary value. This value can be anything, including blank. The --cert-type flag specifies that the certificate is a PKCS#12 certificate. The --cert flag specifies the location of the certificate, followed by a colon, and then the password for the certificate:
```
curl -k https://localhost:9443/ibmmq/rest/v3/admin/admin/action/qmgr/QM1/mqsc -X POST -
-cert-type P12 --cert c:\user.p12:password 
-H "ibm-mq-rest-csrf-token: value" 
-H "Content-Type: application/json" 
--data "{\"type\": \"runCommandJSON\", \"command\": \"define\", \"qualifier\": \"qlocal\", \"name\": \"Q1\"}"
```