mirror of
https://salsa.debian.org/freeipa-team/freeipa.git
synced 2024-12-25 08:21:05 -06:00
574517cb16
Related: https://pagure.io/freeipa/issue/9261 Signed-off-by: Florence Blanc-Renaud <flo@redhat.com> Reviewed-By: Alexander Bokovoy <abokovoy@redhat.com>
269 lines
12 KiB
Markdown
269 lines
12 KiB
Markdown
# 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/`.
|
||
|