2.5. User Authentication

xGT’s user authentication can be configured to use two mechanisms:

  • Linux’s Pluggable Authentication Modules (PAM) system to support multiple authentication sources.

  • Generic Security Service Application Program Interface (GSSAPI) to support Kerberos single-sign-on authentication.

xGT supports using PAM to authenticate users and retrieve user group membership based on different authentication services available on an installed Linux system. Both UNIX and LDAP can be used to define the users and groups.

For username password authentication, the username and password provided by an xGT user in their Python connection object are passed directly to the PAM authentication service (or services) configured on the Linux system running the xGT server application (xgtd daemon).

For Kerberos authentication, the user will have obtained tickets using a client utility such as kinit. The xGT client will then request Kerberos tickets specifically to authenticate against the service principal for the xGT server they are connecting to.

For more information on how a user will pass credentials to the client see User Authentication.

When a user is authenticated, a session is created, access to the xGT server is granted, and the user’s group membership is retrieved and used to populate their set of security labels. The session will persist while the Python client connection is maintained to the server for a given session lifetime as configured by security.session_ttl. Note that further actions on the xGT server are now subject to access control validation.

2.5.1. Group Membership

The xgtd daemon derives group membership for the user from the groups reported to it by Linux and PAM. For the pam_unix module, these correspond to the UNIX groups set up by the system administrator on the local Linux system running xgtd. For the pam_ldap module, the groups reported back to xGT might not exist on the local Linux system, but on a remote LDAP server. The GSSAPI mechanism doesn’t provide a way to determine groups, so one of the PAM modules must still be used to setup groups. Group membership will be mapped to the security labels configured by the administrator of the server instance. For more discussion on security labels and their mapping see User Labels and Validation.

2.5.2. PAM Setup

xGT supports using PAM to do no authentication or username / password authentication using either UNIX or LDAP. PAM configuration for xGT is typically set up in a system file located at /etc/pam.d/xgtd.

2.5.2.1. No Authentication

If running xGT in an exploratory capacity or as a single-user server, one may want to bypass the user authentication step. In that case a user would want to use the pam_permit module:

#
# /etc/pam.d/xgtd - specify the PAM behavior for xgtd
#

auth       required     pam_permit.so
account    required     pam_permit.so
session    required     pam_permit.so

Warning

Using pam_permit is insecure and should be used with caution.

The pam_permit module simply authenticates any given username and password. User groups can still be retrieved if xgtd is given a valid UNIX user (a valid password is not necessary to retrieve the groups).

2.5.2.2. UNIX User Password Authentication

xGT supports using UNIX users to authenticate. This setup allows users already configured as UNIX users in the system to authenticate to the xGT server. Users would use their regular Linux user identification and password to authenticate against xGT. The following sample PAM configuration file illustrates that case:

#
# /etc/pam.d/xgtd - specify the PAM behavior for xgtd
#

auth       required     pam_unix.so
account    required     pam_unix.so
session    required     pam_unix.so

With the pam_unix module, a user’s group membership will be determined by the user’s UNIX groups membership.

2.5.2.3. LDAP User Password Authentication

xGT can be deployed to authenticate against the Lightweight Directory Access Protocol (LDAP) enterprise-level directory service. PAM on xGT’s supported Linux platforms provides a module to interface to an LDAP directory server for authentication: PAM-LDAP (found as the pam_ldap.so shared library on Linux platforms).

The Linux server running the xgtd daemon should be configured as a client of the LDAP server and the Name Service Switch (NSS) service should be configured to validate users and groups from LDAP as well. The addition of these two services allows for xGT to authenticate users existing in the LDAP directory without them needing to have a UNIX account on the local Linux server running xGT. A sample configuration file for setting up xGT to authenticate against LDAP sources is as follows:

#
# /etc/pam.d/xgtd - specify the PAM behavior for xgtd
#

auth       required     pam_ldap.so
account    required     pam_ldap.so
session    required     pam_ldap.so

By default xGT uses an insecure channel for its remote connection. Secure Sockets Layer (SSL) should be enabled in a production environment where a server expects remote client connections. For information on setting up SSL with xGT see Using an SSL Secure Channel.

2.5.3. GSSAPI Setup

xGT implements an interface for Kerberos-based single-sign-on authentication through the use of the GSSAPI libraries. In this framework, users authenticate against a third party Authentication Server (AS), which communicates to a Key Distribution Center (KDC) server. In many cases, the AS and KDC servers run on the same host. If the client’s credentials are correct, the KDC server returns a timestamped Ticket Granting Ticket (TGT) back to the client. When the client wants to communicate to the xGT server, it request validation against the Ticket Granting Service (TGS). When configured to use Kerberos authentication, the xGT server automatically registers with the TGS using a service principal name. After verifying the tickets provided by the client, the TGS issues a service-specific ticket and session keys back to the client. The client then proceeds to send those to the xGT server.

The user identity is derived from the Kerberos ticket information automatically by the xGT server. The identity corresponds to the initiator of the Kerberos connection. Group membership is determined in the same manner as described in Section Group Membership based on the user’s identity.

2.5.3.1. Kerberos Configuration

The Kerberos configuration on the xGT client and server machines must be set so that they are on the same Kerberos realm. Typically, a Kerberos realm corresponds to the internet domain (or a sub-domain) of the enterprise’s network. Realms are specified using a capital letter form of the domains such as TROVARES.COM. In addition, both the xGT client and server must have access to the same Key Distribution Center (KDC) server(s).

A typical configuration for the MIT Kerberos 5 framework would be as follows (specified in the file /etc/krb5.conf):

[libdefaults]
     default_realm = TROVARES.COM
...
[realms]
     TROVARES.COM = {
             kdc = kdc.trovares.com
             ...
     }

2.5.3.2. xGT Server Configuration for Kerberos

When running the xGT server, the configuration variable security.use_kerberos must be set to true. By default, xgtd uses the network name of the host machine prefixed by the string xgtd/ as the name of the Kerberos service principal it listens on: e.g. xgtd/xgtd_server@TROVARES.COM. The service principal to use can be specified using the configuration variable security.server_krb_principal if the default is not acceptable.

Typically, the xGT server itself is executed by a non-root user on the host machine: e.g. user xgtd. By default, non-root users do not have access to reading the Kerberos configuration, in particular the list of principals that can authenticate against it. For this reason, xgtd needs a list of the principals that can authenticate against it in a file that is readable by the user running the xGT server. In addition, there must be an entry in that list for the xgtd service principal corresponding to that network host (e.g. xgtd/xgtd_server@TROVARES.COM). The list of principals is specified in a keytab file:

slot

KVNO

Principal

1

3

alice@TROVARES.COM

2

3

bob@TROVARES.COM

3

3

charlie@TROVARES.COM

4

3

xgtd/xgtd_server@TROVARES.COM

The xGT server will look for a keytab file specified by the KRB5_KTNAME environment variable. The default value of the KRB5_KTNAME variable on an installed xGT server is “FILE:/etc/xgtd/xgtd.keytab”. The file must be readable by the user running the xGT server.

keytab files can be generated using the ktadd command in the kadmin utility on the Kerberos server. More information on Kerberos configuration and keytab files can be found at: https://web.mit.edu/kerberos/krb5-latest/doc/index.html.

Details on how the client must connect to use Kerberos authentication are in Section Kerberos Authentication.