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