Setting up client certificate authentication for IBM Streams users

Use this procedure to set up client certificate authentication for IBM® Streams by using X.509 certificates and Kubernetes secrets.

Using client certificate authentication is optional. However, if you choose to use client certificate authentication, you must follow this procedure before installing Streams.

Before you begin

In the following procedure, the keytool command is used to work with certificates. This command is included in the Java Runtime Environment package. For more information about the keytool command, go to the Oracle Java SE documentation . The openssl command is also used as a reference for generating PKCS #12 keystores. 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, Streams attempts to use X.509 certificate authentication when it authenticates a user to the Streams instance. If certificate authentication fails, Streams uses the default authentication method for the instance, which is LDAP.

Procedure

Create the streams.jks keystore by running the following command:

keytool -genkeypair -alias e1 -keyalg RSA -keysize 2048 -keystore streams.jks 
-storepass <your_keystore_password> -keypass <your_key_password> -validity 3650 
-dname "CN=example.ibm.com,OU=SWG,O=IBM,L=Rochester,ST=MN,C=US"

Restriction: To use Transport Layer Security (TLS) 1.2, you must include the keysize option set to 2048 or larger.

Run the following command to use the streams.jks keystore and create the streams.jts truststore:
```
cp streams.jks streams.jts
```
Obtain X.509 certificates.

You can use certificates that are signed by a certificate authority (CA) or self-signed certificates. 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 IBM Streams users.
  To authenticate users, 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, generate an RSA private key and a client certificate by using the openssl command. The following command creates the e1.pem private key and the certificate c1.pem:
```
openssl genrsa -out e1.pem 1024 
openssl req -x509 -new -days 3650 -key e1.pem -out c1.pem
-subj '/C=US/ST=MN/L=Rochester/O=IBM/OU=SWG/CN=streamsadmin/' 
```
  For more information about the subject CN and other information in a client certificate, see Setting the user ID pattern for certificate authentication.
Add the trusted certificate to the streams.jts truststore under its own alias:
```
keytool -import -alias e2 -trustcacerts -keystore streams.jts 
-storepass <your_keystore_password> -file c1.pem --noprompt 
```
Note:
- 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 truststore. For more information about the certificate revocation status, see Setting up client certificate revocation checking for IBM Streams users.
- If you use self-signed certificates, the trusted certificate is the self-signed certificate.
- You can specify a PKCS #12 file that contains the trusted certificate on the keytool 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.

To use client certificate authentication for Streams, you must set up a Kubernetes secret for the certificate keystore and truststore, and their passwords.

Run the following command to create files that contain the keystore password, truststore password, and keystore alias.

echo -n "<your_keystore_password>" > keystorepw
echo -n "<your_truststore_password>" > truststorepw
echo -n "e1" > keystorealias

Create the Kubernetes secret by running the following command:

kubectl create secret generic my-secret-files --from-file=streams.jks 
--from-file=streams.jts --from-file=keystorepw --from-file=truststorepw --from-file=keystorealias

In the IBMStreamsSecurity manifest, set the value of the security.secret property to the Kubernetes secret name.

# security.secret specifies the secret containing keystore and truststore files, passwords, and alias for the security service.
secret: my-secret-files

Enable client certificate authentication for web management services.

The procedure to enable client certificate authentication depends on the Streams interface that will use the client certificate authentication.

Interface	Procedure
streamtool	Complete the following steps: 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, Streams prompts you for the PKCS #12 password. If the PKCS #12 file contains more than one certificate, 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: Enable client authentication by setting the sws.clientAuthenticationEnabled property to true. You set this property in the `IBMStreamsInstance` manifest during the Streams instance installation. 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. Import the PKCS #12 file into your browser. For additional information, see the help for your browser.
REST API	Complete the following steps: Enable client authentication by setting the sws.clientAuthenticationEnabled property to true. You set this property in the `IBMStreamsInstance` manifest during the Streams instance installation. Configure the IBM Streams interface to authenticate using the client certificate.