NAME¶

pam_cockpit_cert - PAM module for authenticating to Cockpit with a client certificate

DESCRIPTION¶

pam_cockpit_cert provides an PAM authentication module for identifying and authenticating users through a TLS client certificate. Commonly this is provided by a smart card, but it's equally possible to import certificates directly into the web browser.

This requires the host to be in an Identity Management domain like FreeIPA[1] or Active Directory[2], which can associate certificates to users. See the FreeIPA User Certificates documentation[3] for details. The sssd-dbus package must be installed for this to work.

In authentication mode, pam_cockpit_cert is invoked with the user name unset. It checks whether the web browser presented and validated a TLS client certificate to Cockpit. If so, that gets passed to sssd. If that can successfully map the certificate to a user, this PAM module sets the user name and succeeds, which should be treated as a sufficient authentication.

Cockpit does not use certificate based authentication by default; it has to be explicitly enabled in cockpit.conf. If not enabled, this PAM module is inert and always returns ignore.

OPTIONS¶

debug

This option will turn on debug logging to syslog.

RESULT CODES¶

success

Certificate is present, mapped to a user, and the user name is set in the PAM stack.

user_unknown

Certificate is present, but sssd cannot map it to a user. Effectively a definitive failed authentication.

ignore

The PAM user is already set, so this authentication process does not use a certificate.

unavail

sssd is not available for mapping certificates to users.

service_err

sssd is available in general, but responded with an invalid answer. This might indicate a compatibility problem with a future version.

USAGE IN PAM CONFIGURATION¶

The module should be added to service PAM configurations like this:

-auth      [success=done new_authtok_reqd=done user_unknown=die default=ignore]   pam_cockpit_cert.so
# fallback authentication methods such as pam_unix

This must be first module in the "auth" stack as it sets the PAM_USER variable on successful mapping of a certificate to a user name. Also, if a certificate is being presented, then failure to map that to a user should usually be treated as fatal, without falling back to other methods such as password. Other errors should usually be considered non-fatal, and just try the next authentication method in the stack.