Linux PAM_GSS module (pam_gss)

Owned by Alex Perez Mendez
Last updated: Sept 30, 2021
4 min read

The Linux PAM GSS module (pam_gss)  brings Moonshot compatibility to PAM, allowing Moonshot-based authentication for any application that supports PAM as the authentication backend.

Notably, you can use this module for logging in the Linux Console and in Display Managers such as GDM.

Contents

PAM works in a way that is not recommended with Moonshot. The client device is not under the direct control of the user, and with pam_gss the device is both the client and the server. The consequence of this is that the user's credentials (NAI and password) are exposed directly to a device which is not the user's. Thus, this should only be deployed where the implications and the risk are fully understood:

  • Deployers should understand that the credentials of users using the device could be exposed on that device.
  • Users should understand that their credential could be exposed and should thus do it only on devices managed by organisations they trust.

Use this module only if you understand the consequences.

Note: We provide a TOTP module for FreeRADIUS that allows adding a second factor to the authentication, mitigating the security risk.

1. System Preparation

1.1. Add the Moonshot libraries

If you have not already done so, you first need to follow the instructions on how to configure a Install Moonshot Libraries on a Linux Server

2. Installation Instructions

2.1. Install pam_gss

Install the pam_gss packages using one of the following commands, according to your OS distribution.

CentOS / RH / SL 
yum install pam_gss
Debian / Ubuntu / Raspbian 
apt-get install libpam-gss
Alpine Linux 
apk add pam-gss

2.2. Configure the .gss_eap_authorized_anchors file

Since the PAM module does not make use of the Moonshot UI, a static list of IDP's certificate fingerprints needs to be configured in order to avoid pam_gss accepting a malicious entity impersonating end user's IDP.

That is achieved by creating the file .gss_eap_authorized_anchors in the /root directory. Its format is as follows:

REALM:FINGERPRINT
REALM2:FINGERPRINT2
REALM3:FINGERPRINT3
[...]

The realm and fingerprint portions are case-insensitive. The fingerprint is the server fingerprint, the realm is the same as the realm in the ID Selector.

3. Configuration Instructions

pam_gss is configured by including the following line in the desired /etc/pam.d/ configuration file, right after the execution of the pam_unix module.

auth	sufficient	pam_gss.so ignore_unknown_user mech=1.3.6.1.5.5.15.1.1.18 try_first_pass

The configuration file depends on the application and OS you are trying to configure. In particular:

3.1. Linux console

Edit the indicated file for your system to make it match the following stanzas:

  • RH / CentOS / SL

    /etc/pam.d/system-auth
    ...
auth        required      pam_env.so
auth        sufficient    pam_unix.so try_first_pass nullok
auth        sufficient    pam_gss.so ignore_unknown_user mech=1.3.6.1.5.5.15.1.1.18 try_first_pass
...

  • Debian / Ubuntu / Raspbian

    /etc/pam.d/common-auth
    ...
# here are the per-package modules (the "Primary" block)
auth    sufficient  pam_unix.so nullok_secure
auth	sufficient	pam_gss.so ignore_unknown_user mech=1.3.6.1.5.5.15.1.1.18 try_first_pass
...
  • Alpine Linux
    /etc/pam.d/base-auth
    ...
# basic PAM configuration for Alpine.

auth		required	pam_env.so
auth		required	pam_unix.so	nullok_secure
auth	    sufficient	pam_gss.so ignore_unknown_user mech=1.3.6.1.5.5.15.1.1.18 try_first_pass
...

3.2. GDM

Edit the indicated file for your system to make it match the following stanzas:

  • RH / CentOS / SL

    /etc/pam.d/password-auth
    ...
auth        required      pam_env.so
auth        sufficient    pam_unix.so try_first_pass nullok
auth        sufficient    pam_gss.so ignore_unknown_user mech=1.3.6.1.5.5.15.1.1.18 try_first_pass
...

    SElinux

    If SElinux is in Enforcing mode, GDM will not be able to access to /root/.gss_eap_authorized_anchors.

    You can workaround this limitation by running GDM in permissive mode, using the following command:

    semanage permissive -a xdm_t

  • Debian / Ubuntu / Raspbian

    /etc/pam.d/common-auth
    ...
# here are the per-package modules (the "Primary" block)
auth    sufficient      pam_unix.so nullok_secure
auth	sufficient	pam_gss.so ignore_unknown_user mech=1.3.6.1.5.5.15.1.1.18 try_first_pass
...
    /etc/pam.d/gdm-password
    ...
auth    requisite       pam_nologin.so
# Commented out since pam_gss requires this to be true
# auth	required	pam_succeed_if.so user != root quiet_success
@include common-auth
...

Screensaver

If the screensaver locks the screen, you won't be able to unlock it using your password, as it expect's the password of the local account instead. As a workaround, you must use the "Login as a different user" and log in again. This will actually unlock the session rather than creating a new one.

4. Account mapping

When you authenticate using your federated identity, it must be mapped into a local account in the system. For doing so, read our General account mapping advice page before you go any further to get an overview of the general options available for mapping federation provided identities to local accounts.

Then refer to our Configure a Linux Server's Attribute Resolution page.

5. Customising the value of GSS-Acceptor-Service-Name 

By default, pam_gss uses host as the default value for GSS-Acceptor-Service-Name attribute. This is the same value used by SSH and other applications. If you want to be able to distinguish between them in your RP proxy or IDP, you can change this by adding the service_name=value to the pam_gss.so line. For example

/etc/pam.d/common-auth
auth	sufficient	pam_gss.so ignore_unknown_user mech=1.3.6.1.5.5.15.1.1.18 try_first_pass service_name=pam

6. Logging in using pam_gss

  1. When the application requires a username, use your full NAI (e.g. johnsmith@example.com).
  2. When the application requires a password, use your password as usual.
    1. If you are using the Moonshot 2FA module, you must use your password concatenated with your OTP code (e.g. mypasswdendshere054448)
  3. If successful, you should be logged in as the local user that your account is mapped to (see previous section).

Ensure that the account that the user is being mapped to (via whatever method) actually exists beforehand!