Skip to content

Commit 2d5f0e0

Browse files
ikerexxeikerexxe
committed
design pages: Passwordless-GDM integration
Passwordless authentication from the GUI. Signed-off-by: Iker Pedrosa <ipedrosa@redhat.com>
1 parent 8b310f3 commit 2d5f0e0

File tree

2 files changed

+391
-0
lines changed

2 files changed

+391
-0
lines changed

‎src/design-pages/passwordless_gdm.rst

+367
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,367 @@
1+
Passkey authentication Kerberos integration
2+
=======================================================
3+
4+
Related ticket(s):
5+
------------------
6+
* https://github.com/SSSD/sssd/issues/7069
7+
8+
Problem statement
9+
-----------------
10+
Passwordless authentication is becoming increasingly popular. SSSD and FreeIPA
11+
already provide several authentication mechanisms which make use of it:
12+
`Smart Cards <https://sssd.io/design-pages/smartcards.html>`__,
13+
`External Identity Providers <https://freeipa.readthedocs.io/en/latest/designs/external-idp/external-idp.html>`__ (EIdP)
14+
and `Passkeys <https://sssd.io/design-pages/passkey_kerberos.html>`__.
15+
Unfortunately, the integration of these mechanisms into the graphical interface
16+
leaves much to be desired. Some of them may work in a degraded mode, while
17+
others can’t be used at all.
18+
19+
SSSD and the GUI should be better integrated to make all these authentication
20+
mechanisms effortless for the user. This would increase the overall security of
21+
the system, by providing the benefits of these authentication mechanisms, i.e.
22+
passwordless, MFA, etc.
23+
24+
SSSD and `GDM <https://wiki.gnome.org/Projects/GDM>`__ are working together to
25+
provide a set of interfaces that can be used to enable these authentication
26+
mechanisms in Linux’s GUI. While the initial work targets SSSD-GDM integration,
27+
the objective is that these interfaces can be used by any other desktop
28+
environment.
29+
30+
The use of new tools to authenticate users, such as 2FA, U2F and FIDO2, is
31+
becoming increasingly popular. Currently SSSD provides local authentication of
32+
a centrally managed user with passkeys, but it doesn't provide any way to
33+
authenticate remotely to a system. This diminishes the value provided by SSSD
34+
in some environments like big companies and governments, where remote
35+
authentication is a common pattern.
36+
37+
Use cases
38+
---------
39+
* As a centrally managed user, I want to choose the authentication mechanism
40+
to login from the graphical interface so that I can select the one that best
41+
suits my needs.
42+
43+
* As a centrally managed user, I want to use an external identity provider
44+
(IdP) to login from the graphical interface so that the user interface is
45+
easy to use and consistent across all authentication mechanisms in the
46+
distribution.
47+
48+
* As a centrally managed user, I want to select the smart card identity to
49+
login from the graphical interface so that the authentication is performed
50+
with the correct credentials.
51+
52+
* As a centrally managed user, I want to use a passkey to login from the
53+
graphical interface so that the user interface is easy to use and consistent
54+
across all authentication mechanisms in the distribution.
55+
56+
* As a centrally managed user, I want to get notified when the passkey
57+
authentication has been performed locally so that I am aware that the user
58+
experience might be affected.
59+
60+
Solution overview
61+
-----------------
62+
The objective is to provide usable workflows for users to authenticate in the
63+
graphical interface using passwordless authentication mechanisms. To do this,
64+
we first need to design a communication protocol between SSSD and GDM.
65+
66+
The APIs can be implemented in two ways, either by implementing them in
67+
`D-BUS <https://www.freedesktop.org/wiki/Software/dbus/>`__, or by extending
68+
the PAM conversation to include the new authentication mechanisms. There
69+
doesn’t seem to be any advantage in using D-BUS, whereas a PAM-level API would
70+
give other desktop environments the ability to offer similar features. For this
71+
reason, the GDM PAM extension has been selected.
72+
73+
GDM already provides an interface in ``/usr/include/gdm/gdm-pam-extensions.h``
74+
that SSSD supports. Unfortunately extending this binary interface is hard, so
75+
a JSON based protocol is used. It’s easier to extend and manage, making it
76+
easier to adapt the different packages involved. The previous implementation
77+
will continue to be maintained for backward compatibility.
78+
79+
As for the workflows, they have to provide the user with a way to interact
80+
(i.e. insert the hardware token or enter the PIN), while allowing communication
81+
with the device or the external provider. Each authentication mechanism needs
82+
its own sequence diagram definition, which will be explained later in this
83+
document.
84+
85+
Implementation details
86+
----------------------
87+
88+
Sequence diagram
89+
****************
90+
The communication between SSSD and GDM is explained in the following sequence
91+
diagram.
92+
93+
.. uml:: ../diagrams/passwordless-gdm-auth.pu
94+
95+
* GDM prompts the user for their username.
96+
97+
* The user initiates the login procedure by entering their username.
98+
99+
* GDM starts the PAM conversation.
100+
101+
* GDM starts the authentication process in SSSD.
102+
103+
* pam_sss communicates with the PAM responder to resolve the user.
104+
105+
* PAM responder resolves the username and obtains, among other things, the
106+
available authentication methods and the prompting strings.
107+
108+
* PAM responder prepares the JSON message with the available authentication
109+
mechanisms, the prompts and the user credentials to be requested
110+
(check format in :ref:`data`).
111+
112+
* PAM responder returns this information to pam_sss.
113+
114+
* pam_sss wraps the JSON message in the PAM conversation using the macros
115+
provided by GDM in ``/usr/include/gdm/gdm-custom-json-pam-extension.h``.
116+
117+
* GDM prompts the user for the user credentials, and at the bottom of the
118+
screen it shows the available authentication mechanisms. If the user selects
119+
another method, GDM already has all the information needed to request the
120+
user credentials for this authentication mechanism.
121+
122+
* The authentication workflow continues, but varies depending on the selected
123+
authentication mechanism. This will be explained separately for each
124+
mechanism.
125+
126+
.. _data:
127+
128+
Data
129+
****
130+
In addition, the messages exchanged follow the JSON standard. SSSD provides the available authentication mechanisms in the following message:
131+
132+
.. code-block:: json
133+
134+
{
135+
"auth-selection": {
136+
"mechanisms": {
137+
"$mech1": {
138+
"name": "$name1",
139+
"role": "$role1",
140+
"selectable": true,
141+
"msg1": "$msg1"
142+
},
143+
"$mech2": {
144+
"name": "$name2",
145+
"role": "$role2",
146+
"selectable": true,
147+
"msg1": "$msg2",
148+
"msg2": "$msg3"
149+
}
150+
},
151+
"priority": [
152+
"$role2",
153+
"$role1"
154+
]
155+
}
156+
}
157+
158+
The field meaning is as follows:
159+
160+
* name: the mechanism name that will be shown in the login screen.
161+
* role: the authentication mechanism. It can be password, EIdP, smartcard or
162+
passkey.
163+
* selectable: whether the authentication mechanism should be shown up in the
164+
login screen as an explicitly selectable option. By default it is set to
165+
``true``.
166+
167+
GDM answers with the result for the previous JSON message processing:
168+
169+
.. code-block:: json
170+
171+
{
172+
"auth-selection": {
173+
"status": "$status",
174+
"mech": {
175+
"data1": "$data1",
176+
"data2": "$data2"
177+
}
178+
}
179+
}
180+
181+
Examples for the two messages are defined in the following lines.
182+
183+
Password
184+
++++++++
185+
SSSD provides the available authentication mechanisms:
186+
187+
.. code-block:: json
188+
189+
{
190+
"auth-selection": {
191+
"mechanisms": {
192+
"password": {
193+
"name": "Password",
194+
"role": "password",
195+
"selectable": true,
196+
"prompt": "Password:"
197+
}
198+
},
199+
"priority": [
200+
"password"
201+
]
202+
}
203+
}
204+
205+
GDM replies with the selection:
206+
207+
.. code-block:: json
208+
209+
{
210+
"auth-selection": {
211+
"status": "Ok",
212+
"password": {
213+
"password": "ThePassword"
214+
}
215+
}
216+
}
217+
218+
EIdP
219+
++++
220+
SSSD provides the available authentication mechanisms:
221+
222+
.. code-block:: json
223+
224+
{
225+
"auth-selection": {
226+
"mechanisms": {
227+
"eidp": {
228+
"name": "Web Login",
229+
"role": "eidp",
230+
"selectable": true,
231+
"init_prompt": "Login",
232+
"link_prompt": "Log in online with another device",
233+
"uri": "https://short.url.com/1234",
234+
"code": "1234",
235+
"timeout": 300
236+
}
237+
},
238+
"priority": [
239+
"eidp"
240+
]
241+
}
242+
}
243+
244+
GDM replies with the selection:
245+
246+
.. code-block:: json
247+
248+
{
249+
"auth-selection": {
250+
"status": "Ok",
251+
"eidp": {}
252+
}
253+
}
254+
255+
Smart card
256+
++++++++++
257+
SSSD provides the available authentication mechanisms:
258+
259+
.. code-block:: json
260+
261+
{
262+
"auth-selection": {
263+
"mechanisms": {
264+
"smartcard:1": {
265+
"name": "smartcard ID1",
266+
"role": "smartcard",
267+
"selectable": true,
268+
"prompt": "Enter PIN:"
269+
},
270+
"smartcard:2": {
271+
"name": "smartcard ID2",
272+
"role": "smartcard",
273+
"selectable": true,
274+
"instruction": "Enter PIN in reader"
275+
}
276+
},
277+
"priority": [
278+
"smartcard:1",
279+
"smartcard:2"
280+
]
281+
}
282+
}
283+
284+
The field meaning is as follows:
285+
286+
* prompt: GDM prompts the user to input the PIN.
287+
* instruction: GDM indicates the user to follow instructions, e.g. to enter the
288+
PIN in the reader.
289+
290+
GDM replies with the selection:
291+
292+
.. code-block:: json
293+
294+
{
295+
"auth-selection": {
296+
"status": "Ok",
297+
"smartcard:1": {
298+
"pin": "ThePIN"
299+
}
300+
}
301+
}
302+
303+
All authentication mechanisms
304+
+++++++++++++++++++++++++++++
305+
SSSD provides the available authentication mechanisms:
306+
307+
.. code-block:: json
308+
309+
{
310+
"auth-selection": {
311+
"mechanisms": {
312+
"password": {
313+
"name": "Password",
314+
"role": "password",
315+
"selectable": true,
316+
"prompt": "Password:"
317+
},
318+
"eidp": {
319+
"name": "Web Login",
320+
"role": "eidp",
321+
"selectable": true,
322+
"init_prompt": "Login",
323+
"link_prompt": "Login online with another device",
324+
"uri": "https://short.url.com/tmp",
325+
"code": "1234"
326+
},
327+
"smartcard:1": {
328+
"name": "smartcard ID1",
329+
"role": "smartcard",
330+
"selectable": true,
331+
"prompt": "Enter PIN:"
332+
}
333+
},
334+
"priority": [
335+
"eidp",
336+
"smartcard:1",
337+
"password"
338+
]
339+
}
340+
}
341+
342+
GDM replies with the selection, as explained in the preceding sections.
343+
344+
Passkey
345+
+++++++
346+
347+
Authentication mechanisms priority
348+
**********************************
349+
350+
The priority for the authentication mechanisms set in the JSON message is a
351+
hardcoded value and follows the next priority:
352+
353+
* EIdP
354+
* Password
355+
356+
PAM responder options
357+
*********************
358+
PAM responder provides the new ``pam_json_services`` option to enable the
359+
aforementioned authentication method selection mechanism. This is a list of all
360+
PAM service files allowed to use it. Application maintainers can use it to let
361+
SSSD know they support the json protocol, and that SSSD should provide the
362+
available authentication methods using it.
363+
364+
Authors
365+
-------
366+
* Iker Pedrosa <ipedrosa@redhat.com>
367+
* Ray Strode <halfline@redhat.com>

‎src/diagrams/passwordless-gdm-auth.pu

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
@startuml
2+
actor User
3+
participant GDM
4+
box SSSD
5+
participant pam_sss
6+
participant "PAM responder"
7+
end box
8+
9+
GDM -> User: Login prompt
10+
User -> GDM: Input username
11+
GDM -> pam_sss: pam_start(service, user, conv, pamh)
12+
GDM -> pam_sss: pam_authenticate(pamh, flags, argc, argv)
13+
pam_sss -> "PAM responder": sss_cli_send_req()
14+
note over "PAM responder": Resolves the username and obtains, among other things,\nthe available authentication methods and the prompting\nstrings.
15+
16+
"PAM responder" -> "PAM responder": format_json(auth_mechanisms, prompts)
17+
"PAM responder" -> pam_sss: sss_cli_recv_rep(..., json_msg)
18+
pam_sss -> GDM: pam_conv(1, message, &reply, appdata_ptr)
19+
GDM -> User: Prompt user credentials\nand available authentication\nmechanisms
20+
User -> GDM: Choose authentication mechanism and input data
21+
GDM -> GDM: format_json(auth_selection, data)
22+
GDM -> pam_sss: return pam_conv(reply)
23+
24+
@enduml

0 commit comments

Comments
 (0)