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