'\" t
.\"     Title: pam_cockpit_cert
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/30/2021
.\"    Manual: pam_cockpit_cert
.\"    Source: pam_cockpit_cert
.\"  Language: English
.\"
.TH "PAM_COCKPIT_CERT" "8" "04/30/2021" "pam_cockpit_cert" "pam_cockpit_cert"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pam_cockpit_cert \- PAM module for authenticating to Cockpit with a client certificate
.SH "DESCRIPTION"
.PP
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\*(Aqs equally possible to import certificates directly into the web browser\&.
.PP
This requires the host to be in an Identity Management domain like
\m[blue]\fBFreeIPA\fR\m[]\&\s-2\u[1]\d\s+2
or
\m[blue]\fBActive Directory\fR\m[]\&\s-2\u[2]\d\s+2, which can associate certificates to users\&. See the
\m[blue]\fBFreeIPA User Certificates documentation\fR\m[]\&\s-2\u[3]\d\s+2
for details\&. The
sssd\-dbus
package must be installed for this to work\&.
.PP
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\&.
.PP
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\&.
.SH "OPTIONS"
.PP
\fBdebug\fR
.RS 4
This option will turn on debug logging to syslog\&.
.RE
.SH "RESULT CODES"
.PP
\fBsuccess\fR
.RS 4
Certificate is present, mapped to a user, and the user name is set in the PAM stack\&.
.RE
.PP
\fBuser_unknown\fR
.RS 4
Certificate is present, but sssd cannot map it to a user\&. Effectively a definitive failed authentication\&.
.RE
.PP
\fBignore\fR
.RS 4
The PAM user is already set, so this authentication process does not use a certificate\&.
.RE
.PP
\fBunavail\fR
.RS 4
sssd is not available for mapping certificates to users\&.
.RE
.PP
\fBservice_err\fR
.RS 4
sssd is available in general, but responded with an invalid answer\&. This might indicate a compatibility problem with a future version\&.
.RE
.SH "USAGE IN PAM CONFIGURATION"
.PP
The module should be added to service PAM configurations like this:
.sp
.if n \{\
.RS 4
.\}
.nf
\-auth      [success=done new_authtok_reqd=done user_unknown=die default=ignore]   pam_cockpit_cert\&.so
# fallback authentication methods such as pam_unix
   
.fi
.if n \{\
.RE
.\}
.PP
This
\fImust\fR
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,
\fIif\fR
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\&.
.SH "SEE ALSO"
.PP
\fBcockpit.conf\fR(5),
\fBcockpit-tls\fR(8),
\fBpam.d\fR(5),
\fBsssd\fR(8),
\fBsssd-ifp\fR(5)
.SH "AUTHOR"
.PP
Cockpit has been written by many
\m[blue]\fBcontributors\fR\m[]\&\s-2\u[4]\d\s+2\&.
.SH "BUGS"
.PP
Please send bug reports to either the distribution bug tracker or the
\m[blue]\fBupstream bug tracker\fR\m[]\&\s-2\u[5]\d\s+2\&.
.SH "NOTES"
.IP " 1." 4
FreeIPA
.RS 4
\%https://www.freeipa.org
.RE
.IP " 2." 4
Active Directory
.RS 4
\%https://en.wikipedia.org/wiki/Active_Directory
.RE
.IP " 3." 4
FreeIPA User Certificates documentation
.RS 4
\%https://www.freeipa.org/page/V4/User_Certificates
.RE
.IP " 4." 4
contributors
.RS 4
\%https://github.com/cockpit-project/cockpit/
.RE
.IP " 5." 4
upstream bug tracker
.RS 4
\%https://github.com/cockpit-project/cockpit/issues/new
.RE