---
name: "pam_cockpit_cert"
section: "8"
platform: "linux"
package: "cockpit-ws"
version: "239-1"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/pam_cockpit_cert"
---

# pam\_cockpit\_cert(8)

PAM module for authenticating to Cockpit with a client certificate

## 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.conf/5.md), [**cockpit-tls**(8)](/cockpit-tls/8.md), [**pam.d**(5)](/pam.d/5.md), [**sssd**(8)](/sssd/8.md), [**sssd-ifp**(5)](/sssd-ifp/5.md)

## 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