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

pam_cockpit_cert                                   03/23/2020                                PAM_COCKPIT_CERT(8)