pam_cockpit_cert - Man Page
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.
See Also
cockpit.conf(5), cockpit-tls(8), pam.d(5), sssd(8), sssd-ifp(5)
Author
Cockpit has been written by many contributors[4].
Bugs
Please send bug reports to either the distribution bug tracker or the upstream bug tracker[5].
Notes
- FreeIPA
https://www.freeipa.org - Active Directory
https://en.wikipedia.org/wiki/Active_Directory - FreeIPA User Certificates documentation
https://www.freeipa.org/page/V4/User_Certificates - contributors
https://github.com/cockpit-project/cockpit/ - upstream bug tracker
https://github.com/cockpit-project/cockpit/issues/new