From 1aea5a9cdda8cd0976b6eaf76edd352d5b7235bb Mon Sep 17 00:00:00 2001 From: Manav Rathi Date: Sun, 9 Jun 2024 21:27:02 +0530 Subject: [PATCH] Minor tweaks --- web/docs/webauthn-passkeys.md | 61 ++++++++++++++++++----------------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/web/docs/webauthn-passkeys.md b/web/docs/webauthn-passkeys.md index 1c4e368bf2..19ea281419 100644 --- a/web/docs/webauthn-passkeys.md +++ b/web/docs/webauthn-passkeys.md @@ -46,7 +46,7 @@ used.** This restriction is a byproduct of the enablement for automatic login. | ------------ | ------ | ------------------------------------------------ | | X-Auth-Token | string | The user session token. It is encoded in base64. | -##### Response Body (JSON) +##### Response body (JSON) | Key | Type | Value | | ------------- | ------ | ----------------------------------------------------------------- | @@ -119,7 +119,7 @@ func (u *PasskeyUser) WebAuthnCredentials() []webauthn.Credential { | ------------ | ------ | ------------------------------------------------ | | X-Auth-Token | string | The user session token. It is encoded in base64. | -##### Response Body (JSON) +##### Response body (JSON) | Key | Type | Value | | --------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | @@ -205,8 +205,8 @@ We just have to decode the base64 fields back into `Uint8Array`. ```ts const options = response.options; -options.publicKey.challenge = _sodium.from_base64(options.publicKey.challenge); -options.publicKey.user.id = _sodium.from_base64(options.publicKey.user.id); +options.publicKey.challenge = sodium.from_base64(options.publicKey.challenge); +options.publicKey.user.id = sodium.from_base64(options.publicKey.user.id); ``` ### Creating the credential @@ -226,13 +226,13 @@ The browser returns the newly created credential with a bunch of binary fields, so we have to encode them into base64 for transport to the server. ```ts -const attestationObjectB64 = _sodium.to_base64( +const attestationObjectB64 = sodium.to_base64( new Uint8Array(credential.response.attestationObject), - _sodium.base64_variants.URLSAFE_NO_PADDING + sodium.base64_variants.URLSAFE_NO_PADDING ); -const clientDataJSONB64 = _sodium.to_base64( +const clientDataJSONB64 = sodium.to_base64( new Uint8Array(credential.response.clientDataJSON), - _sodium.base64_variants.URLSAFE_NO_PADDING + sodium.base64_variants.URLSAFE_NO_PADDING ``` Attestation object contains information about the nature of the credential, like @@ -283,7 +283,7 @@ credID := base64.StdEncoding.EncodeToString(cred.ID) On retrieval, this process is effectively the opposite. -#### Query Parameters +#### Query parameters | Key | Value | | ------------ | ------------------------------------------------------------------------------------------------------- | @@ -296,7 +296,7 @@ On retrieval, this process is effectively the opposite. | ------------ | ------ | ------------------------------------------------ | | X-Auth-Token | string | The user session token. It is encoded in base64. | -##### Request Body (JSON) +##### Request body (JSON) | Key | Type | Value | | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -307,7 +307,7 @@ On retrieval, this process is effectively the opposite. **Example** -```json +```js { id: credential.id, rawId: credential.id, @@ -340,8 +340,9 @@ if (passkeySessionID) { ``` The client should redirect the user to Accounts with this session ID to prompt -credential authentication. We use Accounts as the central WebAuthn hub because -credentials are locked to an FQDN. +credential authentication. We use Accounts as the central WebAuthn hub since it +is needed anyways to service credential authentication from mobile clients, so +we use the same flow for other (web, desktop) clients too. ```tsx window.location.href = `${accountsAppURL()}/passkeys/verify?passkeySessionID=${passkeySessionID}&redirect=${ @@ -353,13 +354,13 @@ window.location.href = `${accountsAppURL()}/passkeys/verify?passkeySessionID=${p #### GET /users/two-factor/passkeys/begin -##### Query Parameters +##### Query parameters | Key | Value | | --------- | ------------------------------------------------------------------------- | | sessionID | The `passkeySessionID` returned from SRP login or email OTT verification. | -##### Response Body (JSON) +##### Response body (JSON) **Example** @@ -395,14 +396,14 @@ The browser requires `Uint8Array` versions of the `options` challenge and credential IDs. ```ts -publicKey.challenge = _sodium.from_base64( +publicKey.challenge = sodium.from_base64( publicKey.challenge, - _sodium.base64_variants.URLSAFE_NO_PADDING, + sodium.base64_variants.URLSAFE_NO_PADDING, ); publicKey.allowCredentials?.forEach(function (listItem: any) { - listItem.id = _sodium.from_base64( + listItem.id = sodium.from_base64( listItem.id, - _sodium.base64_variants.URLSAFE_NO_PADDING, + sodium.base64_variants.URLSAFE_NO_PADDING, ); }); ``` @@ -421,21 +422,21 @@ Before sending the public key and signature to the server, their outputs must be encoded into Base64. ```ts -authenticatorData: _sodium.to_base64( +authenticatorData: sodium.to_base64( new Uint8Array(credential.response.authenticatorData), - _sodium.base64_variants.URLSAFE_NO_PADDING + sodium.base64_variants.URLSAFE_NO_PADDING ), -clientDataJSON: _sodium.to_base64( +clientDataJSON: sodium.to_base64( new Uint8Array(credential.response.clientDataJSON), - _sodium.base64_variants.URLSAFE_NO_PADDING + sodium.base64_variants.URLSAFE_NO_PADDING ), -signature: _sodium.to_base64( +signature: sodium.to_base64( new Uint8Array(credential.response.signature), - _sodium.base64_variants.URLSAFE_NO_PADDING + sodium.base64_variants.URLSAFE_NO_PADDING ), -userHandle: _sodium.to_base64( +userHandle: sodium.to_base64( new Uint8Array(credential.response.userHandle), - _sodium.base64_variants.URLSAFE_NO_PADDING + sodium.base64_variants.URLSAFE_NO_PADDING ), ``` @@ -443,14 +444,14 @@ userHandle: _sodium.to_base64( #### POST /users/two-factor/passkeys/finish -##### Query Parameters +##### Query parameters | Key | Value | | ----------------- | ---------------------------------------------------------------------------------------- | | ceremonySessionID | The `ceremonySessionID` identifier from the begin step. | | sessionID | The `passkeySessionID` identifier from the SRP login or email OTT verification response. | -##### Request Body (JSON) +##### Request body (JSON) | Key | Type | Value | | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -459,7 +460,7 @@ userHandle: _sodium.to_base64( | type | string | The type of credential. | | response | object | Contains authenticatorData, clientDataJSON, signature and userHandle fields that were encoded prior to request. | -##### Response Body (JSON) +##### Response body (JSON) | Key | Type | Value | | -------------- | ------ | ------------------------------------------- |