freeipa/doc/designs/passkeys.md

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

SSSD has defined the implementation in two design pages:

• Local passkey authentication.
• Passkey Kerberos integration

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 (True/False):
  • True: require user verification during authentication (PIN for instance).
  • False: do not require user verification during authentication. The default value is True.

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.
• credential type: server-side or discoverable Discoverable credentials do not require to first identify the user.

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.

If user verification is enabled, then the PIN is prompted. 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: True

The object class allows a single attribute, require user verification, which is mandatory, single valued, and stores a boolean (TRUE, FALSE). The LDAP entry is added when IPA server is installed or when the server is upgraded to a version supporting passkeys, with a default value = TRUE.

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' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 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 check box: on or off.

• 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=BOOL	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='true' for the 'require user verification' setting.

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/.