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

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

Before starting

Configure users, groups, and roles to be authorized to use the IBM MQ Console and REST API. For more information, see Configure users and roles.
When we use the REST API, we 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 user name, 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 user name of Fred.
- For an LDAP registry, by default the full distinguished name is matched against LDAP. We can set up filters and mapping 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 user name 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.

The procedure assumes the following information:

That the mqwebuser.xml file is based on one of the following samples:
- basic_registry.xml
- local_os_registry.xml
- ldap_registry.xml
That we are using a UNIX, Linux, or Windows system.
You are a privileged user.

To configure client certificate authentication with a RACF key ring on z/OS, follow the procedure in Configure 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

Start the mqweb server by entering the strmqweb command on the command line.
Create a client certificate:
1. Create a PKCS#12 keystore:
  1. Open the IBM Key Management tool by entering the strmqikm command on the command line.
  2. From the Key Database File menu in the IBM Key Management tool, click New.
  3. Select PKCS12 from the Key database type list.
  4. Select a location to save the keystore, and enter an appropriate name in the File Name field. For example, user.p12
  5. Set a password when prompted.
2. Create the certificate, either by creating a self-signed certificate, or by obtaining a certificate from a certificate authority:
  - Create a self-signed certificate:
    1. Click New Self-Signed.
    2. Enter user in the Key Label field.
    3. If we are using a basic user registry, enter the name of a user from your user registry in the Common Name field. For example, mqadmin. For an LDAP user registry, make sure that the distinguished name for the certificate matches the distinguished name in the LDAP registry.
    4. Click OK.
  - Obtain a certificate from a certificate authority. The CA certificate must include the appropriate user name within the common name (CN) of the distinguished name (DN) field:
    1. Request a new certificate. From the Create menu, click New Certificate Request.
    2. In the Key Label field, enter the certificate label.
    3. If we are using a basic user registry, in the Common Name field, enter the user name of the user that the certificate is for.
      
      If we are using a local OS registry, the Common Name field must match the local OS user id.
      
      For an LDAP user registry, make sure that the distinguished name for the certificate matches the distinguished name in the LDAP registry.
    4. Type or select values for the remaining fields, as applicable.
    5. Choose where to save the certificate request, and the filename for the certificate request, then click OK.
    6. Send the certificate request file to a certificate authority (CA).
    7. When you have the certificate from the CA, open the IBM Key Management tool by entering the strmqikm command on the command line.
    8. From the Key Database File menu in the IBM Key Management tool, click Open.
    9. Select the PKCS#12 keystore that holds the client certificate. For example, user.p12
    10. Click Receive, select the appropriate certificate, and click OK.
Extract the public part of the client certificate:
1. Open the IBM Key Management tool by entering the strmqikm command on the command line.
2. From the Key Database File menu in the IBM Key Management tool, click Open.
3. Select the PKCS#12 keystore that holds the client certificate. For example, user.p12
4. Select the client certificate from the certificate list in the IBM Key Management tool.
5. Click Extract Certificate.
6. Select a location to save the certificate, and enter an appropriate file name in the Certificate file name field. For example, user.arm.
Import the public part of the client certificate into the mqweb server trust keystore as a signer certificate so that the server can validate the client certificate:
1. Create a trust.jks keystore for use by the mqweb server, if one does not already exist:
  1. From the Key Database File menu in the IBM Key Management tool, click New.
  2. Select JKS from the Key database type list.
  3. Click Browse and navigate to: MQ_DATA_DIRECTORY/web/installations/installationName/servers/mqweb/resources/security.
    This directory should already contain a key.jks file. If a trust.jks file already exists then open the existing one rather than overwriting it.
  4. Enter trust.jks in the File Name field.
  5. Set a password when prompted.
2. From the drop-down menu, select Signer Certificates.
3. Click Add.
4. Select the appropriate arm file, and click OK. For example, select user.arm.
5. Enter a label for the certificate.
Change the password of the mqweb server keystore:
1. From the Key Database File menu, click Open.
2. Select JKS from the Key database type list.
3. Click Browse and navigate to MQ_DATA_PATH/web/installations/installationName/servers/mqweb/resources/security
4. Select the key.jks keystore, and click Open.
5. Enter the password when prompted. The default password is password.
6. From the Key Database File menu, click Change Password.
7. Enter a new password for the keystore.
Enable client certificate authentication in the mqwebuser.xml file:
The mqwebuser.xml file can be found on the following path: MQ_DATA_PATH/web/installations/installationName/servers/mqweb
1. 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"/>
```
2. Check that the serverKeyAlias value matches the name of the server certificate. If we are using the default server certificate, the value is correct.
3. Change the value for password for the defaultKeyStore to an encoded version of the password for the key.jks keystore:
  1. From the MQ_INSTALLATION_PATH/web/bin directory, enter the following command on the command line:
```
securityUtility encode password
```
  2. Place the output of this command in the password field for the defaultKeyStore.
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 on the command line:
```
securityUtility encode password
```
  2. Place the output of this command in the password field for the defaultTrustStore.
5. Remove, or comment out, the following line from the mqwebuser.xml file:
```
<sslDefault sslRef="mqDefaultSSLConfig"/>
```
Stop the mqweb server by entering the endmqweb command on the command line.
Start the mqweb server by entering the strmqweb command on the command line.
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. For example, install the client certificate user.p12 as a personal certificate.
- To use the client certificate with the REST API, provide the client certificate with each REST request. When we use HTTP POST, PATCH, or DELETE methods, we 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 we must use a cURL implementation that does.

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

Use the HTTP POST method with the queue 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/v1/admin/qmgr/QM1/queue -X POST -
-cert-type P12 --cert c:\user.p12:password 
-H "ibm-mq-rest-csrf-token: value" 
-H "Content-Type: application/json" --data "{\"name\":\"Q1\"}"
```

Parent topic: IBM MQ Console and REST API security