pam_cockpit_cert(8)

1PAM_COCKPIT_CERT(8)            pam_cockpit_cert            PAM_COCKPIT_CERT(8)
2
3
4

NAME

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

DESCRIPTION

10       pam_cockpit_cert provides an PAM authentication module for identifying
11       and authenticating users through a TLS client certificate. Commonly
12       this is provided by a smart card, but it's equally possible to import
13       certificates directly into the web browser.
14
15       This requires the host to be in an Identity Management domain like
16       FreeIPA[1] or Active Directory[2], which can associate certificates to
17       users. See the FreeIPA User Certificates documentation[3] for details.
18       The sssd-dbus package must be installed for this to work.
19
20       In authentication mode, pam_cockpit_cert is invoked with the user name
21       unset. It checks whether the web browser presented and validated a TLS
22       client certificate to Cockpit. If so, that gets passed to sssd. If that
23       can successfully map the certificate to a user, this PAM module sets
24       the user name and succeeds, which should be treated as a sufficient
25       authentication.
26
27       Cockpit does not use certificate based authentication by default; it
28       has to be explicitly enabled in cockpit.conf. If not enabled, this PAM
29       module is inert and always returns ignore.
30

OPTIONS

32       debug
33           This option will turn on debug logging to syslog.
34

RESULT CODES

36       success
37           Certificate is present, mapped to a user, and the user name is set
38           in the PAM stack.
39
40       user_unknown
41           Certificate is present, but sssd cannot map it to a user.
42           Effectively a definitive failed authentication.
43
44       ignore
45           The PAM user is already set, so this authentication process does
46           not use a certificate.
47
48       unavail
49           sssd is not available for mapping certificates to users.
50
51       service_err
52           sssd is available in general, but responded with an invalid answer.
53           This might indicate a compatibility problem with a future version.
54

USAGE IN PAM CONFIGURATION

56       The module should be added to service PAM configurations like this:
57
58           -auth      [success=done new_authtok_reqd=done user_unknown=die default=ignore]   pam_cockpit_cert.so
59           # fallback authentication methods such as pam_unix
60
61
62       This must be first module in the "auth" stack as it sets the PAM_USER
63       variable on successful mapping of a certificate to a user name. Also,
64       if a certificate is being presented, then failure to map that to a user
65       should usually be treated as fatal, without falling back to other
66       methods such as password. Other errors should usually be considered
67       non-fatal, and just try the next authentication method in the stack.
68

AUTHOR

73       Cockpit has been written by many contributors[4].
74

BUGS

76       Please send bug reports to either the distribution bug tracker or the
77       upstream bug tracker[5].
78

NOTES

80        1. FreeIPA
81           https://www.freeipa.org
82
83        2. Active Directory
84           https://en.wikipedia.org/wiki/Active_Directory
85
86        3. FreeIPA User Certificates documentation
87           https://www.freeipa.org/page/V4/User_Certificates
88
89        4. contributors
90           https://github.com/cockpit-project/cockpit/
91
92        5. upstream bug tracker
93           https://github.com/cockpit-project/cockpit/issues/new
94
95
96
97pam_cockpit_cert                  05/16/2021               PAM_COCKPIT_CERT(8)