5. User Authentication¶
xGT’s user authentication can be configured to use three different 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.
Public Key Infrastructure (PKI) certificate-based authentication.
xGT supports using PAM to authenticate users. It can retrieve user group membership based on different directory 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 PKI authentication, the use of SSL and mutual TLS is required (see Using an SSL Secure Channel for more details).
Client x509 certificates must include a userId field if PKI authentication is desired.
The server validates the client’s certificate using information provided on the encrypted channel and extracts its userId field.
If the userId is not empty, then the connection is authenticated and used to compute group membership based on the configured directory services on the system running xGT.
Note that a password or other credentials are not required when using PKI authentication in this manner.
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.
5.1. Group Membership¶
The xgtd daemon derives group membership for the user from the groups reported to it by Linux.
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_sss 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 these mechanisms 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.
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.
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).
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.
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. It is common to deploy LDAP service on an enterprise via the combination of SSSD (System Security Services Daemon) and IPA (Identity, Policy and Audit).
The Linux server running the xgtd daemon should be configured as a client of the LDAP server and the SSSD 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 using SSSD is as follows:
#
# /etc/pam.d/xgtd - specify the PAM behavior for xgtd
#
auth required pam_sss.so
account required pam_sss.so
session required pam_sss.so
More information on SSSD is available at https://sssd.io/docs/introduction.html. More information on IPA is available at https://www.freeipa.org.
Note that these services (SSSD and LDAP) are external to the xgtd daemon.
The SSSD daemon is needed on the machine running xgtd as it provides authentication services to processes running on that machine.
The LDAP daemon can be run on a different machine.
The machine running xgtd becomes a client to the LDAP server.
A straightforward setup of SSSD and IPA enables login access via ssh to the machine running xgtd.
The users’ identity and credentials will be validated against the provided directory for login access to the server running xgtd.
The same identity and credentials will also allow access to the xgtd server.
The file /etc/sssd/sssd.conf controls the behavior of the SSSD daemon on the machine running the xgtd server.
An example setup is as follows:
[sssd]
config_file_version = 2
services = nss, pam, ifp, ssh, sudo
domains = ipa.domain
The critical configuration needed for xgtd to use PAM authentication against the configured LDAP directory server is the services entry requiring the pam service.
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.
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
...
}
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 |
|
2 |
3 |
|
3 |
3 |
|
4 |
3 |
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.
5.4. Encrypted Connections to xGT and PKI Authentication¶
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.
If the server is configured to use mutual TLS, then client connections with an x509 certificate containing a valid userId field can be used for authentication.
This is another mechanism (in addition to Kerberos) to use password-less authentication for xGT.