Configuring user authentication with a TLS user certificate by using the command line

Configure the appliance to authenticate the users by using a TLS user certificate.

1. Connect to the IBM® MQ Appliance as described in Command line access. Log in as an administrative user.
2. Type config to enter global configuration mode.
3. Type the following command to configure role based management:

   rbm

4. Enter the following command to specify the TLS certificate authentication method:

   au-method client-ssl

5. Specify the validation credentials that you have previously defined for this purpose:

   au-valcred <credname>

6. If required, specify that the common name part of the user's distinguished name is used as the user id for authentication:

   au-ssl-user-attribute cn

   By default, the authenticated principal for a TLS user certificate is the distinguished name (DN) of the certificate subject in X.509 format, converted to lower case, and with any embedded whitespace removed. For example, the TLS certificate subject C=GB, ST=Hursley, L=Hursley, O=IBM, OU=MQ Appliance, CN=Jo Jo becomes the authenticated principal c=gb,st=hursley,l=hursley,o=ibm,ou=mqappliance,cn=jojo. You can, however, specify that the common name portion of the full name is used, so, in the example, jojo is the user id. The user id is displayed in the title bar of the Web UI.
7. If required, use the au-user-map command to specify username mapping so that user names as specified in the TLS certificates are mapped onto usernames in a format that can be used by IBM MQ. See Using an alternative user name (TLS certificate).
8. Optionally specify fallback users who can log in to the appliance if the certificate is not available. Fallback users must already have been added as local users to the appliance. You can specify that all local users are fallback users by entering the following command:

   fallback-login local

   Alternatively, you can specify one or more particular users by entering the following commands:

   fallback-login restricted
   fallback-user localuser1
   fallback-user localuser2
   ...
   fallback-user localuserN
   

9. Alter the default cache settings, if required. By default, the appliance caches results of authentication attempts for 600 seconds, but you can change the mode of caching, and the caching duration by entering the following commands:

   au-cache-mode mode
   au-cache-ttl seconds

   Where mode is one of:

   absolute

   Caches the results of user authentications for a period of time specified by the au-cache-ttl command (the explicit time-to-live). This is the default setting.

   disabled

   Disables caching. The appliance will not cache any results and instead always authenticates every time a user requests access.

   maximum

   Compares the explicit TTL to the TTL contained in the response (if any) and cache authentication results for the maximum of the two values.

   minimum

   Compares the explicit TTL to the TTL contained in the response (if any) and cache authentication results for the minimum of the two values.

10. Click Apply to apply your changes.

mqa# config
Global configuration mode
mqa(config)# rbm
Modify RBM Settings configuration

mqa(config rbm)# au-method client-ssl
mqa(config rbm)# au-valcred mycredname
mqa(config rbm)# au-ssl-user-attribute cn
mqa(config rbm)# fallback-login local
mqa(config rbm)# exit
mqa(config)# write memory
Overwrite previously saved configuration? Yes/No [y/n]: y
Configuration saved successfully.