PAM_COCKPIT_CERT(8)

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.

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

1.  FreeIPA
    https://www.freeipa.org

2.  Active Directory
    https://en.wikipedia.org/wiki/Active_Directory

3.  FreeIPA User Certificates documentation
    https://www.freeipa.org/page/V4/User_Certificates

4.  contributors
    https://github.com/cockpit-project/cockpit/

5.  upstream bug tracker
    https://github.com/cockpit-project/cockpit/issues/new