From e2e9880fcce7f1fb7834a93c802dc0c481a9759d Mon Sep 17 00:00:00 2001 From: Iker Pedrosa Date: Wed, 9 Oct 2024 10:42:25 +0200 Subject: [PATCH] man: add `sssd-passkey.5` Include a new man page for passkey to explain the behaviour of `user_verification` option in the different scenarios. It is a complex option, so it has been decided to add a table to simplify its understanding. Signed-off-by: Iker Pedrosa --- contrib/sssd.spec.in | 4 ++ src/man/Makefile.am | 4 ++ src/man/po/po4a.cfg | 1 + src/man/sssd-passkey.5.xml | 128 +++++++++++++++++++++++++++++++++++++ src/man/sssd.conf.5.xml | 15 +++-- 5 files changed, 145 insertions(+), 7 deletions(-) create mode 100644 src/man/sssd-passkey.5.xml diff --git a/contrib/sssd.spec.in b/contrib/sssd.spec.in index bd57f830461..f42d32a0ad0 100644 --- a/contrib/sssd.spec.in +++ b/contrib/sssd.spec.in @@ -759,6 +759,9 @@ do sss-certmap*) echo \%lang\(${lang}\) \%{_mandir}/${man}\* >> libsss_certmap.lang ;; + sssd-passkey*) + echo \%lang\(${lang}\) \%{_mandir}/${man}\* >> sssd_passkey.lang + ;; *) echo \%lang\(${lang}\) \%{_mandir}/${man}\* >> sssd.lang ;; @@ -1111,6 +1114,7 @@ install -D -p -m 0644 %{SOURCE1} %{buildroot}%{_sysusersdir}/sssd.conf %{_udevrulesdir}/90-sssd-token-access.rules %endif %config(noreplace) %{_sysconfdir}/krb5.conf.d/sssd_enable_passkey +%{_mandir}/man5/sssd-passkey.5* %endif %if %{use_sssd_user} diff --git a/src/man/Makefile.am b/src/man/Makefile.am index fcbd086e76d..5299e4b028f 100644 --- a/src/man/Makefile.am +++ b/src/man/Makefile.am @@ -130,6 +130,10 @@ man_MANS += sssd-files.5 endif # BUILD_FILES_PROVIDER endif +if BUILD_PASSKEY +man_MANS += sssd-passkey.5 +endif + $(builddir)/src/man/sssd_user_name.include: @mkdir -p $(builddir)/src/man @echo -n $(SSSD_USER) > $(builddir)/src/man/sssd_user_name.include diff --git a/src/man/po/po4a.cfg b/src/man/po/po4a.cfg index de60095f771..71388c916ff 100644 --- a/src/man/po/po4a.cfg +++ b/src/man/po/po4a.cfg @@ -30,6 +30,7 @@ [type:docbook] sssd-systemtap.5.xml $lang:$(builddir)/$lang/sssd-systemtap.5.xml [type:docbook] sssd-ldap-attributes.5.xml $lang:$(builddir)/$lang/sssd-ldap-attributes.5.xml [type:docbook] sssd_krb5_localauth_plugin.8.xml $lang:$(builddir)/$lang/sssd_krb5_localauth_plugin.8.xml +[type:docbook] sssd-passkey.5.xml $lang:$(builddir)/$lang/sssd-passkey.5.xml [type:docbook] include/autofs_attributes.xml $lang:$(builddir)/$lang/include/autofs_attributes.xml opt:"-k 0" [type:docbook] include/service_discovery.xml $lang:$(builddir)/$lang/include/service_discovery.xml opt:"-k 0" [type:docbook] include/upstream.xml $lang:$(builddir)/$lang/include/upstream.xml opt:"-k 0" diff --git a/src/man/sssd-passkey.5.xml b/src/man/sssd-passkey.5.xml new file mode 100644 index 00000000000..4a8b857ec4e --- /dev/null +++ b/src/man/sssd-passkey.5.xml @@ -0,0 +1,128 @@ + + + +SSSD Manual pages + + + + + sssd-passkey + 5 + File Formats and Conventions + + + + sssd-passkey + SSSD passkey options + + + + DESCRIPTION + + This manual page describes the specifics for configuration of + passkey for + + sssd + 8 + . + Refer to the FILE FORMAT section of the + + sssd.conf + 5 + manual page for detailed syntax information. + + + + CONFIGURATION OPTIONS + + + + user_verification (boolean) + + + Enable or disable the requirement for user + verification (i.e. PIN, fingerprint) on the passkey + device during authentication. + + + Three different actors come into play when deciding + whether to request user verification: LDAP server, + sssd.conf + 5 + option and the passkey device itself. + + + If the IPA provider is used and online, Kerberos + based passkey authentication is available, the + server-side settings are applied for all passkey + usages. For other cases the settings in + sssd.conf are used. This + includes passkey authentication with any other + provider; and the IPA provider in case online + authentication is not available and local passkey + is allowed by the option + local_auth_policy = enable:passkey. + + + The interaction of the + user_verification option and + the passkey device option is explained in the + following table: + + + + + + + + + user_verificationDevice + Result + + + + True + User verification is configured + User verification is requested + + + True + User verification is not configured + + User verification is requested; however, the + authentication is expected to fail if the device is + not replaced with a device where authentication is + configured during the authentication process. + + + + False + User verification is configured + + sssd automatically detects it during device query + and user verification is requested + + + + False + User verification is not configured + User verification is not requested + + + + If 'enter' is pressed at the PIN prompt for user + verification without typing any characters, then + SSSD falls back from passkey to password + authentication. + + + + + + + + + + + diff --git a/src/man/sssd.conf.5.xml b/src/man/sssd.conf.5.xml index 860ab94cf1e..97e40fe7a5c 100644 --- a/src/man/sssd.conf.5.xml +++ b/src/man/sssd.conf.5.xml @@ -727,15 +727,16 @@ Enable or disable the user verification (i.e. PIN, fingerprint) - during authentication. If enabled, the - PIN will always be requested. + during authentication. - The default is that the key settings - decide what to do. In the IPA or - kerberos pre-authentication case, - this value will be overwritten by the - server. + See + + sssd-passkey + 5 + to + understand the behaviour of this option + in the different scenarios.