IBM InfoSphere Streams Version 4.1.1

Setting up client certificate authentication for InfoSphere Streams users

Use this procedure to set up client certificate authentication for an InfoSphere® 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, InfoSphere Streams attempts to use X.509 certificate authentication when it authenticates a user to the domain. If the certificate authentication fails, InfoSphere Streams uses the default authentication method for the domain, which is either LDAP or PAM.

Procedure

Obtain X.509 certificates.
You can use certificates that are signed by a certificate authority (CA) or self-signed certificates. InfoSphere 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 InfoSphere Streams users.
  To authenticate users, InfoSphere 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
```
  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/'
```
  To authenticate users, InfoSphere 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.
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 InfoSphere 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 InfoSphere 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
```
Set up InfoSphere 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 InfoSphere Streams domains and instances.
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 InfoSphere Streams. For more information, see Setting up client certificate revocation checking for InfoSphere Streams users. Client certificate revocation checking does not apply to self-signed certificates.

Enable client certificate authentication for the domain.

If you enable client certificate authentication for a domain, InfoSphere Streams attempts to use the X.509 certificate for user authentication. If the certificate authentication fails, InfoSphere Streams uses the default authentication method for the domain, which is either LDAP or PAM.

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

Interface	Procedure
Domain Manager and 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, InfoSphere Streams prompts you for the PKCS #12 password. If the PKCS #12 file contains more than one certificate, InfoSphere Streams prompts you to select a user certificate. You can disable certificate authentication by running the unset STREAMS_X509CERT command. For the change to take effect in the Domain Manager, restart the Domain Manager.
Streams Studio	Complete the following steps: Specify the path to the client certificate by using the Streams Explorer preference page. Select the Use client certificate for authentication option when you add the domain connection. When you connect to the domain, InfoSphere Streams uses the certificate that you specified in the previous step for authentication. Notes: If you specify a path to a PKCS #12 file that contains the certificate, InfoSphere Streams prompts you for the PKCS #12 password. This password is stored in Eclipse's Secure Storage. If you specify a PKCS #12 file that contains more than one certificate, InfoSphere Streams prompts you to select a user certificate.
Streams Console	Complete the following steps: Enable client authentication by setting the sws.clientAuthenticationEnabled domain property to true. You can use the Domain Manager or the streamtool setdomainproperty command to set this property. For the changes to take effect, use the streamtool restartdomainservice sws command to restart the web management service, or restart the domain. 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.
Streams for Excel and REST API	Complete the following steps: Enable client authentication by setting the sws.clientAuthenticationEnabled domain property to true. You can use the Domain Manager or the streamtool setdomainproperty command to set this property. For the changes to take effect, use the streamtool restartdomainservice sws command to restart the web management service, or restart the domain. Configure the InfoSphere Streams interface to authenticate using the client certificate. For Streams for Excel, see Setting up certificate authentication for IBM® InfoSphere Streams for Microsoft Excel. For the REST API, see Configuring security for the InfoSphere Streams REST API.