"Fossies" - the Fresh Open Source Software Archive

Member "sssd-2.4.2/src/man/pam_sss_gss.8.xml" (19 Feb 2021, 8861 Bytes) of package /linux/misc/sssd-2.4.2.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "pam_sss_gss.8.xml": 2.4.1_vs_2.4.2.

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
    4 <reference>
    5 <title>SSSD Manual pages</title>
    6 <refentry>
    7     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
    8                 href="include/upstream.xml" />
    9 
   10     <refmeta>
   11         <refentrytitle>pam_sss_gss</refentrytitle>
   12         <manvolnum>8</manvolnum>
   13     </refmeta>
   14 
   15     <refnamediv id='name'>
   16         <refname>pam_sss_gss</refname>
   17         <refpurpose>PAM module for SSSD GSSAPI authentication</refpurpose>
   18     </refnamediv>
   19 
   20     <refsynopsisdiv id='synopsis'>
   21         <cmdsynopsis>
   22             <command>pam_sss_gss.so</command>
   23             <arg choice='opt'>
   24                 <replaceable>debug</replaceable>
   25             </arg>
   26         </cmdsynopsis>
   27     </refsynopsisdiv>
   28 
   29     <refsect1 id='description'>
   30         <title>DESCRIPTION</title>
   31         <para>
   32             <command>pam_sss_gss.so</command> authenticates user
   33             over GSSAPI in cooperation with SSSD.
   34         </para>
   35         <para>
   36             This module will try to authenticate the user using the GSSAPI
   37             hostbased service name host@hostname which translates to
   38             host/hostname@REALM Kerberos principal. The
   39             <emphasis>REALM</emphasis> part of the Kerberos principal name is
   40             derived by Kerberos internal mechanisms and it can be set explicitly
   41             in configuration of [domain_realm] section in /etc/krb5.conf.
   42         </para>
   43         <para>
   44             SSSD is used to provide desired service name and to validate the
   45             user's credentials using GSSAPI calls. If the service ticket is
   46             already present in the Kerberos credentials cache or if user's
   47             ticket granting ticket can be used to get the correct service ticket
   48             then the user will be authenticated.
   49         </para>
   50         <para>
   51             If <option>pam_gssapi_check_upn</option> is True (default) then SSSD
   52             requires that the credentials used to obtain the service tickets can
   53             be associated with the user. This means that the principal that owns
   54             the Kerberos credentials must match with the user principal name as
   55             defined in LDAP.
   56         </para>
   57         <para>
   58             To enable GSSAPI authentication in SSSD, set
   59             <option>pam_gssapi_services</option> option in [pam] or domain
   60             section of sssd.conf. The service credentials need to be stored
   61             in SSSD's keytab (it is already present if you use ipa or ad
   62             provider). The keytab location can be set with
   63             <option>krb5_keytab</option> option. See
   64             <citerefentry>
   65                 <refentrytitle>sssd.conf</refentrytitle>
   66                 <manvolnum>5</manvolnum>
   67             </citerefentry> and
   68             <citerefentry>
   69                 <refentrytitle>sssd-krb5</refentrytitle>
   70                 <manvolnum>5</manvolnum>
   71             </citerefentry> for more details on these options.
   72         </para>
   73         <para>
   74             Some Kerberos deployments allow to assocate authentication
   75             indicators with a particular pre-authentication method used to
   76             obtain the ticket granting ticket by the user.
   77             <command>pam_sss_gss.so</command> allows to enforce presence of
   78             authentication indicators in the service tickets before a particular
   79             PAM service can be accessed.
   80         </para>
   81         <para>
   82             If <option>pam_gssapi_indicators_map</option> is set in the [pam] or
   83             domain section of sssd.conf, then SSSD will perform a check of the
   84             presence of any configured indicators in the service ticket.
   85         </para>
   86     </refsect1>
   87 
   88     <refsect1 id='options'>
   89         <title>OPTIONS</title>
   90         <variablelist remap='IP'>
   91             <varlistentry>
   92                 <term>
   93                     <option>debug</option>
   94                 </term>
   95                 <listitem>
   96                     <para>Print debugging information.</para>
   97                 </listitem>
   98             </varlistentry>
   99         </variablelist>
  100     </refsect1>
  101 
  102     <refsect1 id='module_types_provides'>
  103         <title>MODULE TYPES PROVIDED</title>
  104         <para>Only the <option>auth</option> module type is provided.</para>
  105     </refsect1>
  106 
  107     <refsect1 id="return_values">
  108         <title>RETURN VALUES</title>
  109         <variablelist>
  110             <varlistentry>
  111                 <term>PAM_SUCCESS</term>
  112                 <listitem>
  113                     <para>
  114                         The PAM operation finished successfully.
  115                     </para>
  116                 </listitem>
  117             </varlistentry>
  118             <varlistentry>
  119                 <term>PAM_USER_UNKNOWN</term>
  120                 <listitem>
  121                     <para>
  122                         The user is not known to the authentication service or
  123                         the GSSAPI authentication is not supported.
  124                     </para>
  125                 </listitem>
  126             </varlistentry>
  127             <varlistentry>
  128                 <term>PAM_AUTH_ERR</term>
  129                 <listitem>
  130                     <para>
  131                         Authentication failure.
  132                     </para>
  133                 </listitem>
  134             </varlistentry>
  135             <varlistentry>
  136                 <term>PAM_AUTHINFO_UNAVAIL</term>
  137                 <listitem>
  138                     <para>
  139                         Unable to access the authentication information.
  140                         This might be due to a network or hardware failure.
  141                     </para>
  142                 </listitem>
  143             </varlistentry>
  144             <varlistentry>
  145                 <term>PAM_SYSTEM_ERR</term>
  146                 <listitem>
  147                     <para>
  148                         A system error occurred. The SSSD log files may contain
  149                         additional information about the error.
  150                     </para>
  151                 </listitem>
  152             </varlistentry>
  153         </variablelist>
  154     </refsect1>
  155 
  156     <refsect1 id='examples'>
  157         <title>EXAMPLES</title>
  158         <para>
  159             The main use case is to provide password-less authentication in
  160             sudo but without the need to disable authentication completely.
  161             To achieve this, first enable GSSAPI authentication for sudo in
  162             sssd.conf:
  163         </para>
  164         <programlisting>
  165 [domain/MYDOMAIN]
  166 pam_gssapi_services = sudo, sudo-i
  167         </programlisting>
  168         <para>
  169             And then enable the module in desired PAM stack
  170             (e.g. /etc/pam.d/sudo and /etc/pam.d/sudo-i).
  171         </para>
  172         <programlisting>
  173 ...
  174 auth sufficient pam_sss_gss.so
  175 ...
  176         </programlisting>
  177     </refsect1>
  178 
  179     <refsect1 id='troubleshooting'>
  180         <title>TROUBLESHOOTING</title>
  181         <para>
  182             SSSD logs, pam_sss_gss debug output and syslog may contain helpful
  183             information about the error. Here are some common issues:
  184         </para>
  185         <para>
  186             1. I have KRB5CCNAME environment variable set and the authentication
  187             does not work: Depending on your sudo version, it is possible that
  188             sudo does not pass this variable to the PAM environment. Try adding
  189             KRB5CCNAME to <option>env_keep</option> in /etc/sudoers or in your
  190             LDAP sudo rules default options.
  191         </para>
  192         <para>
  193             2. Authentication does not work and syslog contains "Server not
  194             found in Kerberos database": Kerberos is probably not able to
  195             resolve correct realm for the service ticket based on the hostname.
  196             Try adding the hostname directly to
  197             <option>[domain_realm]</option> in /etc/krb5.conf like so:
  198         </para>
  199         <para>
  200             3. Authentication does not work and syslog contains "No Kerberos
  201             credentials available": You don't have any credentials that can be
  202             used to obtain the required service ticket. Use kinit or autheticate
  203             over SSSD to acquire those credentials.
  204         </para>
  205         <para>
  206             4. Authentication does not work and SSSD sssd-pam log contains "User
  207             with UPN [$UPN] was not found." or "UPN [$UPN] does not match target
  208             user [$username].": You are using credentials that can not be mapped
  209             to the user that is being authenticated. Try to use kswitch to
  210             select different principal, make sure you authenticated with SSSD or
  211             consider disabling <option>pam_gssapi_check_upn</option>.
  212         </para>
  213         <programlisting>
  214 [domain_realm]
  215 .myhostname = MYREALM
  216         </programlisting>
  217     </refsect1>
  218 
  219     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" />
  220 
  221 </refentry>
  222 </reference>