On z/OS®, you can configure the mqweb server to use
a RACF® key ring to store certificates for secure connections with TLS,
and client certificate authentication.
Before you begin
You must be a user that has write access to the mqwebuser.xml file, and authority to
work with SAF key rings, to complete this procedure.
About this task
The default mqweb server configuration uses Java
keystores for the server and trusted certificates. On z/OS,
you can configure the mqweb server to use a RACF key ring,
instead of the Java keystores. The server can also be
configured to allow users to authenticate using a client certificate.
See Liberty: Keystores for information on using RACF
key rings in Liberty.
Follow this procedure to configure the mqweb server to use a RACF
key ring, and optionally configure client certificate authentication.
Procedure
-
Create a certificate authority (CA) certificate, which will be used to sign the server certificate.
For example, enter the following RACF command:
RACDCERT GENCERT
CERTAUTH
SUBJECTSDN(CN('mqweb Certification Authority')
O('IBM')
OU('MQ'))
SIZE(2048)
WITHLABEL('mqwebCertauth')
-
Create a server certificate, signed with the CA certificate created in step 1, by entering the
following command:
RACDCERT ID(mqwebUserId) GENCERT
SUBJECTSDN(CN('hostname')
O('IBM')
OU('MQ'))
SIZE(2048)
SIGNWITH (CERTAUTH LABEL('mqwebCertauth'))
WITHLABEL('mqwebServerCert')
where
mqwebUserId is the mqweb server started task user ID, and
hostname is the host name of the mqweb server.
-
Connect the CA certificate and server certificate to a SAF key ring by entering the following commands:
RACDCERT ID(mqwebUserId) CONNECT(RING(keyring) LABEL('mqwebCertauth') CERTAUTH)
RACDCERT ID(mqwebUserId) CONNECT(RING(keyring) LABEL('mqwebServerCert'))
where
mqwebUserId is the mqweb server started task user ID, and
keyring is
the name of the key ring you want to use.
-
Export the CA certificate to a CER file by entering the following command:
RACDCERT CERTAUTH EXPORT(LABEL('mqwebCertauth'))
DSN('hlq.CERT.MQWEBCA')
FORMAT(CERTDER)
PASSWORD('password')
-
FTP the exported CA certificate in binary to your workstation, and import it into your browser as a certificate
authority certificate.
- Optional:
If you want to configure client certificate authentication, create and export a client certificate.
-
Create a certificate authority (CA) certificate, which will be used to sign the client certificate.
For example, enter the following RACF command:
RACDCERT GENCERT
CERTAUTH
SUBJECTSDN(CN('mqweb User CA')
O('IBM')
OU('MQ'))
SIZE(2048)
WITHLABEL('mqwebUserCertauth')
-
Connect the CA certificate to a SAF key ring by entering the following command:
RACDCERT ID(mqwebUserId) CONNECT(RING(keyring) LABEL('mqwebUserCertauth') CERTAUTH)
where
mqwebUserId is the mqweb server started task user ID, and
keyring is the name of the key ring you want to use.
-
Create a client certificate, signed with the CA certificate. For example, enter the following command:
RACDCERT ID(clientUserId) GENCERT
SUBJECTSDN(CN('clientUserId')
O('IBM')
OU('MQ'))
SIZE(2048)
SIGNWITH (CERTAUTH LABEL('mqwebUserCertauth'))
WITHLABEL('userCertLabel')
where
clientUserId is the user name.
The method used to map a certificate to a
principal depends on the type of user registry configured:
- If you are using a basic registry, the Common Name field in the certificate is matched against
the user in the registry.
- If you are using a SAF registry, and the certificate is in the RACF database, the certificate owner, specified with the
ID parameter when creating the certificate, is used.
- If you are using an LDAP registry, the full distinguished name in the certificate is matched
against the LDAP registry.
-
Export the client certificate to a PKCS #12 file by entering the following command:
RACDCERT ID(mqwebUserId) EXPORT(LABEL('userCertLabel')) PASSWORD('password') DSN('hlq.USER.CERT')
-
FTP the exported certificate in binary to your workstation. To use the client certificate with the
IBM® MQ Console, import it into the web browser used to access the
IBM MQ Console as a personal certificate.
-
Edit the file WLP_user_directory/servers/mqweb/mqwebuser.xml,
where WLP_user_directory is the directory that was specified when the crtmqweb
script ran to create the mqweb server definition.
Make the following changes to configure the mqweb server to use a RACF
key ring:
-
Remove, or comment out, the following line:
<sslDefault sslRef="mqDefaultSSLConfig"/>
-
Add the following statements:
<keyStore id="defaultKeyStore" filebased="false" location="safkeyring://mqwebUserId/keyring"
password="password" readOnly="true" type="JCERACFKS" />
<ssl id="thisSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="TLSv1.2"
serverKeyAlias="mqwebServerCert" clientAuthenticationSupported="true" />
<sslDefault sslRef="thisSSLConfig"/>
where:
- mqwebUserId is the mqweb server started task user ID.
- keyring is the name of the RACF key ring.
- mqwebServerCert is the label of the mqweb server certificate.
Notes:
The value of keyStore password is ignored.
-
Restart the mqweb server by stopping and restarting the mqweb server started task.
- Optional:
Use the client certificate to authenticate:
- To use the client certificate with the IBM MQ Console, enter the URL for the MQ Console in the web browser
where you installed the client certificate.
- To use the client certificate with the REST API, provide the client certificate with each REST
request.
Notes:
- If you are using only certificates to authenticate to the IBM MQ Console, the browser might display a list of certificates
for you to select from.
- If you want to use a different certificate you might need to close and restart your
browser.
- If you are using client certificates that are not in the RACF database, you can use RACF certificate name filtering, to map certificate
attributes to a user ID. For example:
RACDCERT ID(DEPT3USR) MAP SDNFILTER(OU=DEPT1.C=US)
maps certificates with a
subject distinguished name containing OU=DEPT1
and C=US
to user ID
DEPT3USR
.
Results
You have set up a TLS interface for the IBM MQ Console
and REST API.