Skip to content

Commit eaab5be

Browse files
ikerexxeikerexxe
committed
design pages: Passwordless-GDM integration
Passwordless authentication from the GUI. Signed-off-by: Iker Pedrosa <[email protected]>
1 parent dd73964 commit eaab5be

File tree

2 files changed

+282
-0
lines changed

2 files changed

+282
-0
lines changed

‎src/design-pages/passwordless_gdm.rst‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
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+
"code": "$code",
163+
"message": "$message"
164+
}
165+
}
166+
167+
Examples for the two messages are defined in the following lines.
168+
169+
Password
170+
++++++++
171+
.. code-block:: json
172+
173+
{
174+
"auth-selection": {
175+
"mechanisms": {
176+
"password": {
177+
"name": "Password",
178+
"role": "password",
179+
"prompt": "Password:"
180+
}
181+
},
182+
"priority": [
183+
"password"
184+
]
185+
}
186+
}
187+
188+
EIdP
189+
++++
190+
.. code-block:: json
191+
192+
{
193+
"auth-selection": {
194+
"mechanisms": {
195+
"eidp": {
196+
"name": "Web Login",
197+
"role": "eidp",
198+
"init_prompt": "Login",
199+
"link_prompt": "Login online with another device",
200+
"uri": "https://short.url.com/1234",
201+
"code": "1234"
202+
}
203+
},
204+
"priority": [
205+
"eidp"
206+
]
207+
}
208+
}
209+
210+
Password and EIdP
211+
+++++++++++++++++
212+
.. code-block:: json
213+
214+
{
215+
"auth-selection": {
216+
"mechanisms": {
217+
"password":
218+
{
219+
"name": "Password",
220+
"role": "password",
221+
"prompt": "Password:"
222+
},
223+
"eidp": {
224+
"name": "Web Login",
225+
"role": "eidp",
226+
"init_prompt": "Login",
227+
"link_prompt": "Login online with another device",
228+
"uri": "https://short.url.com/tmp",
229+
"code": "1234"
230+
}
231+
},
232+
"priority": [
233+
"eidp",
234+
"password"
235+
]
236+
}
237+
}
238+
239+
GDM reply
240+
+++++++++
241+
.. code-block:: json
242+
243+
{
244+
"auth-selection": {
245+
"code": 0,
246+
"message": "Ok"
247+
}
248+
}
249+
250+
Smart card
251+
++++++++++
252+
253+
Passkey
254+
+++++++
255+
256+
Authors
257+
-------
258+
* Iker Pedrosa <[email protected]>
259+
* Ray Strode <[email protected]>

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
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+
21+
note across: The authentication workflow varies depending on the mechanism used,\nso this diagram is expanded by authentication mechanism
22+
23+
@enduml

0 commit comments

Comments
 (0)