Skip to content

Commit 8a027cb

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 8a027cb

File tree

2 files changed

+367
-0
lines changed

2 files changed

+367
-0
lines changed

‎src/design-pages/passwordless_gdm.rst

+343
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,343 @@
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+
"msg1": "$msg1"
141+
},
142+
"$mech2": {
143+
"name": "$name2",
144+
"role": "$role2",
145+
"msg1": "$msg2",
146+
"msg2": "$msg3"
147+
}
148+
},
149+
"priority": [
150+
"$role2",
151+
"$role1"
152+
]
153+
}
154+
}
155+
156+
GDM answers with the result for the previous JSON message processing:
157+
158+
.. code-block:: json
159+
160+
{
161+
"auth-selection": {
162+
"status": "$status",
163+
"mech": {
164+
"data1": "$data1",
165+
"data2": "$data2"
166+
}
167+
}
168+
}
169+
170+
Examples for the two messages are defined in the following lines.
171+
172+
Password
173+
++++++++
174+
SSSD provides the available authentication mechanisms:
175+
176+
.. code-block:: json
177+
178+
{
179+
"auth-selection": {
180+
"mechanisms": {
181+
"password": {
182+
"name": "Password",
183+
"role": "password",
184+
"prompt": "Password:"
185+
}
186+
},
187+
"priority": [
188+
"password"
189+
]
190+
}
191+
}
192+
193+
GDM replies with the selection:
194+
195+
.. code-block:: json
196+
197+
{
198+
"auth-selection": {
199+
"status": "Ok",
200+
"password": {
201+
"password": "ThePassword"
202+
}
203+
}
204+
}
205+
206+
EIdP
207+
++++
208+
SSSD provides the available authentication mechanisms:
209+
210+
.. code-block:: json
211+
212+
{
213+
"auth-selection": {
214+
"mechanisms": {
215+
"eidp": {
216+
"name": "Web Login",
217+
"role": "eidp",
218+
"init_prompt": "Login",
219+
"link_prompt": "Log in online with another device",
220+
"uri": "https://short.url.com/1234",
221+
"code": "1234",
222+
"timeout": 300
223+
}
224+
},
225+
"priority": [
226+
"eidp"
227+
]
228+
}
229+
}
230+
231+
GDM replies with the selection:
232+
233+
.. code-block:: json
234+
235+
{
236+
"auth-selection": {
237+
"status": "Ok",
238+
"eidp": {}
239+
}
240+
}
241+
242+
Smart card
243+
++++++++++
244+
SSSD provides the available authentication mechanisms:
245+
246+
.. code-block:: json
247+
248+
{
249+
"auth-selection": {
250+
"mechanisms": {:
251+
"smartcard:1": {
252+
"name": "smartcard ID1",
253+
"role": "smartcard",
254+
"prompt": "Enter PIN:"
255+
},
256+
"smartcard:2": {
257+
"name": "smartcard ID2",
258+
"role": "smartcard",
259+
"prompt": "Enter PIN:"
260+
}
261+
},
262+
"priority": [
263+
"smartcard:1",
264+
"smartcard:2"
265+
]
266+
}
267+
}
268+
269+
GDM replies with the selection:
270+
271+
.. code-block:: json
272+
273+
{
274+
"auth-selection": {
275+
"status": "Ok",
276+
"smartcard:1": {
277+
"pin": "ThePIN"
278+
}
279+
}
280+
}
281+
282+
All authentication mechanisms
283+
+++++++++++++++++++++++++++++
284+
SSSD provides the available authentication mechanisms:
285+
286+
.. code-block:: json
287+
288+
{
289+
"auth-selection": {
290+
"mechanisms": {
291+
"password": {
292+
"name": "Password",
293+
"role": "password",
294+
"prompt": "Password:"
295+
},
296+
"eidp": {
297+
"name": "Web Login",
298+
"role": "eidp",
299+
"init_prompt": "Login",
300+
"link_prompt": "Login online with another device",
301+
"uri": "https://short.url.com/tmp",
302+
"code": "1234"
303+
},
304+
"smartcard:1": {
305+
"name": "smartcard ID1",
306+
"role": "smartcard",
307+
"prompt": "Enter PIN:"
308+
}
309+
},
310+
"priority": [
311+
"eidp",
312+
"smartcard:1",
313+
"password"
314+
]
315+
}
316+
}
317+
318+
GDM replies with the selection, as explained in the preceding sections.
319+
320+
Passkey
321+
+++++++
322+
323+
Authentication mechanisms priority
324+
**********************************
325+
326+
The priority for the authentication mechanisms set in the JSON message is a
327+
hardcoded value and follows the next priority:
328+
329+
* EIdP
330+
* Password
331+
332+
PAM responder options
333+
*********************
334+
PAM responder provides the new ``pam_json_services`` option to enable the
335+
aforementioned authentication method selection mechanism. This is a list of all
336+
PAM service files allowed to use it. Application maintainers can use it to let
337+
SSSD know they support the json protocol, and that SSSD should provide the
338+
available authentication methods using it.
339+
340+
Authors
341+
-------
342+
* Iker Pedrosa <ipedrosa@redhat.com>
343+
* 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)