diff --git a/designs/mfa-device-enrollment-process.rst b/designs/mfa-device-enrollment-process.rst new file mode 100644 index 000000000..3b246418a --- /dev/null +++ b/designs/mfa-device-enrollment-process.rst @@ -0,0 +1,97 @@ +Multiple Device Enrollment Workflow +----------------------------------- + +As we continue to develop kanidm, we'll add support for OTP and Webauthn. A constraint we must +consider is that many webauthn devices are tied to (bound) to the device. This could be a yubikey +nano that may not pluginto a phone, a built in touch id, a tpm, or even a softtoken in firefox. + +As a result, we must have a way for an account to be able to authenticate the addition of a new +webauthn token *without* being able to provide an existing token to the new device. + +We must also consider that the process should be simple and easy to follow. We have taken +inspiration from existing systems to support this. + +Situation +========= + +We have a user with a device E(nrolled), and a device N(ew) that they wish to be able to use. + +Each device contains a unique webauthn device that is inseperable from the device. + +Each device may be connected to a seperate Kanidm instance - IE we can not assume that +the data in the system may be point-in-time consistent due to replication as an asynchronous +process. + +The process "will" come under attack. It must not be an avenue for partial credential disclosure. + +The enrollment process and credentials issued must only be for the purpose of enrollment of webauthn +devices and must not grant any other permission. + +The overall security of the system must not be "lowered" to allow the enrollment to occur. + +Schema +====== + +MFAEnrollmentToken: TOTP/HOTP seed/counter +WebauthnCredential: Storage of a webauthn pubkey +WebauthnCredentialRequest: Storage of a webauthn pubkey that is awaiting acceptance. + +Preparation +=========== + +When the account is created, a private recovery TOTP seed is created and stored in the account +as an MFAEnrollmentToken. + +This is so that all replicas in the topology have the same credential tokens available. + +The "login" page has an "enroll new device" option. + +A claim for self write to webauthn registration must exist. + +Process +======= + +Device N is accessed (which is not yet enrolled). The "enroll new device" option is selected. + +The username is entered. This goes to the next step + +The TOTP is requested. + +On the enrolled device E, the TOTP is "generated". It is then typed into device N. + +Device N then prompts for the user primary password (if exists). + +The session is logged in with a single self-write claim that allows creation of a webauthn pub key +on the account. alt: the server just does the change as internal system to bypassword acp, but I think +there are some attack vectors here. + +The session has a 5 minute timelimit. + +Device N challenged for a webauthn registration process. The public key is written to the account's +WebauthCredentialRequest. + +On Device E, the user approves the WebauthCredentialRequest, and it is moved from WebauthCredentialRequest +to WebauthnCredential. It may now be used. + + +Possible Issues +=============== + +TOTP has a time window, and if we are near that window it may not last long enough. We could consider +HOTP instead, assuming that the HOTP has not been accessed +- 10 times between the replicas. + +Handling for accounts with no user primary password. + +Device E may be connected to a different replica to Device N, so there may be a delay in requested +token enrollments from appearing in the request list. + +Device N may have to wait for replication back for the WebauthnCredential to appear. + + +Possible Changes +================ + +Do not require the approval step, as an OTP has already been provided, which is evidence of possesion +of an account which has sufficent permissions. + +