Setting up client certificate authentication for Teracloud® Streams users

Use this procedure to set up client certificate authentication for a Teracloud® Streams domain by using X.509 certificates. Using client certificate authentication is optional.

Before you begin

In the following procedure, the openssl command is used to work with certificates. This command is included in the openssl package. To download this package, go to the OpenSSL website.

About this task

After you set up client certificate authentication, Teracloud® Streams attempts to use X.509 certificate authentication when it authenticates a user to the domain. If certificate authentication fails, Teracloud® Streams uses the default authentication method for the domain, which is either LDAP or PAM.

Procedure

  1. Obtain X.509 certificates.

    You can use certificates that are signed by a certificate authority (CA) or self-signed certificates. Teracloud® Streams supports certificates in Distinguished Encoding Rules (DER) format or Privacy Enhanced Mail (PEM) format.

    • If you are using certificates that are signed by a CA, complete the following steps:
      1. Obtain the following files from the CA:
        • Client certificate
        • CA certificate for the CA that issued the client certificate
        • Certificate Revocation List (CRL) of the CA that issued the client certificate

        The process for requesting certificates depends on the issuing CA. Typically, you create a private key file and then create a certificate signing request (CSR) file that you send to the CA to sign. For more information, contact your CA.

        If you receive a certificate in PEM format, remove any text that is outside of the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers. You can manually remove the text with an editor of your choice. This update ensures that only the base64 encoded data remains. The following example shows a client certificate that contains the correct text: 

        -----BEGIN CERTIFICATE-----
MIID+jCCA2OgAwIBAgICEA8wDQYJKoZIhvcNAQEFBQAwcTELMAkGA1UEBhMCVVMx
CzAJBgNVBAgTAk1OMQwwCgYDVQQKEwNJQk0xEDAOBgNVBAsTB1N0cmVhbXMxEzAR
Y29tMB4XDTE1MTAxNDE1NDkyN1oXDTE2MTAxMzE1NDkyN1owdzELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAk1OMQwwCgYDVQQKEwNJQk0xEDAOBgNVBAsTB1N0cmVhbXMx
FDASBgNVBAMTC3N0cmVhbXN1c2VyMSUwIwYJKoZIhvcNAQkBFhZzdHJlYW1zdXNl
ckB1cy5pYm0uY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCjaQlq1M5d
YQP6puRLOTqmZdKFFngpuFnoIF6I7uwMJ8jNZx0Y9rkxVTGCqvmxnwvADG0GV5UR
ilXFhTYJINo1ggo+Ohm819k7YVAESv34kryj+1f86yj00Tzq6ykefYMre7t8PIZo
QW8QvjLZEdbjZnMgXyOGHWz1rAt+0376XwIDAQABo4IBmTCCAZUwKQYJYIZIAYb4
QgENBBwWGk9wZW5TU0wgQ2xpZW50IENlcnRpZmljYXRlMEAGCCsGAQUFBwEBBDQw
MjAwBggrBgEFBQcwAYYkaHR0cDovL3Nob2UucmNoLnN0Z2xhYnMuaWJtLmNvbTo5
MDgwMIGWBgNVHSMEgY4wgYuAFBQ8NrJJ9ddVW4Z/LvDbtUvsC51UoXCkbjBsMQsw
CQYDVQQGEwJVUzELMAkGA1UECBMCTU4xEjAQBgNVBAcTCVJvY2hlc3RlcjEMMAoG
A1UEChMDSUJNMQwwCgYDVQQDEwNJQk0xIDAeBgkqhkiG9w0BCQEWEXNtc2hhb0B1
cy5pYm0uY29tggFYMAkGA1UdEwQCMAAwPgYDVR0fBDcwNTAzoDGgL4YtaHR0cDov
L3Nob2UucmNoLnN0Z2xhYnMuaWJtLmNvbS9jZXJ0cy9jcmwucGVtMA4GA1UdDwEB
/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDAjAdBgNVHQ4EFgQUJqFG/AckkKoB
T8kRhyDCMNzmQ9gwDQYJKoZIhvcNAQEFBQADgYEAtqFIHeHakd1QAlxYRhKefqQg
VW0X7VRVJe7IhUKHBe8DXwSJmIETdxUbhzwNhmxijJkGyBu055YSlCz4X+wNaSC8
lDrO5g1ej3wh2cZFzVAYzyDhBo6urXiX9XEi94tc3/UBvwRHGP/MtmRJCbUyr5A7
p3Xu6ZBlpTyRZ18KRpU=
-----END CERTIFICATE-----

      2. Verify the certificates by using the procedure in Verifying certificates for Teracloud Streams users.

      To authenticate users, Teracloud® Streams interfaces can use a certificate or a password protected PKCS #12 file that contains the certificate. You can obtain the PKCS #12 file from a CA, or create this file by using the procedure in Creating a password protected PKCS #12 file for certificates.

    • If you are using self-signed certificates, complete the following steps:
      1. Generate an RSA private key by using the openssl genpkey command, for example:
        openssl genpkey -algorithm RSA -out selfsigned.key
        Restriction: If the domain is configured to use Transport Layer Security (TLS) 1.2, you must include the -pkeyopt rsa_keygen_bits:numbits option with numbits set to 2048 or larger, for example:
        openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out
 selfsigned.key

      2. Generate a client certificate from the private key by using the openssl req command, for example:
        openssl req -x509 -new -key selfsigned.key -out selfsigned.pem -subj '/C=CA/ST=MN/O=IBM/OU=Streams/CN=selfsigned/'
        Restriction: If the domain is configured to use Transport Layer Security (TLS) 1.2, you must include the -sha256 option, for example:
        openssl req -x509 -sha256 -new -key selfsigned.key -out selfsigned.pem -subj '/C=CA/ST=MN/O=IBM/OU=Streams/CN=selfsigned/'

      To authenticate users, Teracloud® Streams interfaces can use a certificate or a password protected PKCS #12 file that contains the certificate. To create this file, use the procedure in Creating a password protected PKCS #12 file for certificates.

  2. Add the trusted certificate to the web management service truststore.
    • If you use certificates that are signed by a CA, the trusted certificate is the certificate of the CA that issued the client certificate.
      Attention: If the certificate revocation status is valid, all client certificates that are issued by that CA can authenticate after you add the CA certificate to the web management service truststore. For more information about the certificate revocation status, see Setting up client certificate revocation checking for Teracloud Streams users.

    • If you use self-signed certificates, the trusted certificate is the self-signed certificate.
    To add the trusted certificate to the web management service truststore, enter the following Teracloud® Streams streamtool command:
    streamtool addcertificate -d domainid --clientid trustedcert -f trustedcert.pem
    A message similar to the following example is displayed:
    Trusted client certificate for trustedcert imported successfully for domain domainid.
    Notes:
    • You can specify a PKCS #12 file that contains the trusted certificate on the streamtool addcertificate command. If specified, you are prompted for the PKCS #12 password. If the PKCS #12 file contains more than one trusted certificate, you are prompted to select a trusted certificate.

    • You can enter any name for the clientid, but the preferred practice is to use a name that is associated with the trusted certificate. In the streamtool command example, the clientid of trustedcert is associated with the file name of the trusted certificate. Another option is to use the subject CN of the trusted certificate, as shown in the following example:
      openssl x509 -noout -subject -in trustedcert.pem 
subject= /C=US/ST=MN/O=IBM/OU=Streams/CN=trustedcert/emailAddress=admin@example.com
    Note: You can enter any name for the clientid, but the preferred practice is to use a name that is associated with the trusted certificate. In the streamtool command example, the clientid of trustedcert is associated with the file name of the trusted certificate. Another option is to use the subject CN of the trusted certificate, as shown in the following example:
    openssl x509 -noout -subject -in trustedcert.pem 
subject= /C=US/ST=MN/O=IBM/OU=Streams/CN=trustedcert/emailAddress=admin@example.com

  3. Set up Teracloud® Streams authorization for the certificate user.
    By default, the certificate user is the subject CN of the client certificate. You can display the client certificate subject information by entering the following openssl command:
    openssl x509 -noout -subject -in /streamscertificates/streamsuser.pem 
subject= /C=US/ST=MN/O=IBM/OU=Streams/CN=streamsuser/emailAddress=streamsuser@example.com
    In this example, the subject CN is streamsuser. For more information about the subject CN and other information in a client certificate, see Setting the user ID pattern for certificate authentication.

    You can configure permissions for a certificate user by using roles or by setting access permissions for the user. Groups do not apply to certificate users. To configure permissions, see Configuring user access to Teracloud Streams domains and instances.

  4. If you are using certificates that are signed by a CA, you might need to modify the default client revocation method that is used by Teracloud® Streams. For more information, see Setting up client certificate revocation checking for Teracloud Streams users.
    Client certificate revocation checking does not apply to self-signed certificates.

  5. Enable client certificate authentication for the domain.

    The procedure to enable client certificate authentication depends on the Teracloud® Streams interface that you use.

    InterfaceProcedure
    streamtool Set the STREAMS_X509CERT environment variable to the path of the client certificate or a PKCS #12 file that contains the certificate.
    • Client certificate example
      export STREAMS_X509CERT=/streamscertificates/streamsuser.pem
    • PKCS #12 file example
      export STREAMS_X509CERT=/streamscertificates/streamsuser.p12
    Notes:
    • If you specify a PKCS #12 file, Teracloud® Streams prompts you for the PKCS #12 password. If the PKCS #12 file contains more than one certificate, Teracloud® Streams prompts you to select a user certificate.

    • You can disable certificate authentication by running the unset STREAMS_X509CERT command.
    Streams Console Complete the following steps:
    1. Enable client authentication by setting the sws.clientAuthenticationEnabled domain property to true. You can use the streamtool setdomainproperty command to set this property.

    2. For the changes to take effect, restart the domain.

    3. Create a PKCS #12 file that contains the following files:
      • User certificate
      • User private key file
      • CA certificate, if the user certificate is signed by a CA
      For instructions, see Creating a password protected PKCS #12 file for certificates.

    4. Import the PKCS #12 file into your browser. For additional information, see the help for your browser.