External authentication

The external authentication feature provides a framework that enables you to integrate LSF with any third-party authentication product—such as Kerberos or DCE Security Services—to authenticate users, hosts, and daemons. This feature provides a secure transfer of data within the authentication data stream between LSF clients and servers. Using external authentication, you can customize LSF to meet the security requirements of your site.

Contents

  • About external authentication (eauth)

  • Scope

  • Configuration to enable external authentication

  • External authentication behavior

  • Configuration to modify external authentication

  • External authentication commands

About external authentication (eauth)

The external authentication feature uses an executable file called eauth. You can write an eauth executable that authenticates users, hosts, and daemons using 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.

During LSF installation, a default eauth executable is installed in the directory specified by the parameter LSF_SERVERDIR in lsf.conf. The default executable provides an example of how the eauth protocol works. You should write your own eauth executable to meet the security requirements of your cluster.

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.
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
where

The variable …

Represents the …

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 passed from the client host

eauth_client

Daemon or user that invokes eauth -c

eauth_server

Daemon that invokes eauth -s

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 passed from the client host


The variables required for the eauth executable depend on how you implement external authentication at your site. For eauth parsing, unused variables are marked by '''.

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 sent from all hosts 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 non-LSF host. If your cluster requires additional 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 master host. The master host mediates authentication by means of 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 will be 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 (in a MultiCluster environment)

Kerberos authentication

Kerberos authentication is an extension of external daemon authentication, providing authentication of LSF users and daemons during client-server interactions. The eauth executable provided with the Platform integration package uses Kerberos Version 5 APIs for interactions between mbatchd and sbatchd, and between pam and res. When you use Kerberos authentication for a cluster or MultiCluster, authentication data is encrypted along the entire path from job submission through to job completion.

You can also use Kerberos authentication for delegation of rights (forwarding credentials) when a job requires a Kerberos ticket during job execution. LSF ensures that a ticket-granting ticket (TGT) can be forwarded securely to the execution host. LSF also automatically renews Kerberos credentials by means of daemon wrapper scripts.

Scope


Applicability

Details

Operating system

  • UNIX

  • Windows (except for Kerberos authentication)

Allows for

  • 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 and Windows user accounts must be valid on all hosts in the cluster, or the correct type of account mapping must be enabled:
    • For a mixed UNIX/Windows cluster, UNIX/Windows user account mapping must be enabled

    • For a cluster with a non-uniform user name space, between-host account mapping must be enabled

    • For a MultiCluster environment with a non-uniform user name space, cross-cluster user account mapping must be enabled

  • User accounts must have the correct permissions to successfully run jobs.

  • The owner of lsf.sudoers on Windows must be Administrators.


Configuration to enable external authentication

During LSF installation:
  • The parameter LSF_AUTH in lsf.conf is set to eauth, which enables external authentication

  • A default eauth executable is installed in the directory specified by the parameter LSF_SERVERDIR in lsf.conf

The default executable provides an example of how the eauth protocol works. You should write your own eauth executable to meet the security requirements of your cluster.


Configuration file

Parameter and syntax

Default behavior

lsf.conf

LSF_AUTH=eauth

  • Enables external authentication

LSF_AUTH_DAEMONS=y | Y

  • Enables daemon authentication when external authentication is enabled
    Note:

    By default, daemon authentication is not enabled. If you enable daemon authentication and want to turn it off later, you must comment out or delete the parameter LSF_AUTH_DAEMONS.


External authentication behavior

The following example illustrates how a customized eauth executable can provide external authentication of users, hosts, and daemons. In this example, the eauth executable has been customized so that corresponding instances of eauth -c and eauth -s obtain user, host, and daemon credentials from a file that serves as the external security system. The eauth executable can also be customized to obtain credentials from an operating system or from an authentication protocol such as Kerberos.

Figure 3. Example of external authentication

Authentication failure

When external authentication is enabled, the message

User permission denied

indicates that the eauth executable failed to authenticate the user’s credentials.

Security

External authentication—and any other LSF authentication method—depends on the security of the root account on all hosts within the cluster. Limit access to the root account to prevent unauthorized use of your cluster.

Configuration to modify external authentication

You can modify external authentication behavior by writing your own eauth executable. There are also configuration parameters that modify various aspects of external authentication behavior by:
  • Increasing security through the use of an external encryption key (recommended)

  • Specifying a trusted user account under which the eauth executable runs (UNIX and Linux only)

You can also choose Kerberos authentication to provide a secure data exchange during LSF user and daemon authentication and to forward credentials to a remote host for use during job execution.

Configuration to modify security


File

Parameter and syntax

Descriptions

lsf.sudoers

LSF_EAUTH_KEY=key

  • The eauth executable uses the external encryption key that you define to encrypt and decrypt the credentials.

  • The key must contain at least six characters and must use only printable characters.

  • For UNIX, you must edit the lsf.sudoers file on all hosts within the cluster and specify the same encryption key. You must also configure eauth as setuid to root so that eauth can read the lsf.sudoers file and obtain the value of LSF_EAUTH_KEY.

  • For Windows, you must edit the shared lsf.sudoers file.


Configuration to specify the eauth user account

On UNIX hosts, the eauth executable runs under the account of the primary LSF administrator. You can modify this behavior by specifying a different trusted user account. For Windows hosts, you do not need to modify the default behavior because eauth runs under the service account, which is always a trusted, secure account.

File

Parameter and syntax

Description

lsf.sudoers

LSF_EAUTH_USER=user_name

  • UNIX only

  • The eauth executable runs under the account of the specified user rather than the account of the LSF primary administrator

  • You must edit the lsf.sudoers file on all hosts within the cluster and specify the same user name


Configuration to enable Kerberos authentication

To install and configure Kerberos authentication, refer to the information included with your Kerberos integration package provided by Platform Computing Inc..
Restriction:
Kerberos authentication is supported only for UNIX and Linux hosts, and only on the following operating systems:
  • AIX 4

  • Alpha 4.x

  • IRIX 6.5

  • Linux 2.x

  • Solaris 2.x


Configuration file

Parameter and syntax

Behavior

lsf.conf

LSF_AUTH=eauth

  • Enables external authentication

LSF_AUTH_DAEMONS=y | Y

  • Enables daemon authentication when external authentication is enabled

LSF_DAEMON_WRAP=y | Y

  • Required for Kerberos authentication

  • mbatchd, sbatchd, and RES run the executable LSF_SERVERDIR/daemons.wrap

lsf.sudoers

LSF_EAUTH_USER=root

  • for Kerberos authentication, the eauth executable must run under the root account

  • You must edit the lsf.sudoers file on all hosts within the cluster and specify the same user name

LSF_LOAD_PLUGINS=y | Y

  • Required for Kerberos authentication when plug-ins are used instead of the daemon wrapper script

  • LSF loads plug-ins from the directory LSB_LIBDIR

LSF_EEXEC_USER=root

  • Required for Kerberos authentication. The parameter LSF_DAEMON_WRAP must also be set to y or Y.

  • The eexec executable provided with the Kerberos integration runs under the root account


External authentication commands

Commands for submission


Command

Description

All LSF commands

  • If the parameter LSF_AUTH=eauth in the file lsf.conf, LSF daemons authenticate users and hosts—as configured in the eauth executable—before executing an LSF command

  • If external authentication is enabled and the parameter LSF_AUTH_DAEMONS=Y in the file lsf.conf, LSF daemons authenticate each other as configured in the eauth executable


Commands to monitor

Not applicable: There are no commands to monitor the behavior of this feature.

Commands to control

Not applicable: There are no commands to control the behavior of this feature.

Commands to display configuration


Command

Description

badmin showconf

  • Displays all configured parameters and their values set in lsf.conf or ego.conf that affect mbatchd and sbatchd.

    Use a text editor to view other parameters in the lsf.conf or ego.conf configuration files.

  • In a MultiCluster environment, badmin showconf only displays the parameters of daemons on the local cluster.


Use a text editor to view the lsf.sudoers configuration file.