From 574517cb165eb3d89dc3492895cf830a9bde67b2 Mon Sep 17 00:00:00 2001 From: Florence Blanc-Renaud Date: Jun 01 2023 06:20:37 +0000 Subject: Design for passkey support Related: https://pagure.io/freeipa/issue/9261 Signed-off-by: Florence Blanc-Renaud Reviewed-By: Alexander Bokovoy --- diff --git a/doc/designs/index.rst b/doc/designs/index.rst index 39c1622..9172407 100644 --- a/doc/designs/index.rst +++ b/doc/designs/index.rst @@ -29,5 +29,6 @@ FreeIPA design documentation external-idp/idp-api.md random-serial-numbers.md client-install-pkinit.md + passkeys.md prci_checker.md rbcd.md diff --git a/doc/designs/passkeys.md b/doc/designs/passkeys.md new file mode 100644 index 0000000..0a4c5b1 --- /dev/null +++ b/doc/designs/passkeys.md @@ -0,0 +1,268 @@ +# Passkey authentication + +## Overview + +Traditional authentication with a password is not considered secure enough +by many companies or government agencies. Alternate and more secure +solutions exist, among which the use of passkeys, where the private +key is stored on the device and the server only needs to know the public +key. + +For the purpose of this feature, passkey is a FIDO2 compatible device supported +by the libfido2 library. For more details, refer to +https://fidoalliance.org/fido2/ + +The goal of this feature is to use a passkey to authenticate a user +against IPA. + +The project will be jointly developed by SSSD and IPA: + +- IPA provides the interface to store the user's public credentials +- IPA provides the interface to configure passkey settings +- SSSD performs the actual authentication + +TBD: link to https://sssd.io/ design for the passkey feature + +## Use Cases + +- The administrator or the user registers a passkey into IPA, associated +to a user account. The registration process stores a description of the passkey +bound to IPA deployment and requires a direct communication with the passkey +device. Alternatively the description string can be obtained through the SSSD +registration tool and added without the presence of the passkey device. +- The user is then able to authenticate to any IPA enrolled host using the +passkey. The first round of passkey integration is targeting a login to +services implementing login with the help of PAM library locally on the host. +This includes direct console or graphical desktop login and authentication +to PAM-protected shell services like 'su' or 'sudo'. To access remote services +a Kerberos ticket can be obtained and used against those services later. + +## How to Use + +### Configuration of the passkey settings by the administrator + +The administrator is able to specify common settings that will apply: + +- require user verification during authentication (On/Off/Default): + - On: require user verification during authentication (PIN for instance). + - Off: do not require user verification during authentication. + - Default: fallback to the passkey’s default behavior. + +### Registration of credentials + +The user can register credentials for himself, or the admin (or any user with +the permission "System: Manage User passkeys") can register +credentials for another user. + +During the registration process, it is possible to specify +- a COSE type: `es256`, `rs256` or `eddsa` +- request user verification: true or false +the authentication will force to execute the user verification check even if +the passkey settings do not set this flag. If credentials are registered without +the flag, the global passkey settings apply. + +When the passkey credential is registered, a relaying party (RP) is set to be +the IPA domain (e.g. ipa.test). While using a domain-wide relaying party +reduces access control capabilities for individual application's use of the +registered passkey, IPA provides own access control mechanisms to be layered +on top. We choose to combine existing authorization features of IPA with an +ease of use for the passkeys. + +### Authentication + +#### Console or desktop authentication + +The user has a passkey in his possession that was already registered to IPA +and has physical access to a machine enrolled in IPA. + +At Gnome login, he types his username and inserts the device. + +At console login, he types his username and inserts the device. + +SSSD validates the credentials and checks that the passkey allows +authentication. + +#### PAM-protected service access + +The following example is using the su command, but would apply to any other +PAM-protected service. + +The user passkeyuser has a passkey in his possession that was already +registered to IPA and has physical access to a machine enrolled in IPA. He +is already logged into the machine as a different user and wants to perform +su to authenticate as passkeyuser. + +Inside a terminal, he inserts his device and enters the `su - passkeyuser` +command. + +SSSD validates the credentials and checks that the passkey allows +authentication. + + +## Design + +### Configuration of the passkey settings + +A new LDAP entry stores the passkey configuration and needs a new objectclass +and a new attributetype: +``` +dn: cn=passkeyconfig,cn=etc,$BASEDN +objectclass: top +objectclass: nsContainer +objectclass: ipapasskeyconfigObject +cn: passkeyconfig +ipaRequireUserVerification: default +``` + +The object class allows a single attribute, require user verification, +which is mandatory, single valued, and stores a string (on, off, default). +The LDAP entry is added when IPA server is installed or when the server is +upgraded to a version supporting passkeys. + +### Storage of the passkey mapping + +The passkey mapping is stored directly in the user entry. It needs a +new auxiliary objectclass and a new attributetype. + +Note: a first proposal intended to store the value in the ipasshpubkey +attribute, but this attribute has a special handling (a new fingerprint is +calculated for each public key and added into the attribute sshpubkeyfp) +which makes it unsuitable for storing values that are not keys. + +The attribute is multi valued, optional. + +``` +dn: uid=idmuser,cn=users,cn=accounts,dc=ipa,dc=test +uid: idmuser +... +objectClass: top +objectClass: person +... +objectClass: ipapasskeyuser +ipapasskey: passkey:9S87qLk8/RxYJ3skwwYduomAM+/HDtz41N0+w/vRL6aGKJkLMsg+2OhO0E8pK5DuO1KmdK61K8PmH7jiYuOqbg==,9YE1s/f7J47h2A/DXCVFWulqoBXFzCSxcbGEBadkpSUFjwUudhPLnPUTv2qNamakXJgRYCZQ7vpS/t5zXMLnkw== +``` + +The passkey mapping has the format `passkey:credentialid,pubkey`. credential +ID and public key are obtained during the registration phase, for instance +by calling SSSD helper process `sssctl passkey-exec --register` or the IPA Command +`ipa user-add-passkey LOGIN --register`. + + +### Access control + +#### Permissions + +- New permission created for writing the passkey configuration: +`System: Modify Passkey Configuration`. Granted to the Privilege `Passkey Administrators` +- New permission created for reading the passkey configuration: +`System: Read Passkey configuration`. Granted to all authenticated users. +- New permission for managing passkey mapping: +`System: Manage Passkey Mappings`. Granted to the Privilege: `Passkey Administrators` + +- Extend existing permission" `System: Read User IPA Attributes`: +allow read access to the ipapasskey attribute (granted to all authenticated +users). This attribute is not sensitive as it contains only public data. + +#### Self-service Permission + +- New self-service permission for managing their own passkey mapping: +`Users can manage their own passkey mappings` + +#### Privilege + +- New privilege `Passkey Administrators` with the permissions `System: Modify Passkey Configuration` and `System: Manage Passkey Mappings`. + +By default only members of the admins group are allowed to modify the passkey +settings or another user's passkeys. + +## Implementation + +### LDAP schema + +New objectclass and attribute for the passkey configuration object: +``` +attributeTypes: ( 2.16.840.1.113730.3.8.23.26 NAME 'ipaRequireUserVerification' DESC 'require passkey user verification' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE X-ORIGIN 'IPA v4.10') +objectclasses: ( 2.16.840.1.113730.3.8.24.8 NAME 'ipaPasskeyConfigObject' DESC 'IPA passkey global config options' AUXILIARY MUST ipaRequireUserVerification X-ORIGIN 'IPA v4.10') +``` + +New objectclass and attribute for the passkey mapping: +``` +attributeTypes: ( 2.16.840.1.113730.3.8.23.27 NAME 'ipapasskey' DESC 'Passkey mapping' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'IPA v4.10' ) +objectclasses: ( 2.16.840.1.113730.3.8.24.9 NAME 'ipaPasskeyUser' DESC 'IPA passkey user' AUXILIARY MAY ipapasskey X-ORIGIN 'IPA v4.10') +``` + +### Indices + +No need to add a new index for ipapasskey as the search performed by SSSD +will use a filter based on the user uid. + + +## Feature Management + +### UI + +- A new tab will be added below "Policy", at the same level as `Host-Based Access Control`, `Sudo`, `SELInux User Maps`, `Password Policies` and `Kerberos Ticket Policy`, with the label `Passkey Configuration`. + +It will allow to configure the attribute `Require User Verification`, with a radio button: `on`, `off` or `default`. + +- In the `User` facet, a new field will be added, below `SSH public keys`, with the label `Passkey mappings`, and will display the values, or allow to add a new value. + +Note: since the Web browser may be running on a non-enrolled host without +the required packages, the WebUI will probably need specific javascript code +to register a key by inserting it on the machine where the browser is +running. + +Investigations TBD regarding the possible solutions. The key registration +using the WebUI will not be part of the original implementation. + + +### CLI + +| Command | Options | Description | +| --- | ----- | --- | +| **Passkey configuration** | | | +| passkeyconfig-show | | This command displays the Passkey settings | +| passkeyconfig-mod | --require-user-verification=['on', 'off', 'default'] | This command modifies the Passkey settings | +| **User Mapping** | | | +| user-add-passkey | LOGIN [PASSKEY...] | This command does not require the device to be inserted and can directly add the mapping data, obtained through another mean (for instance through sssctl passkey-exec --register) | +| user-add-passkey | LOGIN --register [--cose-type=['es256', 'rs256', 'eddsa']] [--require-user-verification=BOOL] | This command requires the insertion of the device, performs the registration with the specified cose type + user verification requirement, and adds the mapping data to the user entry | +| user-remove-passkey | LOGIN PASSKEY... | | +| user-show | LOGIN | This command displays the passkey mapping if set, with the label `Passkey mapping` | +| stageuser-add-passkey | LOGIN [PASSKEY...] | This command does not require the device to be inserted and can directly add the mapping data, obtained through another mean (for instance through sssctl passkey-exec --register) | +| stageuser-add-passkey | LOGIN --register [--cose-type=['es256', 'rs256', 'eddsa']] [--require-user-verification=BOOL] | This command requires the insertion of the passkey, performs the registration with the specified cose type + user verification requirement, and adds the mapping data to the user entry | +| stageuser-remove-passkey | LOGIN PASSKEY... | | +| stageuser-show | LOGIN | This command displays the passkey mapping if set, with the label `Passkey mapping` | + + +### Configuration + +The global settings can be read or modified using `ipa passkeyconfig-[show|mod]`. + +## Upgrade + +During upgrade, the new LDAP schema is automatically added and replicated to the replicas. + +The upgrade must create the Passkey configuration entry if it does not already exist, with value='default' for the 'require user verification' setting (meaning it will use the default value from each key). + +## Test plan + +XMLRPC tests must validate the new CLI. + +## Troubleshooting and debugging + +SSSD provides 2 new commands that can be used for debugging: +* `/usr/sbin/sssctl passkey-exec --register`: documented and supported. This command can be run as root only. +* `/usr/libexec/sssd/passkey_child --register`: internally called by `sssctl passkey-exec --register`. This command does not require root access. + +IPA command `ipa user-add-passkey --register` internally calls `passkey_child`. + +SSSD's helper `passkey_child` provides debugging options: + +`passkey_child --register --username=passkeyuser --domain=ipa.test --debug-level=9 --logger=stderr --debug-libfido2` + +SSSD's helper can also be used to test the authentication: + +`passkey_child --authenticate --username=passkeyuser --domain=ipa.test --public-key=... --key-handle=... --debug-level=9 --logger=stderr --debug-libfido2` + +SSSD logs are available in `/var/log/sssd/`. +