Enabling Kerberos authentication on Windows hosts

Configure user authentication through the SSPI-Kerberos security plug-in on Windows hosts in your cluster.

About this task

To enable Kerberos authentication in the IBM® Spectrum Symphony cluster, you must configure all your Windows hosts (management, compute, and client) to use the sec_ego_sspikrb plug-in.

This task uses the following examples to illustrate a basic Kerberos scenario; ensure that you modify this task as it applies to your production cluster:

Your environment includes two Active Directory (AD) domains: ad1.example.com and ad2.example.com. Two management hosts, mghost1.ad1.example.com and mghost2.ad1.example.com, are located in the ad1.example.com domain. A compute host is located in the ad1.example.com domain; a client host is located in the ad2.example.com domain.
All users that log on to the cluster are in one of the following user groups and users are loaded only from groups ad1\symphonyAdmins, ad1\symUserGroup1, and ad2\symUniversalUserGroup2 (a universal user group).
The cluster administrator OS user account is ad1\Administrator, where ad1 specifies the user's domain. This user account must be a domain user and a member of the local Administrators user group.
The AD user who must be mapped to the built-in Admin cluster administrator account in IBM Spectrum Symphony is egoadmin.
Two service principal names (SPNs) are created in the ad1.example.com domain for services on the two management hosts, by using the Windows setspn tool as follows:
```
setspn -A symService/mghost1.ad1.example.com ad1\Administrator
setspn -A symService/mghost2.ad1.example.com ad1\Administrator
```

Procedure

Log on to the primary host as cluster administrator and shut down the cluster:

egosh user logon –u Admin –x Admin
soamcontrol app disable all
egosh service stop all
egosh ego shutdown all

Modify the security configuration on all management hosts in your cluster.
1. On each management host, modify the following parameters in the %EGO_CONFDIR%\ego.conf file:
  - EGO_SEC_PLUGIN: Specify authentication through the sec_ego_sspikrb plug-in when connecting to the IBM Spectrum Symphony cluster.
  - EGO_SEC_CONF: Specify the plug-in's configuration in the format path_to_plugin_conf_dir,created-ttl,plugin_log_level,path_to_plugin_log_dir, where:
    - path_to_plugin_conf_dir (required): Specifies the absolute path to the sec_ego_sspikrb.conf file (created in the next step), which must be set to the value of %EGO_CONFDIR% in your cluster.
    - created_ttl (optional): Specifies a time-to-live duration (in minutes) for the authentication token sent from the client to the server. Valid value is higher than 0 but lower than 1440 minutes (24 hours). The default is 600 minutes (10 hours).
    - plugin_log_level (optional): Specifies the log level for the plug-in. Valid values are DEBUG, INFO, WARN, and ERROR. As a best practice, set the log level as ERROR or WARN. A lower level causes too many messages to be logged, making it harder to troubleshoot if required. If this parameter is not configured, SSPI logs are not generated.
    - path_to_plugin_log_dir (optional): Specifies the absolute path to the directory where the plug-in's logs are located. If this parameter is not configured, SSPI logs are not generated.
  For example:
```
EGO_SEC_PLUGIN=sec_ego_sspikrb
EGO_SEC_CONF=C:\Program Files\shareConf\kernel\conf,0,ERROR,C:\Program Files\IBM\SpectrumComputing\kernel\log
```
2. Create the sec_ego_sspikrb.conf file under %EGO_CONFDIR% and define the following parameters in the file:
  - KERBEROS_ADMIN (required): Specify the AD user that will map to the built-in cluster administrator (Admin). When you use the Admin user account to log on to your cluster, the Admin account is mapped to the AD user that you specify as the KERBEROS_ADMIN. You would then use the password of the AD user to log on. Client logons with this AD user are treated as the Admin user (with its role and permissions).
    While you can configure this parameter as the cluster administrator OS user, it is not required. Whichever user you specify, ensure that you include the user's domain in the format domain\user. It is recommended that you use the NETBIOS domain name. Also, ensure that all management hosts in your cluster use the same value.
  - KRB_SERVICENAME (required): Specify the service’s user account (the cluster administrator OS user) or the service principal name (SPN).
    - To use the service’s user account, specify the user (the cluster administrator OS user) in the format domain\user. For example, enter KRB_SERVICENAME=ad1\Administrator.
      Any time you change the password of the service’s user account (the cluster administrator), ensure that you stop all EGO services and restart the cluster.
    - To use the SPN, you must use the Windows setspn tool to register the SPN for services on all management hosts under the service’s account in the management host-located domain. Then, specify the SPN here in the format serviceName/${host}; do not replace the keyword ${host} with the actual host name. For example, enter KRB_SERVICENAME=symService/${host}.
  - USERLOAD_DOMAIN (optional): Specify the domains from which users or user groups (including universal user groups) are loaded, in the format windows-domain1,windows-domain2,…. You can specify a maximum of 10 domains. Ensure that you use the NETBIOS domain name.
    If you do not configure this parameter, users and user groups are loaded from the primary host-located domain.
  - CACHEEXPIRYTIME (optional): Specify the interval at which the user and user group cache is refreshed. Default is 1 hour. You can specify the interval as a positive integer, or a positive integer followed by a suffix representing days (d or D), hours (h or H), or minutes (m or M). If you do not specify a suffix, the integer is considered in minutes.
    - To specify an interval in days, enter a positive integer followed by d or D. For example, 2D or 2d means that the user cache is set to refresh every 2 days.
    - To specify a duration in minutes or hours, enter a positive integer followed by m or M for minutes or h or H for hours. For example, 2m or 2 means that the user cache is set to refresh every 2 minutes; 2h means that the user cache is set to refresh every 2 hours.
  - INCLUDED_USERGROUP (optional): Specify the user groups (including universal user groups) to load to IBM Spectrum Symphony. Only users belonging to the specified user groups are loaded; if the group contains subgroups, the subgroups and users in the subgroups are not loaded. Use the format domain-name1\groupname1,domain-name1\groupname2,.... Ensure that you use the NETBIOS domain name.
    As a best practice, use this parameter to limit the users you want to load to IBM Spectrum Symphony.
    
    If you configure this INCLUDED_USERGROUP parameter, you cannot configure the EXCLUDED_USERGROUP parameter. If both parameters are configured, neither parameter takes effect.
  - EXCLUDED_USERGROUP (optional): Specify the user groups (including universal user groups) from which users must not be loaded, in the format domain-name1\groupname1,domain-name1\groupname2,.... Ensure that you use the NETBIOS domain name. For example, enter EXCLUDED_USERGROUP=ad1\symUserGroup3,ad2\symUserGroup4.
    As a best practice, use this parameter to limit the users you want to load to IBM Spectrum Symphony.
    
    If you configure this EXCLUDED_USERGROUP parameter, you cannot configure the INCLUDED_USERGROUP parameter. If both parameters are configured, neither parameter takes effect.
  For example:
```
KERBEROS_ADMIN=ad1\egoadmin
KRB_SERVICENAME=symService/${host}
USERLOAD_DOMAIN=ad1,ad2
CACHEEXPIRYTIME=12h
INCLUDED_USERGROUP=ad1\symphonyAdmins,ad1\symUserGroup1,ad2\symUniversalUserGroup2
```
Modify the configuration on all compute hosts in the cluster.
1. On each compute host, define the EGO_SEC_PLUGIN and EGO_SEC_CONF parameters in %EGO_CONFDIR%\ego.conf, similar to the configuration on management hosts in step 2.a. For example:
```
EGO_SEC_PLUGIN=sec_ego_sspikrb
EGO_SEC_CONF=C:\Program Files\IBM\SpectrumComputing\kernel\conf,0,ERROR,C:\Program Files\IBM\SpectrumComputing\kernel\log
```
2. Create the sec_ego_sspikrb.conf file under %EGO_CONFDIR% and define the KERBEROS_ADMIN and KRB_SERVICENAME parameters as configured on management hosts in step 2.b. For example:
```
KRB_SERVICENAME=symService/${host}
KERBEROS_ADMIN=ad1\egoadmin
```
  The KERBEROS_ADMIN parameter is optional. If you define this parameter, use the same value as on management hosts. When this parameter is defined on compute hosts, you can log on to the cluster as the Admin user with the password of the AD user that you define as the KERBEROS_ADMIN. When this parameter is not defined on compute hosts and its value on management hosts is not Admin (the default cluster administrator user), you cannot use the Admin user to log on from compute hosts. Define this parameter if you want to use the Admin user to run IBM Spectrum Symphony commands or to run application clients.
Modify the configuration on all client hosts in the cluster.
1. On each client host, define the EGO_SEC_PLUGIN and EGO_SEC_CONF parameters in %SOAM_HOME%\conf\ego.conf, similar to the configuration on compute hosts in step 3.a. For example:
```
EGO_SEC_PLUGIN=sec_ego_sspikrb
EGO_SEC_CONF=C:\Program Files\IBM\SpectrumComputing\SymphonyClient\Client731\conf,0,ERROR,C:\Program Files\IBM\SpectrumComputing\SymphonyClient\Client731\log
```
2. Create the sec_ego_sspikrb.conf file under %SOAM_HOME%\conf\ and define the KERBEROS_ADMIN and KRB_SERVICENAME parameters as configured on compute hosts in step 3.b. For example:
```
KRB_SERVICENAME=symService/${host}
KERBEROS_ADMIN=ad1\egoadmin
```
From the primary host, start the cluster and enable applications:
```
egosh ego start all 
soamcontrol app enable application_name
```

Results

The Kerberos security configuration takes effect in your cluster.

What to do next

Verify Kerberos authentication in your cluster. See Using Kerberos authentication in a Windows cluster.