User Handle

This description is derived in large part from the W3C’s recommendation, Web Authentication: An API for accessing Public Key Credentials Level 1.

The user handle represents the mapping of a public key credential to a user account with the Relying Party (RP). As such, it is the RP that sets its value, user.id.

Characteristics of user.id

  • Must not contain information that could identify the user.

  • Opaque byte sequence, maximum length = 64

  • Must be pseudo random

  • Must not include personal identifying information

An authenticator maps the user handle to a private key. Authentication and authorization decisions are made on the basis of the user.id (not the user.name or user.displayName, which can be understood as nicknames in the sense of RFC 8266). The user.id and other user account attributes reside in the PublicKeyCredentialUserEntity dictionary, which is used when creating a new credential, as shown here:

{
   dictionary PublicKeyCredentialUserEntity : PublicKeyCredentialEntity {
       required BufferSource   id;
       required DOMString      displayName;
   };
}

The user handle is required for usernameless passwordless authentication with discoverable credentials, i.e., credentials that live on the security key. The example below illustrates how registration of the key creates the user.id underlying the user handle that is verified during authorization. In this example, at no point after registration is either a username or a password required. Note that the user.id is not generally created along with the credential key pair. The user.id may be created when registering the first credential for an account, but in general it is a constant identifier stored in the user’s account, and the same user.id value is used when registering any future credentials.

Note

Universal second factor authentication (U2F) does not support the user handle.

Example

When user John registers his security key with a Microsoft online service (the RP), the service prompts John to allow the service to create and register a credential on the key. That service identifies the pairing (the public key credential on John’s key + John’s account) by means of the user handle, by setting the value for the ``user.id`` to the following, for example:

{
   user.id = 69 b3 72 54 75 20 ee 1f 91 7e 62 06 86 87 18 94
   02 94 1f f0 31 75 d7 d9 91 7c d5 f6 2c c3 cd 39
   b2 f9 ee 15 2f 13 8a f7 fa 29 bc fe ab 35 c4 aa
   89 40 b5 54 c1 83 4a 85 fa 8a dd d5 f6 6c a1 0d
}

When John logs in using the security key, the authenticator verifies that the public key credential on John’s key was indeed created for Microsoft, and returns the user handle along with the authentication signature. Microsoft can then look up the user handle in their user database and conclude that the person logging in is John.