Passwordless auth method (API)

The passwordless and username-less auth method is provides by the custom auth plugin vault_plugin_auth_passkeys and needs to be registered in the plugin catalog before usage.

This documentation assumes the passkey method is mounted at the /auth/passkey path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly.

A policy according to Passwordless is created and named passkey_policy.

Passkey Configuration

The passkey configuration is needed to set up the origins, the relying party ID, the relying party displayname and attached policies.

Read Passkey Configuration

Returns the set up configuration.

Method	Path
GET	/auth/passkey/config

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault-passkeys.com:8200/v1/auth/passkey/config

Sample response

{
    "data": {
        "config": {
            "policies": [
                "default"
            ],
            "rp_displayname": "Example Coorp",
            "rp_id": "example.com",
            "rp_origins": [
                "https://example.com:443"
            ]
        }
    },
}

Set Passkey Configuration

Set up the configuration to enable users to authenticate.

Method	Path
POST	/auth/passkey/config

Parameters

• policies (Array<string>) - Array of all policies which will be attached to each authenticated user.

• rp_displayname (string) - A human readable Displayname for your project or website. It is used to enhance user experience and has not technical importance.

• rp_id ( string) - The ID of the relying party. This must be set to your domain without scheme and port (e.g. vault-passkeys.com). It will be checked technically by the browser and the auth mechanism. The RP ID is used to identify entries in the authenticator.

• rp_origins (Array<string>) - An origin must be a Fully Qualified Domain Name (FQDN). Only request from this URL are allowed. The origin is technically checked and must be set correctly.

Sample payload

{
    "rp_displayname":"Vault Passkeys",
    "rp_id":"vault-passkeys.com",
    "rp_origins":["https://vault-passkeys.com:8200"],
    "policies":["default","passkey_policy"]
}

Sample request

$ curl \
 --header "X-Vault-Token: ..." \
 --request POST \
 --data @payload.json \
 https://vault-passkeys.com:8200/v1/auth/passkey/config

Sample response

{
    "data": {
        "config":{ 
            "policies":["default","passkey_policy"],
            "rp_displayname":"Vault Passkeys",
            "rp_id":"vault-passkeys.com",
            "rp_origins":["https://vault-passkeys.com:8200"]
        }
    }
}

User management

A user object needs to be either created by an administrator and the one-time-password has to be supplied to the user or an already authenticated user (e.g. via userpass) may use the /create endpoint for self-registration.

List users

List all users that are created at the plugin.

Method	Path
LIST	/auth/passkey/users

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://vault-passkeys.com:8200/v1/auth/passkey/users

Sample response

{
    "data": {
        "keys": ["janedoe","johndoe"]
    }
}

Read user

Retrieve user object information like the one-time-password needed for registration.

Method	Path
GET	/auth/passkey/users/:username

Parameters

• username (string: <required>) - Name of the user.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    https://vault-passkeys.com:8200/v1/auth/passkey/users/johndoe

Sample response

{
    "data": {
        "credentials": null,
        "otp": "8AE4IASG",
        "otp_timestamp": "2024-08-04T21:21:31.605972419Z",
        "username": "johndoe"
    }
}

Create user

Create a pending user object for a user to register with a one-time-password.

Method	Path
POST	/auth/passkey/users/:username

Parameters

• username (string: <required>) - Name of the user.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    https://vault-passkeys.com:8200/v1/auth/passkey/users/johndoe

Delete user

Delete a user object.

Method	Path
DELETE	/auth/passkey/users/:username

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://vault-passkeys.com:8200/v1/auth/passkey/users/johndoe

Reset user

This endpoint is used to reset the one-time-password and timestamp of the validation time.

Method	Path
POST	/auth/passkey/users/:username/reset

Parameters

• username (string: <required>) - Name of the user.

• minutes (number) - Number of minutes that determine how long it is possible to use the one-time-password.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault-passkeys.com:8200/v1/auth/passkey/users/johndoe/reset

Sample response

{
    "data": {
        "VerificationTimestamp":"2024-08-04T22:01:41.372579174Z",
        "VerificationToken":"U7TBKBBP"
    }
}

Authentication

These endpoints operate one a challenge and response sequenze. First the ceremony needs to be started at the Vault system and the returned information must be used to make the WebAuthn API calls at the client. All data used for the WebAuthn calls are url safe encoded via Base64 (-_ are used instead of +/) for transmission. The values must be decoded into ArrayBuffer for the WebAuthn API calls.

Since a browser is needed for the WebAuthn API calls, the samples only show responses.

Registraion Init

Method	Path
POST	/auth/passkey/register

Parameters

• operation (string: "init") - The operation must be set to init to initiate the registration ceremony.

• otp (string: <required>) - The valid one-time-password provided by an administrator.

• username (string: <required>) - Name of the user provided by an administrator.

Sample response

"data": {
    "creationOptions": {
        "publicKey": {
            "attestation": "direct",
            "authenticatorSelection": {
            "requireResidentKey": true,
            "residentKey": "required",
            "userVerification": "preferred"
        },
        "challenge": "bSrBa-4hIMg9_BKwxxY4-YpZ85caSG8vR5V2VfP8v-w",
        "pubKeyCredParams": [
            {"alg": -7, "type": "public-key"},
            {"alg": -35,"type": "public-key"},
            {"alg": -36,"type": "public-key"},
            {"alg": -257,"type": "public-key"},
            {"alg": -258,"type": "public-key"},
            {"alg": -259,"type": "public-key"},
            {"alg": -37,"type": "public-key"},
            {"alg": -38,"type": "public-key"},
            {"alg": -39,"type": "public-key"},
            {"alg": -8,"type": "public-key"}
        ],
        "rp": {
            "id": "vault-passkeys.com",
            "name": "Vault Passkeys"
        },
        "timeout": 300000,
        "user": {
            "displayName": "johndoe",
            "id": "YjIzMTcwYjItMGNiOC00ZWUyLTc3YzktMjQzYTBhMTdiMTVk",
            "name": "johndoe"
        }
    }
}

The response data must be decoded and passed to the navigator.credentials.create() as parameter. The response of this call needs to be encoded and sent back to the Vault endpoint.

Registration Finish

Method	Path
POST	/auth/passkey/register

Parameters

• operation (string: "finish") - The operation must be set to finish to finalzie the registration ceremony.

• otp (string: <required>) - The valid one-time-password provided by an administrator.

• username (string: <required>) - Name of the user provided by an administrator.

• credentialData (object: <required>) - This is the response from the authenticator, containing information like the public key of the newly created key pair.

Sample payload

{
    "operation":"finish",
    "username":"johndoe",
    "otp":"FK9B0A40",
    "credentialData": {
        "id":"5f1MJBPlSZRnMef2Cg1rHZBVFtPkbEMafbRFZq921DU",
        "rawId":"5f1MJBPlSZRnMef2Cg1rHZBVFtPkbEMafbRFZq921DU",
        "type":"public-key",
        "response": {
            "attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN...",
            "clientDataJSON":"eyJ0eXBlIjoid2ViY..."
        }
    }
}

Sample response

{
    "auth": {
        "client_token": "hvs.CAESIPciW_aRF93_PmbUo-eGOfr0A27NAhinor_rVOXUFbjjGh4KHGh2cy5xOEJpUk8wZ3hneFhRZEdSekJuRWdXZXg",
        "accessor": "dDddMVta3LZlfniFU1aRxb7D",
        "policies": [
            "default",
            "passkey_policy"
        ],
        "token_policies": [
            "default",
            "passkey_policy"
        ],
        "metadata": {
            "passkey_username": "johndoe"
        },
        "lease_duration": 2764800,
        "renewable": true,
        "entity_id": "86439772-48c7-496c-3d62-ae45c6f07365",
        "token_type": "service",
        "orphan": true,
        "mfa_requirement": null,
        "num_uses": 0
    }
}

After successful registration the user is logged in and the client token is returned.

Login Init

Method	Path
POST	/auth/passkey/login

Parameters

• operation (string: "init") - The operation must be set to init to initiate the login ceremony.

Sample response

"data": {
    "requestOptions": {
        "publicKey": {
            "challenge": "esqj2ECh6dxaJ_d5KLPqMDqTu3_t--O-CrpPPF-mlos",
            "rpId": "vault-passkeys.com",
            "timeout": 300000,
            "userVerification": "preferred"
        }
    }
}

The response data must be decoded and passed to the navigator.credentials.get() as parameter. The response of this call needs to be encoded and sent back to the Vault endpoint.

Login Finish

Method	Path
POST	/auth/passkey/login

Parameters

• operation (string: "finish") - The operation must be set to finish to finalzie the login ceremony.

• credentialData (object: <required>) - This is the response from the authenticator, containing information like the signature which will be validated by the plugin with the stored public key.

Sample payload

{
    "operation":"finish",
    "credentialData": {
        "id":"5f1MJBPlSZRnMef2Cg1rHZBVFtPkbEMafbRFZq921DU",
        "rawId":"5f1MJBPlSZRnMef2Cg1rHZBVFtPkbEMafbRFZq921DU",
        "type":"public-key",
        "response": {
            "authenticatorData":"rBBE1FnK9RzomGX2_aa4jJMS3er7x6FjQkZqmFrsDeoFAAAAAg",
            "clientDataJSON":"eyJ0eXBlIjoid2ViYXV0aG4...",
            "signature":"MEUCIEex-XnVHBqnDeE4egS66Ne060t7N...",
            "userHandle":"YjIzMTcwYjItMGNiOC00ZWUyLTc3YzktMjQzYTBhMTdiMTVk"
        }
    }
}

Sample response

{
    "auth": {
        "client_token": "hvs.CAESIKy-z5Ar7TFGXXCrdTgxOWeKs_0vOQW2iXso3fn8wteSGh4KHGh2cy5xU2t5M0dBa3g1VUl0c00yM0dia2FjY3o",
        "accessor": "4hwbmpS76olQWr1lNaSQY3X3",
        "policies": [
            "default",
            "passkey_policy"
        ],
        "token_policies": [
            "default",
            "passkey_policy"
        ],
        "metadata": {
            "passkey_username": "johndoe"
        },
        "lease_duration": 2764800,
        "renewable": true,
        "entity_id": "86439772-48c7-496c-3d62-ae45c6f07365",
        "token_type": "service",
        "orphan": true,
        "mfa_requirement": null,
        "num_uses": 0
    }
}

After successful validation the user is logged in and the client token is returned.

Self-Registration

The self-registration can be performed to create a passkey account without administrator interaction. The user must be authenticated in Vault and needs the permission for this endpoint to use.

The administrator should merge the newly created passkey entitiy/alias with the one which is used to create the passkey user account.

These endpoints operate one a challenge and response sequenze. First the ceremony needs to be started at the Vault system and the returned information must be used to make the WebAuthn API calls at the client. All data used for the WebAuthn calls are url safe encoded via Base64 (-_ are used instead of +/) for transmission. The values must be decoded into ArrayBuffer for the WebAuthn API calls.

Since a browser is needed for the WebAuthn API calls, the samples only show responses.

Init

Method	Path
POST	/auth/passkey/create

Parameters

• operation (string: "init") - The operation must be set to init to initiate the registration ceremony.

• username (string: <required>) - A unique username must be provided to create a new account.

Sample response

"data": {
    "creationOptions": {
        "publicKey": {
            "attestation": "direct",
            "authenticatorSelection": {
            "requireResidentKey": true,
            "residentKey": "required",
            "userVerification": "preferred"
        },
        "challenge": "axVrF0oAcrDoPcOm9AWuSS1Mq5sx4hwvcQEcVpe8MHE",
        "pubKeyCredParams": [
            {"alg": -7, "type": "public-key"},
            {"alg": -35,"type": "public-key"},
            {"alg": -36,"type": "public-key"},
            {"alg": -257,"type": "public-key"},
            {"alg": -258,"type": "public-key"},
            {"alg": -259,"type": "public-key"},
            {"alg": -37,"type": "public-key"},
            {"alg": -38,"type": "public-key"},
            {"alg": -39,"type": "public-key"},
            {"alg": -8,"type": "public-key"}
        ],
        "rp": {
            "id": "vault-passkeys.com",
            "name": "Vault Passkeys"
        },
        "timeout": 300000,
        "user": {
            "displayName": "jdoe",
            "id": "NTBjNzg4NDQtYzg3Yy00ODFkLTk0ZDAtZWQ5ODkxMDZiMWZl",
            "name": "jdoe"
        }
    }
}

The response data must be decoded and passed to the navigator.credentials.create() as parameter. The response of this call needs to be encoded and sent back to the Vault endpoint.

Finish

Method	Path
POST	/auth/passkey/create

Parameters

• operation (string: "finish") - The operation must be set to finish to finalize the registration ceremony.

• username (string: <required>) - A unique username must be provided to create a new account.

• credentialData (object: <required>) - This is the response from the authenticator, containing information like the public key of the newly created key pair.

Sample payload

{
    "operation":"finish",
    "username":"jdoe",
    "credentialData": {
        "id":"9eM0tq-WQp3cz8JRFVvpoT_yoiFaRjWURleeT5X8NNE",
        "rawId":"9eM0tq-WQp3cz8JRFVvpoT_yoiFaRjWURleeT5X8NNE",
        "type":"public-key",
        "response": {
            "attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN0bXSj...",
            "clientDataJSON":"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwi..."
        }
    }
}

Sample response

"data": {
        "success": "true"
}

After successful registration the newly created passkey can be used and an Vault entitiy will be created at first login.

Credential Management

A user may add or delete passkeys or rename them on the server side for simplified identifiability.

Many authenticators only support one passkey for one relying party. If a new passkey is created the old one may be deleted on the authenticator side.

Add Passkey Init

Method	Path
POST	/auth/passkey/:username/credentials

Parameters

• username (string: <required>) - The users existing username.

• operation (string: "init") - The operation must be set to init to initiate the registration ceremony.

Sample response

"data": {
    "creationOptions": {
        "publicKey": {
            "attestation": "direct",
            "authenticatorSelection": {
            "requireResidentKey": true,
            "residentKey": "required",
            "userVerification": "preferred"
        },
        "challenge": "axVrF0oAcrDoPcOm9AWuSS1Mq5sx4hwvcQEcVpe8MHE",
        "pubKeyCredParams": [
            {"alg": -7, "type": "public-key"},
            {"alg": -35,"type": "public-key"},
            {"alg": -36,"type": "public-key"},
            {"alg": -257,"type": "public-key"},
            {"alg": -258,"type": "public-key"},
            {"alg": -259,"type": "public-key"},
            {"alg": -37,"type": "public-key"},
            {"alg": -38,"type": "public-key"},
            {"alg": -39,"type": "public-key"},
            {"alg": -8,"type": "public-key"}
        ],
        "rp": {
            "id": "vault-passkeys.com",
            "name": "Vault Passkeys"
        },
        "timeout": 300000,
        "user": {
            "displayName": "johndoe",
            "id": "YjIzMTcwYjItMGNiOC00ZWUyLTc3YzktMjQzYTBhMTdiMTVk",
            "name": "johndoe"
        }
    }
}

The response data must be decoded and passed to the navigator.credentials.create() as parameter. The response of this call needs to be encoded and sent back to the Vault endpoint.

Add Passkey Finish

Method	Path
POST	/auth/passkey/:username/credentials

Parameters

• username (string: <required>) - The users existing username.

• operation (string: "finish") - The operation must be set to finish to finalize the registration ceremony.

• credentialData (object: <required>) - This is the response from the authenticator, containing information like the public key of the newly created key pair.

Sample payload

{
    "operation":"finish",
    "credentialData": {
        "id":"s103DfxxiJRKLaciMZbOW9iZlplH7IyBRUoUrvVFC0E",
        "rawId":"s103DfxxiJRKLaciMZbOW9iZlplH7IyBRUoUrvVFC0E",
        "type":"public-key",
        "response": {
            "attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN0bXSjY2...",
            "clientDataJSON":"eyJ0eXBlIjoid2ViYXV0aG4uY3JlY..."
        }
    }
}

Sample response

"data": {
    "credentials": {
        "CreationTime": "2024-08-04T22:27:32.356255938Z",
        "Credential": {
            "attestationType": "packed",
            "authenticator": {
                "AAGUID": "AQIDBAUGBwgBAgMEBQYHCA==",
                "attachment": "",
                "cloneWarning": false,
                "signCount": 1
            },
            "flags": {
                "backupEligible": false,
                "backupState": false,
                "userPresent": true,
                "userVerified": true
            },
            "id": "s103DfxxiJRKLaciMZbOW9iZlplH7IyBRUoUrvVFC0E=",
            "publicKey": "pQECAyYgASFYIJubBAf6hF+iJiBvmDJC4g5IR7vsM8Hf/ZFKHWw3cuhEIlgg7vfnKI6MPhg2EbZxGbc/+QwEPzEjudD/7FBd4bvNVsM=",
            "transport": null
        },
        "Displayname": "Passkey-NM9I20FR",
        "LastUsed": "0001-01-01T00:00:00Z"
    }
}

Delete Passkey

A user may delete its registered passkeys at the plugin.

Method	Path
DELETE	/auth/passkey/:username/credentials/:credentialID

Parameters

• username (string: <required>) - The users existing username.

• credentialID (string: <required>) - The ID of the passkey entry.

Sample response

"data": {
   "message": "credential deleted"
}

Rename Passkey

Displaynames of passkeys are not synced between clients and servers.

Method	Path
POST	/auth/passkey/:username/credentials/:credentialID

Parameters

• username (string: <required>) - The users existing username.

• credentialID (string: <required>) - The ID of the passkey entry.

• displayName (string: <required>) - The new name of the passkey entry.