'\" t .\" Title: pam_sss .\" Author: The SSSD upstream - https://github.com/SSSD/sssd/ .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 02/10/2021 .\" Manual: SSSD Manual pages .\" Source: SSSD .\" Language: English .\" .TH "PAM_SSS" "8" "02/10/2021" "SSSD" "SSSD Manual pages" .\" ----------------------------------------------------------------- .\" * 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_sss \- PAM module for SSSD .SH "SYNOPSIS" .HP \w'\fBpam_sss\&.so\fR\ 'u \fBpam_sss\&.so\fR [\fIquiet\fR] [\fIforward_pass\fR] [\fIuse_first_pass\fR] [\fIuse_authtok\fR] [\fIretry=N\fR] [\fIignore_unknown_user\fR] [\fIignore_authinfo_unavail\fR] [\fIdomains=X\fR] [\fIallow_missing_name\fR] [\fIprompt_always\fR] [\fItry_cert_auth\fR] [\fIrequire_cert_auth\fR] .SH "DESCRIPTION" .PP \fBpam_sss\&.so\fR is the PAM interface to the System Security Services daemon (SSSD)\&. Errors and results are logged through \fBsyslog(3)\fR with the LOG_AUTHPRIV facility\&. .SH "OPTIONS" .PP \fBquiet\fR .RS 4 Suppress log messages for unknown users\&. .RE .PP \fBforward_pass\fR .RS 4 If \fBforward_pass\fR is set the entered password is put on the stack for other PAM modules to use\&. .RE .PP \fBuse_first_pass\fR .RS 4 The argument use_first_pass forces the module to use a previous stacked modules password and will never prompt the user \- if no password is available or the password is not appropriate, the user will be denied access\&. .RE .PP \fBuse_authtok\fR .RS 4 When password changing enforce the module to set the new password to the one provided by a previously stacked password module\&. .RE .PP \fBretry=N\fR .RS 4 If specified the user is asked another N times for a password if authentication fails\&. Default is 0\&. .sp Please note that this option might not work as expected if the application calling PAM handles the user dialog on its own\&. A typical example is \fBsshd\fR with \fBPasswordAuthentication\fR\&. .RE .PP \fBignore_unknown_user\fR .RS 4 If this option is specified and the user does not exist, the PAM module will return PAM_IGNORE\&. This causes the PAM framework to ignore this module\&. .RE .PP \fBignore_authinfo_unavail\fR .RS 4 Specifies that the PAM module should return PAM_IGNORE if it cannot contact the SSSD daemon\&. This causes the PAM framework to ignore this module\&. .RE .PP \fBdomains\fR .RS 4 Allows the administrator to restrict the domains a particular PAM service is allowed to authenticate against\&. The format is a comma\-separated list of SSSD domain names, as specified in the sssd\&.conf file\&. .sp NOTE: If this is used for a service not running as root user, e\&.g\&. a web\-server, it must be used in conjunction with the \(lqpam_trusted_users\(rq and \(lqpam_public_domains\(rq options\&. Please see the \fBsssd.conf\fR(5) manual page for more information on these two PAM responder options\&. .RE .PP \fBallow_missing_name\fR .RS 4 The main purpose of this option is to let SSSD determine the user name based on additional information, e\&.g\&. the certificate from a Smartcard\&. .sp The current use case are login managers which can monitor a Smartcard reader for card events\&. In case a Smartcard is inserted the login manager will call a PAM stack which includes a line like .sp .if n \{\ .RS 4 .\} .nf auth sufficient pam_sss\&.so allow_missing_name .fi .if n \{\ .RE .\} .sp In this case SSSD will try to determine the user name based on the content of the Smartcard, returns it to pam_sss which will finally put it on the PAM stack\&. .RE .PP \fBprompt_always\fR .RS 4 Always prompt the user for credentials\&. With this option credentials requested by other PAM modules, typically a password, will be ignored and pam_sss will prompt for credentials again\&. Based on the pre\-auth reply by SSSD pam_sss might prompt for a password, a Smartcard PIN or other credentials\&. .RE .PP \fBtry_cert_auth\fR .RS 4 Try to use certificate based authentication, i\&.e\&. authentication with a Smartcard or similar devices\&. If a Smartcard is available and the service is allowed for Smartcard authentication the user will be prompted for a PIN and the certificate based authentication will continue .sp If no Smartcard is available or certificate based authentication is not allowed for the current service PAM_AUTHINFO_UNAVAIL is returned\&. .RE .PP \fBrequire_cert_auth\fR .RS 4 Do certificate based authentication, i\&.e\&. authentication with a Smartcard or similar devices\&. If a Smartcard is not available the user will be prompted to insert one\&. SSSD will wait for a Smartcard until the timeout defined by p11_wait_for_card_timeout passed, please see \fBsssd.conf\fR(5) for details\&. .sp If no Smartcard is available after the timeout or certificate based authentication is not allowed for the current service PAM_AUTHINFO_UNAVAIL is returned\&. .RE .SH "MODULE TYPES PROVIDED" .PP All module types (\fBaccount\fR, \fBauth\fR, \fBpassword\fR and \fBsession\fR) are provided\&. .PP If SSSD\*(Aqs PAM responder is not running, e\&.g\&. if the PAM responder socket is not available, pam_sss will return PAM_USER_UNKNOWN when called as \fBaccount\fR module to avoid issues with users from other sources during access control\&. .SH "RETURN VALUES" .PP PAM_SUCCESS .RS 4 The PAM operation finished successfully\&. .RE .PP PAM_USER_UNKNOWN .RS 4 The user is not known to the authentication service or the SSSD\*(Aqs PAM responder is not running\&. .RE .PP PAM_AUTH_ERR .RS 4 Authentication failure\&. Also, could be returned when there is a problem with getting the certificate\&. .RE .PP PAM_PERM_DENIED .RS 4 Permission denied\&. The SSSD log files may contain additional information about the error\&. .RE .PP PAM_IGNORE .RS 4 See options \fBignore_unknown_user\fR and \fBignore_authinfo_unavail\fR\&. .RE .PP PAM_AUTHTOK_ERR .RS 4 Unable to obtain the new authentication token\&. Also, could be returned when the user authenticates with certificates and multiple certificates are available, but the installed version of GDM does not support selection from multiple certificates\&. .RE .PP PAM_AUTHINFO_UNAVAIL .RS 4 Unable to access the authentication information\&. This might be due to a network or hardware failure\&. .RE .PP PAM_BUF_ERR .RS 4 A memory error occurred\&. Also, could be returned when options use_first_pass or use_authtok were set, but no password was found from the previously stacked PAM module\&. .RE .PP PAM_SYSTEM_ERR .RS 4 A system error occurred\&. The SSSD log files may contain additional information about the error\&. .RE .PP PAM_CRED_ERR .RS 4 Unable to set the credentials of the user\&. .RE .PP PAM_CRED_INSUFFICIENT .RS 4 The application does not have sufficient credentials to authenticate the user\&. For example, missing PIN during smartcard authentication or missing factor during two\-factor authentication\&. .RE .PP PAM_SERVICE_ERR .RS 4 Error in service module\&. .RE .PP PAM_NEW_AUTHTOK_REQD .RS 4 The user\*(Aqs authentication token has expired\&. .RE .PP PAM_ACCT_EXPIRED .RS 4 The user account has expired\&. .RE .PP PAM_SESSION_ERR .RS 4 Unable to fetch IPA Desktop Profile rules or user info\&. .RE .PP PAM_CRED_UNAVAIL .RS 4 Unable to retrieve Kerberos user credentials\&. .RE .PP PAM_NO_MODULE_DATA .RS 4 No authentication method was found by Kerberos\&. This might happen if the user has a Smartcard assigned but the pkint plugin is not available on the client\&. .RE .PP PAM_CONV_ERR .RS 4 Conversation failure\&. .RE .PP PAM_AUTHTOK_LOCK_BUSY .RS 4 No KDC suitable for password change is available\&. .RE .PP PAM_ABORT .RS 4 Unknown PAM call\&. .RE .PP PAM_MODULE_UNKNOWN .RS 4 Unsupported PAM task or command\&. .RE .PP PAM_BAD_ITEM .RS 4 The authentication module cannot handle Smartcard credentials\&. .RE .SH "FILES" .PP If a password reset by root fails, because the corresponding SSSD provider does not support password resets, an individual message can be displayed\&. This message can e\&.g\&. contain instructions about how to reset a password\&. .PP The message is read from the file pam_sss_pw_reset_message\&.LOC where LOC stands for a locale string returned by \fBsetlocale\fR(3)\&. If there is no matching file the content of pam_sss_pw_reset_message\&.txt is displayed\&. Root must be the owner of the files and only root may have read and write permissions while all other users must have only read permissions\&. .PP These files are searched in the directory /etc/sssd/customize/DOMAIN_NAME/\&. If no matching file is present a generic message is displayed\&. .SH "SEE ALSO" .PP \fBsssd\fR(8), \fBsssd.conf\fR(5), \fBsssd-ldap\fR(5), \fBsssd-krb5\fR(5), \fBsssd-simple\fR(5), \fBsssd-ipa\fR(5), \fBsssd-ad\fR(5), \fBsssd-files\fR(5), \fBsssd-sudo\fR(5), \fBsssd-session-recording\fR(5), \fBsss_cache\fR(8), \fBsss_debuglevel\fR(8), \fBsss_obfuscate\fR(8), \fBsss_seed\fR(8), \fBsssd_krb5_locator_plugin\fR(8), \fBsss_ssh_authorizedkeys\fR(8), \fBsss_ssh_knownhostsproxy\fR(8), \fBsssd-ifp\fR(5), \fBpam_sss\fR(8)\&. \fBsss_rpcidmapd\fR(5) \fBsssd-systemtap\fR(5) .SH "AUTHORS" .PP \fBThe SSSD upstream \- https://github\&.com/SSSD/sssd/\fR