In this tutorial, you will learn how to configure Kerberos authentication for three IBM Streams interfaces for the current user. The interfaces are: Streams Console, Streamtool, and Domain Manager.

Prior to Streams 4.2, login modules and client certificates could be used to customize user authentication for an enterprise domain. Now, Kerberos is an option. Kerberos is a network authentication protocol developed by the Massachusetts Institute of Technology (MIT) that is designed to provide secure communications over a non-secure network using secret-key cryptography. The primary benefits are strong encryption and single sign-on (SSO).

After completing this step-by-step tutorial, you will be able to easily access all three interfaces without being prompted for your username and password credentials.


Prerequisites

IBM Streams supports the following Kerberos V5 implementations and browsers. Note that the Google Chrome browser is not supported.

  1. MIT Kerberos V5 Release 1.14 for Linux (with Mozilla Firefox)
  2. Microsoft Active Directory for Windows Server 2012 (with Microsoft Internet Explorer)

In this tutorial, I will be using MIT Kerberos for Linux with Mozilla Firefox as we expect that the majority of Streams users will choose this implementation. For those who would like to use Microsoft Active Directory, the general concepts covered in this article will apply, but the terminal commands will differ. For more information, refer to the information in IBM Knowledge Center.

In order to set up Kerberos, the following prerequisites must be met:

  • A Streams domain has been created and is started
  • The DomainAdministrator role has been assigned to your user or group. If you are not currently a DomainAdministrator, please ask the domain administrator to assign this role to you.
  • Kerberos must be installed on the main host where the configuration will be completed. To install and configure Kerberos, see the Kerberos documentation.
  • The following client RPM packages must be installed on all resources that run the IBM Streams web management (SWS) service. For installation instructions, see Installing RPMs in the operating system installation package in IBM Knowledge Center.
    • RHEL 6 and 7 and CentOS 6 and 7: krb5-libs, krb5-workstation
    • SLES 11: krb5, krb5-client
  • You must have the ability to run the kadmin or kadmin.local command in order to perform administrative actions (e.g., creating service principals). For more information, refer to the Kerberos documentation.

Configuring Kerberos

Let’s look at the Kerberos terms that will be used in this tutorial:

  • Key Distribution Center (KDC): The Kerberos KDC is the trusted third party that manages user authentication.
  • service principal: The Kerberos service principals are the IBM Streams authentication and authorization (AAS) service and the IBM Streams web management (SWS) service.
  • user principal: User principals are Kerberos users who access IBM Streams services and interfaces.
For reference, these are the values that will be used in the following steps:

  • streamsdomain: My Streams domain ID
  • qfma: The user principal (my username)
  • streams-aas: The Kerberos service principal name for the AAS service
  • HTTP: The Kerberos service principal name for the SWS service
  • streamshost1.ibm.com: The fully qualified name of the IBM Streams resource that is running the SWS service in my domain
  • IBM.COM: The name of the Kerberos realm

Before starting the tutorial, there are a few points I’d like to cover. This article covers three interfaces: Streamtool, Domain Manager, and Streams Console. You can split up the steps into two parts: one for configuring Kerberos for both Streamtool and Domain Manager (they get enabled at the same time), and another for configuring Kerberos for Streams Console. The Console component is dependent upon the steps for Streamtool/Domain Manager, as Console uses credential delegation. Futhermore, whereas the Streamtool/Domain Manager component sets up the AAS service, the Console component sets up the SWS service. The steps for both components are analagous (i.e., you would execute the same terminal commands but against different service principals). In order to make this tutorial succinct, I will present two sets of commands for each step, one for each component.

Let’s begin!

bee

 

Configure the Kerberos encryption type for IBM Streams

If you are using strong encryption, such as AES-256 encryption, then you will need to complete this step. Even though Kerberos includes strong encryption by default, you must complete the following procedure to enable strong encryption for Streams.

  1. Download the policy files from the IBM Unrestricted SDK JCE policy files website
    IBM Unrestricted SDK JCE policy files
  2. Enable Kerberos strong encryption for IBM Streams by replacing the policy JAR files in your Streams install. You may want to save the old files in case you need to revert these changes in the future.
    $ cd $STREAMS_INSTALL/java/jre/lib/security
    $ mkdir ~/Kerberos_tmp
    $ mv local_policy.jar ~/Kerberos_tmp/local_policy.jar
    $ mv US_export_policy.jar ~/Kerberos_tmp/US_export_policy.jar
    $ cp <path_to_unrestrictedpolicyfiles>/local_policy.jar .
    $ cp <path_to_unrestrictedpolicyfiles>/US_export_policy.jar .

bee

 

Configure the Mozilla Firefox browser on Linux

This step is only applicable to Kerberos for Streams Console. Console uses the Simple and Protected GSS-API Negotiation (SPNEGO) protocol to authenticate users with Kerberos credentials. To use Kerberos authentication, you must configure the Mozilla Firefox browser to use SPNEGO.

  1. Start Firefox on the Linux machine where you will be accessing Streams Console
  2. In the address field, type about:config
  3. In the Search field, type network.n
  4. Double-click network.negotiate-auth.trusted-uris, enter the host name of the web management service, and click OK. For example, since my URL for accessing the Streams Console is https://streamshost1.ibm.com:8443/streams/domain/console, I would enter https://streamshost1.ibm.com in this field.
  5. Double-click network.negotiate-auth.delegation-uris, enter the host name of the web management service, and click OK. This is the same value that you entered in the previous step.
  6. Restart your Firefox browser to activate this configuration

Mozilla Firefox Kerberos Configuration

bee

 

Set up the Streams AAS and SWS services as the Kerberos service principals on all resources that are running the services

The following steps pertaining to AAS should be run on all resources that are running AAS, and likewise for SWS. In my case, both AAS and SWS are running on the same resource in my domain and only that resource (streamshost1.ibm.com). You can check where the services are running by using the streamtool getdomainstate command. For example:

$ streamtool getdomainstate
domain: streamsdomain State: STARTED
Resource     Status  Services                                Tags
streamshost1 RUNNING RUNNING:aas,auditlog,controller,jmx,sws aas,management,sws,view
streamshost2 RUNNING WAITING:controller                      application
streamshost3 RUNNING WAITING:controller                      application
streamshost4 RUNNING WAITING:controller                      application

Below are the steps to follow. I will be running them on the streamshost1.ibm.com resource.

  1. Create service principals for AAS and SWS. For example, see the commands in bold:
    1. AAS
      $ sudo /usr/sbin/kadmin.local
      Authenticating as principal qfma/admin@IBM.COM with password.
      kadmin.local: addprinc -randkey streams-aas/streamshost1.ibm.com@IBM.COM
      WARNING: no policy specified for streams-aas/streamshost1.ibm.com@IBM.COM; defaulting to no policy
      Principal “streams-aas/streamshost1.ibm.com@IBM.COM” created.
    2. SWS
      $ sudo /usr/sbin/kadmin.local
      Authenticating as principal qfma/admin@IBM.COM with password.
      kadmin.local: addprinc -randkey HTTP/streamshost1.ibm.com@IBM.COM
      WARNING: no policy specified for HTTP/streamshost1.ibm.com@IBM.COM; defaulting to no policy
      Principal “HTTP/streamshost1.ibm.com@IBM.COM” created.

    If you would like to retrieve a list of principals, you can use the kadmin list_principals command.

    $ sudo /usr/sbin/kadmin.local
    Authenticating as principal root/admin@IBM.COM with password.
    kadmin.local: list_principals
    HTTP/streamshost1.ibm.com@IBM.COM
    K/M@IBM.COM
    kadmin/admin@IBM.COM
    kadmin/changepw@IBM.COM
    kadmin/streamshost1.ibm.com@IBM.COM
    krbtgt/IBM.COM@IBM.COM
    qfma/admin@IBM.COM
    qfma@IBM.COM
    streams-aas/streamshost1.ibm.com@IBM.COM
  2. Create .keytab files for AAS and SWS in <user-home-directory>/.streams/var/security/keytabs. The keytab encryption keys must be compatible with the supported user encryption types. Since I am using AES-256, I would ensure that an entry for aes256 is created. For example, see the commands in bold:
    1. AAS
      $ sudo su
      [root@streamshost1 qfma]# cd ~
      [root@streamshost1 ~]# /usr/sbin/kadmin.local
      Authenticating as principal root/admin@IBM.COM with password.
      kadmin.local: ktadd -norandkey -k streams-aas.keytab streams-aas/streamshost1.ibm.com@IBM.COM
      Entry for principal streams-aas/streamshost1.ibm.com@IBM.COM with kvno 1, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:streams-aas.keytab.
      Entry for principal streams-aas/streamshost1.ibm.com@IBM.COM with kvno 1, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:streams-aas.keytab.
      Entry for principal streams-aas/streamshost1.ibm.com@IBM.COM with kvno 1, encryption type des3-cbc-sha1 added to keytab WRFILE:streams-aas.keytab.
      Entry for principal streams-aas/streamshost1.ibm.com@IBM.COM with kvno 1, encryption type arcfour-hmac added to keytab WRFILE:streams-aas.keytab.
    2. SWS
      $ sudo su
      [root@streamshost1 qfma]# cd ~
      [root@streamshost1 ~]# /usr/sbin/kadmin.local
      Authenticating as principal root/admin@IBM.COM with password.
      kadmin.local: ktadd -norandkey -k streams-sws.keytab HTTP/streamshost1.ibm.com@IBM.COM
      Entry for principal HTTP/streamshost1.ibm.com@IBM.COM with kvno 1, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:streams-sws.keytab.
      Entry for principal HTTP/streamshost1.ibm.com@IBM.COM with kvno 1, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:streams-sws.keytab.
      Entry for principal HTTP/streamshost1.ibm.com@IBM.COM with kvno 1, encryption type des3-cbc-sha1 added to keytab WRFILE:streams-sws.keytab.
      Entry for principal HTTP/streamshost1.ibm.com@IBM.COM with kvno 1, encryption type arcfour-hmac added to keytab WRFILE:streams-sws.keytab.
  3. Change the user and group owner of the streams-aas.keytab and streams-sws.keytab files to the user:group that runs AAS and/or SWS on the resource. For example, since my username is qfma and my group is streamsgroup, I would run these commands:
    1. AAS
      $ sudo su
      [root@streamshost1 qfma]# cd ~
      [root@streamshost1 ~]# chown qfma streams-aas.keytab
      [root@streamshost1 ~]# chgrp streamsgroup streams-aas.keytab
    2. SWS
      $ sudo su
      [root@streamshost1 qfma]# cd ~
      [root@streamshost1 ~]# chown qfma streams-sws.keytab
      [root@streamshost1 ~]# chgrp streamsgroup streams-sws.keytab
  4. Change the permissions of the streams-aas.keytab and streams-sws.keytab files to 400. Because the .keytab files contain encrypted passwords, anyone with read permission on the files can run a command in the Kerberos realm for the principals in the realm. You should restrict and monitor permissions on these files so that only the principal whose credentials the application is authenticating with has read access to the file. For example:
    1. AAS
      $ sudo su
      [root@streamshost1 qfma]# cd ~
      [root@streamshost1 ~]# chmod 400 streams-aas.keytab
    2. SWS
      $ sudo su
      [root@streamshost1 qfma]# cd ~
      [root@streamshost1 ~]# chmod 400 streams-sws.keytab
  5. Copy the streams-aas.keytab and streams-sws.keytab files that you created in the previous step to the directory: <user-home-directory>/.streams/var/security/keytabs. For example:
    1. AAS
      $ sudo su
      [root@streamshost1 qfma]# cd ~
      [root@streamshost1 ~]# cp -p streams-aas.keytab /tmp
      [root@streamshost1 ~]# exit
      exit
      $ cp /tmp/streams-aas.keytab /home/qfma/.streams/var/security/keytabs
    2. SWS
      $ sudo su
      [root@streamshost1 qfma]# cd ~
      [root@streamshost1 ~]# cp -p streams-sws.keytab /tmp
      [root@streamshost1 ~]# exit
      exit
      $ cp /tmp/streams-sws.keytab /home/qfma/.streams/var/security/keytabs

    Your keytabs directory should look like this:

    $ pwd
    /home/qfma/.streams/var/security/keytabs
    $ ls -l
    total 8
    -r——– 1 qfma streamsgroup 414 Aug 31 12:55 streams-aas.keytab
    -r——– 1 qfma streamsgroup 386 Aug 31 12:55 streams-sws.keytab
  6. Verify that you are able to log in using the streams-aas.keytab and streams-sws.keytab files using the kinit program. For example:
    1. AAS
      1. Ensure that you use the kinit program that is installed with IBM Streams, not the MIT Kerberos kinit program.
        $STREAMS_INSTALL/java/jre/bin/kinit -f -k -t /home/qfma/.streams/var/security/keytabs/streams-aas.keytab streams-aas/streamshost1.ibm.com@IBM.COM

        If your krb5.conf file is not found in the default location of /etc/krb5.conf, you can use the following alternative command:

        $STREAMS_INSTALL/java/bin/java -Djava.security.krb5.conf=<path-to-krb5.conf> com.ibm.security.krb5.internal.tools.Kinit -f -k -t /home/qfma/.streams/var/security/keytabs/streams-aas.keytab streams-aas/streamshost1.ibm.com@IBM.COM
      2. To see the list of tickets, use the klist command:
        $ $STREAMS_INSTALL/java/jre/bin/klist

        Credentials cache: /home/qfma/krb5cc_qfma
        Default principal: streams-aas/streamshost1.ibm.com@IBM.COM
        Number of entries: 1

        [1] Service principal: krbtgt/IBM.COM@IBM.COM
                Valid starting: Wednesday, August 31, 2016 at 5:40:02 PM
                Expires: Thursday, September 1, 2016 at 5:40:02 PM

      3. After the .keytab file is verified, remove the credential cache file in the following directory: <user-home-directory>/krb5cc_<userID>. For example,
        $ rm /home/qfma/krb5cc_qfma
    2. SWS
      1. Ensure that you use the MIT Kerberos kinit program, not the kinit program that is installed with IBM Streams.
        $ /usr/bin/kinit -f -k -t /home/qfma/.streams/var/security/keytabs/streams-sws.keytab HTTP/streamshost1.ibm.com@IBM.COM

        If your krb5.conf file is not found in the default location of /etc/krb5.conf, set the KRB5_CONFIG environment variable to the correct path and then run the kinit command above.

      2. To see the list of tickets, use the klist command:
        $ /usr/bin/klist
        Ticket cache: FILE:/tmp/krb5cc_3158
        Default principal: HTTP/streamshost1.ibm.com@IBM.COM

        Valid starting     Expires            Service principal
        08/31/16 18:05:45  09/01/16 18:05:45  krbtgt/IBM.COM@IBM.COM
                renew until 08/31/16 18:05:45

      3. After the .keytab file is verified, remove the credential cache file by running the following command:
        $ /usr/bin/kdestroy
    Troubleshooting help:

    CDISR2569E The key files that are used for authentication cannot be found, or cannot be opened.

    To resolve the problem:

    • Ensure that the .keytab file mode is 400
    • Ensure that the specified .keytab file owner and group are correct
    • Ensure that the specified .keytab file location is correct

    org.ietf.jgss.GSSException, major code: 11, minor code: 45 [com.ibm.streams.tooling.rest.util.SpnegoUtil$SpnegoAction.run()]
    TRACE: thread:76[Default Executor-thread-22] major string: General failure, unspecified at GSSAPI level 
    [com.ibm.streams.tooling.rest.util.SpnegoUtil$SpnegoAction.run()]
    TRACE: thread:76[Default Executor-thread-22] minor string: Kerberos error while decoding and verifying token:
    com.ibm.security.krb5.KrbException, status code: 45

    To resolve the problem:

    • Ensure that the .keytab file supports the encryption type that is specified in the list of supported encryption types for the user

bee

 

Update the IBM Streams domain properties that are used for Kerberos

The only value that you must set is security.kerberosEnabled. You will likely not need to update the other properties and can accept the default values. However, if updates are necessary, you can use the Domain Manager or the streamtool setdomainproperty command. For more information about each property, see the Domain Manager help information or use the streamtool man domainproperties command.

Domain property Default value Value to set to
security.kerberosEnabled false true
security.kerberosConfigurationFile /etc/krb5.conf Path to krb5.conf file
security.kerberosKDC KDC value in krb5.conf Kerberos KDC
security.kerberosRealm Realm value in krb5.conf Kerberos realm
security.kerberosDebug false true to turn Kerberos debugging for diagnostics on
aas.kerberosServicePrincipal streams-aas/%STREAMS_RESOURCE% AAS service principal name
aas.kerberosKeytabFile %STREAMS_USER_HOME%/.streams/var/security/keytabs/streams-aas.keytab Path to AAS keytab file
sws.kerberosServicePrincipal HTTP/%STREAMS_RESOURCE% SWS service principal name
sws.kerberosKeytabFile %STREAMS_USER_HOME%/.streams/var/security/keytabs/streams-sws.keytab Path to SWS keytab file

Restart the Streams domain for the configuration changes to take effect.

$ streamtool stopdomain
$ streamtool startdomain

bee

 

Obtain and cache the Kerberos ticket-granting tickets that are used to authenticate user principals

The final step is to generate tickets in order for your user to authenticate with Kerberos. To do this, your user must be registered as a user principal with the Kerberos KDC. For example, my user principal is qfma@IBM.COM.

  1. AAS
    To obtain and cache a Kerberos ticket-granting ticket, run the following commands and enter your password if prompted:

    $ $STREAMS_INSTALL/java/jre/bin/kinit -f
    Password for qfma@IBM.COM:

    Done!
    New ticket is stored in cache file /home/qfma/krb5cc_qfma

    To list the ticket-granting tickets in the ticket cache, run the following command:

    $ $STREAMS_INSTALL/java/jre/bin/klist

    Credentials cache: /home/qfma/krb5cc_qfma
    Default principal: qfma@IBM.COM
    Number of entries: 1

    [1] Service principal: krbtgt/IBM.COM@IBM.COM
            Valid starting: Wednesday, August 31, 2016 at 6:49:07 PM
            Expires: Thursday, September 1, 2016 at 6:49:07 PM

  2. SWS
    To obtain and cache a Kerberos ticket-granting ticket, run the following command and enter your password if prompted:

    $ /usr/bin/kinit -f
    Password for qfma@IBM.COM:

    To list the ticket-granting tickets in the ticket cache, run the following command:

    $ /usr/bin/klist
    Ticket cache: FILE:/tmp/krb5cc_3158
    Default principal: qfma@IBM.COM

    Valid starting     Expires            Service principal
    08/31/16 13:48:26  09/01/16 18:52:57  krbtgt/IBM.COM@IBM.COM
            renew until 08/31/16 18:52:57

Troubleshooting help:

No keys to add to Subject for qfma@IBM.COM com.ibm.security.krb5.KrbException, status code: 101
    message: Invalid option in ticket request

To resolve the problem:

  • Ensure that you are using the correct kinit program (IBM Streams for AAS, and MIT Kerberos for SWS) and run the kinit -f command
  • Ensure that the Kerberos configuration file (e.g., /etc/krb5.conf) contains forwardable = true

com.ibm.security.krb5.internal.crypto.KrbCryptoException, status code: 0
    message: com.ibm.security.krb5.internal.KrbException, status code: 31
    message: Integrity check on decrypted field failed

To resolve the problem:

  • Ensure that you installed the Unrestricted SDK Java™ Cryptography Extension (JCE) policy files that are required to use Kerberos strong encryption with IBM Streams. If you do not want to use strong encryption, you must configure a different encryption type for Kerberos. For more information, see this section.

bee

Try it out!

Ready for the fun part? Let’s try accessing all three interfaces and see that you will never need to provide our username and password credentials!

  • For Streamtool, try running the streamtool getdomainstate command. Ensure that public and private key pairs do not exist by running streamtool rmkey to remove all key files. You should see the correct command output without being prompted for your credentials!
  • For Domain Manager, launch the program by running streamtool launch --domainmgr. No password required!
  • For Streams Console, run streamtool geturl and navigate to the returned URL in Firefox. Observe as you automatically bypass the login page!

If, for some reason, authentication was not successful, please refer to the troubleshooting section in IBM Knowledge Center.


Summary

In this tutorial, you configured Kerberos authentication for Streamtool, Domain Manager, and Streams Console. To accomplish this, you configured the Kerberos encryption type for Streams and enabled Firefox to use the SPNEGO protocol. You then set up the AAS and SWS domain services as the Kerberos service principals and updated the Kerberos domain properties. Finally, to authenticate your user principal, you obtained and cached Kerberos ticket-granting tickets. From this point on, you can access these interfaces without having to type in your username and password. Very cool!

Join The Discussion