External authentication with IBM® Spectrum LSF (eauth)

The external authentication feature uses an executable file called eauth. You can write an eauth executable that authenticates users, hosts, and daemons that use a site-specific authentication method such as Kerberos or DCE Security Services client authentication. You can also specify an external encryption key (recommended) and the user account under which eauth runs.

Important: LSF uses an internal encryption key by default. To increase security, configure an external encryption key by defining the parameter LSF_EAUTH_KEY in lsf.sudoers. To use the lsf.sudoers file, you must enable the setuid bit for the LSF administration commands. Run the hostsetup --setuid command option on the LSF management and candidate hosts. Since this allows LSF administration commands to run with root privileges, do not enable the setuid bit if you do not want these LSF commands to run with root privileges.

The hostsetup --setuid command enables the setuid bit for the following LSF executable files: badmin, lsadmin, egosh, utmpreg, swtbl_api, ntbl_api, lstbl_nid, and swtbl_poe.

During LSF installation, a default eauth executable is installed in the directory that is specified by the parameter LSF_SERVERDIR (set by cshrc.lsf and profile.lsf). The default executable provides an example of how the eauth protocol works. Write your own eauth executable based on this example to meet the security requirements of your cluster.

userA submits a job from hostA, LSF dispatches the job to hostB. eauth -s runs as root on hostB and decrypts the user name. eauth -s runs on hostB and verifies the decrypted user name against the user name that submitted the job. If the user names match, the job runs. — Figure 1. Default behavior (eauth executable provided with LSF)

The eauth executable uses corresponding processes eauth -c host_name (client) and eauth -s (server) to provide a secure data exchange between LSF daemons on client and server hosts. The variable host_name refers to the host on which eauth -s runs; that is, the host called by the command. For bsub, for example, the host_name is NULL, which means the authentication data works for any host in the cluster.

user1 runs an LSF command on a client host. The command invokes eauth -c, which gets the external authentication data. eauth -c passes the data to the LSF client command through stdout. The client host connects to the server host. The LSF daemon on the server host invokes eauth -s as the primary LSF administrator. eauth -s receives authentication data through stdin. If the authentication succeeds, the command succeeds. — Figure 2. How eauth works

One eauth -s process can handle multiple authentication requests. If eauth -s terminates, the LSF daemon invokes another instance of eauth -s to handle new authentication requests.

The standard input stream to eauth -s is a text string with the following format:

uid gid user_name client_addr client_port user_auth_data_len eauth_client 
eauth_server aux_data_file aux_data_status user_auth_data

The following table explains the format of the text stream:

Variable	Represents
`uid`	User ID of the client user
`gid`	Group ID of the client user
`user_name`	User name of the client user
`client_addr`	IP address of the client host
`client_port`	Port number from which the client request originates.
`user_auth_data_len`	Length of the external authentication data that is passed from the client host.
`eauth_client`	Daemon or user that invokes the eauth -cc command.
`eauth_server`	Daemon that invokes the eauth -s command.
`aux_data_file`	Location of the temporary file that stores encrypted authentication data.
`aux_data_status`	File in which eauth -s stores authentication status. When used with Kerberos authentication, eauth -s writes the source of authentication to this file if authentication fails. For example, if mbatchd to mbatchd authentication fails, eauth -s writes "mbatchd" to the file defined by `aux_data_status`. If user to mbatchd authentication fails, eauth -s writes "user" to the `aux_data_status` file.
`user_auth_data`	External authentication data that is passed from the client host.

The variables that are required for the eauth executable depend on how you implement external authentication at your site. For eauth parsing, unused variables are marked by empty quotation marks (").

User credentials

When an LSF user submits a job or issues a command, the LSF daemon that receives the request verifies the identity of the user by checking the user credentials. External authentication provides the greatest security of all LSF authentication methods because the user credentials are obtained from an external source, such as a database, and then encrypted prior to transmission. For Windows hosts, external authentication is the only truly secure type of LSF authentication.

Host credentials

LSF first authenticates users and then checks host credentials. LSF accepts requests that are sent from all hosts that are configured as part of the LSF cluster, including floating clients and any hosts that are dynamically added to the cluster. LSF rejects requests sent from a host that is not running LSF. If your cluster requires extra host authentication, you can write an eauth executable that verifies both user and host credentials.

Daemon credentials

Daemon authentication provides a secure channel for passing credentials between hosts, mediated by the management host. The management host mediates authentication by using the eauth executable, which ensures secure passing of credentials between submission hosts and execution hosts, even though the submission host does not know which execution host is selected to run a job.

Daemon authentication applies to the following communications between LSF daemons:

mbatchd requests to sbatchd
sbatchd updates to mbatchd
PAM interactions with res
mbatchd to mbatchd (for the LSF multicluster capability)

Scope

Applicability	Details
Operating system	UNIX
Allows	Authentication of LSF users, hosts, and daemons Authentication of any number of LSF users
Not required for	Authorization of users based on account permissions
Dependencies	UNIX user accounts must be valid on all hosts in the cluster, or the correct type of account mapping must be enabled: For a cluster with a non-uniform user name space, between-host account mapping must be enabled. You must enable cross-cluster user account mapping if you use the LSF multicluster capability with a non-uniform user name space. User accounts must have the correct permissions to successfully run jobs. The owner of lsf.sudoers on Windows must be `Administrators`.