Defining SSH authentication for CLI sessions by using the CLI

You can define how users are authenticated when using SSH for CLI sessions by using the CLI.

About this task

You define which users can use an SSH connection to the appliance CLI by using role-based management (see Role based management). You can further control the methods that such users need to use to authenticate themselves to the CLI.

The following methods are available:

No method selected

The user is prompted for both the user name and password. For example:

ssh hostname

login: username
Password: ******

Password

If you specify the Password method, the user specifies their user name as part of invoking SSH. They are then prompted for their password. For example:

ssh user@hostname
Password: ******

Certificate

If you specify the certificate method, then the user is not prompted for any input and authentication uses a CA-signed user certificate.

If RBM is configured to authenticate users with an LDAP server then the distinguished name of the user is determined by using either a fixed prefix and suffix, or by using an LDAP search, as for password authentication. However, an LDAP bind is not performed to authenticate the user with the LDAP server because the user is authenticated by using their SSH certificate instead. The LDAP distinguished name is used as the authenticated identity when performing authorisation checks for consistency with password authentication.

The connection is successful when the invocation provides a signed SSH user certificate that is verified by the CA public key file in the cert: directory on the appliance. With the ssh command, the invocation must include the -i file parameter. For example:

ssh -i my_key user@hostname

Important: You should save the public key for each user certificate when it is issued by the CA. The user's public key must be provided to the appliance if their CA-signed user certificate needs to be revoked (see Managing the SSH revoked keys list for authenticating CLI sessions for web UI or ssh-revoked-keys for CLI.)

You can specify both the Password and certificate methods at the same time. If authentication using the certificate method fails, then the user is prompted for a password.

When you specify the certificate method, you must create certificates and keys on a client machine using the OpenSSH ssh-keygen command, and upload the CA public key used to sign the user certificates to the appliance. You must then identify that key on the appliance by using the ssh-ca-pubkey-file command.

Note: From 9.3.4, the appliance supports SSH certificates that have either an RSA SHA1 or SHA2 signature. Before 9.3.4, the appliance only supported RSA SHA1 signatures. To generate a SHA2 signature using OpenSSH version 8 or later, specify the -t rsa-sha2-256 or -t rsa-sha2-512 argument to the ssh-keygen commands. To generate a SHA1 signature using OpenSSH version 8 or later, specify -t ssh-rsa. To generate a SHA1 signature using OpenSSH version 7 or earlier, specify -t rsa.

• To use the certificate authentication method, first create a CA key for signing SSH user certificates:

  Create the public key for signing certificates using openSSH on a client machine, for example:

  ssh-keygen -t type -b 4096 -f mqa-ssh-user-ca -C mqa-ssh-user-ca

  Where, for an RSA SHA2 signature, type is either rsa-sha2-256 or rsa-sha2-512 using OpenSSH 8 or later, and, for an RSA SHA1 signature, type is rsa using OpenSSH 7 or ssh-rsa using OpenSSH 8 or later.

• To specify the authentication method for SSH users:
  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. For certificate authentication, upload the public key for the CA certificates to the cert: file system.

     mqa(config)# dir cert:
     
     File Name                    Last Modified                    Size
     ---------                    -------------                    ----
     mqa-ssh-user-ca.pub          Aug 18, 2022 4:20:03 PM          736
     

  4. Type the following command to configure role based management:

     rbm

  5. For certificate authentication, configure the CA certificate for validating SSH user certificates.

     ssh-ca-pubkey-file cert:///mqa-ssh-user-ca.pub

  6. Configure the SSH authentication method:

     ssh-au-method parameter

     Where parameter is one of the following values:

     certificate

     Authenticates users by using a signed SSH user certificate.

     certificate+password

     Authenticates users first by using a signed SSH user certificate. If unsuccessful, prompts for the account password.

     password

     Authenticates users by prompting for the account password.

     To configure the default authentication method instead, you unset ssh-au-method by using:

     no ssh-au-method

  7. Save the changes to the RBM settings by using the command:

     exit

  8. Persist the configuration changes by using the command:

     write memory

• For certificate authentication, complete the following steps for each user.
  1. Create an unsigned SSH key for the specified user. In this example a key is created for the user admin:

     ssh-keygen -t type -b 4096 -f admin-key -C admin

     Where, for an RSA SHA2 signature, type is either rsa-sha2-256 or rsa-sha2-512 using OpenSSH 8 or later, and, for an RSA SHA1 signature, type is rsa using OpenSSH 7 or ssh-rsa using OpenSSH 8 or later.

  2. Issue a CA-signed SSH certificate for that user (you can additionally specify the -V parameter to set a validity period, if required).
     If you are using OpenSSH 7, then an RSA SHA1 certificate is issued for the user admin, signed by the key you uploaded to the appliance, for example:

     ssh-keygen -s mqa-ssh-user-ca -I admin -n admin admin-key.pub

     If you are using OpenSSH 8 or later, then the -t argument is used to specify the certificate type.

     For 9.3.3 and earlier (which only supports SHA 1), you must create an RSA SHA1 certificate by using the -t ssh-rsa argument, for example:

     ssh-keygen -t ssh-rsa -s mqa-ssh-user-ca -I admin -n admin admin-key.pub

     For 9.3.4 onwards (which supports SHA1 and SHA 2), specify a type of ssh-rsa for RSA SHA1 and either rsa-sha2-256 or rsa-sha2-512 for RSA SHA2, for example:

     ssh-keygen -t rsa-sha2-512 -s mqa-ssh-user-ca -I admin -n admin admin-key.pub

  3. Confirm the certificate properties, for example:

     ssh-keygen -L -f admin-key-cert.pub
     
     admin-key-cert.pub:
             Type: ssh-rsa-cert-v01@openssh.com user certificate
             Public key: RSA-CERT SHA256:mMQUALHY3b7GaffRU8D6/5spidqWaKarjSYhPNSXvFE
             Signing CA: RSA SHA256:uoD2k6OMf7+0okmzynf3P2XqE3/8osTt4HnloxpguG4
             Key ID: "admin"
             Serial: 0
             Valid: forever
             Principals:
                     admin
             Critical Options: (none)
             Extensions:
                     permit-X11-forwarding
                     permit-agent-forwarding
                     permit-port-forwarding
                     permit-pty
                     permit-user-rc
     

     If you are using OpenSSH 8 or later, then, for an RSA SHA1 certificate, ensure that the Signing CA line includes the string (using ssh-rsa), for example:

     Signing CA: RSA SHA256:uoD2k6OMf7+0okmzynf3P2XqE3/8osTt4HnloxpguG4 (using ssh-rsa)

     For an RSA SHA2 certificate, ensure that the Signing CA line includes the string (using rsa-sha2-256) or (using rsa-sha2-512) instead.

  4. Copy the user's private key (for example, admin-key), public key (for example, admin-key.pub) and signed certificate (for example, admin-key-cert.pub) to a directory on the SSH client.
  5. Log in to the appliance from your client as the user by specifying the path to their private key (the certificate is used if it is in the same directory). For example:

     ssh -i path/admin-key admin@hostname