Skip to main content
A passkey lets a person sign in with a device, such as a phone or a security key, instead of a password. Passkey sign-in is an option of your organization. An administrator turns it on or off. Passkeys apply to user accounts. Machine-to-machine applications continue to use client credentials.

​
What changes when you turn it on

  • A person who has a passkey signs in with it. Auth refuses the password sign-in of that person with 403 AUT-1019.
  • Lerian Console signs in with a password or SSO. A person who has a passkey cannot sign in to the Console while the option is on.
  • A person who has no passkey signs in with a password, and with MFA when it is enabled.
  • A passkey sign-in does not ask for a second factor.
When you turn passkey sign-in off, Access Manager keeps the stored passkeys. A person who has a passkey can sign in with a password again.

​
Turn passkey sign-in on or off

Send enabled to Update Passkey Policy. The caller needs the application-providers permission of plugin-identity with the action patch. Get Passkey Policy shows the option and ssoActive, which is true when an SSO provider is active. It needs the action get. While an SSO provider is active, Identity refuses to turn passkeys on with 409 IDE-1068. While passkeys are on, Identity refuses to configure an SSO provider with 409 IDE-1069.

​
Add a passkey

Each person adds their own passkey, with their own token. An account holds one passkey.
1

Begin the enrollment

Call Begin Passkey Enrollment with the person’s user ID. Identity answers the WebAuthn creation options and an enrollmentToken.
2

Create the passkey in the browser

Pass the options to navigator.credentials.create.
3

Finish the enrollment

Within 5 minutes, send the enrollmentToken and the created credential to Finish Passkey Enrollment. An enrollment works once.
To add or remove a passkey, the person’s token must be recent: issued no more than PASSKEY_RECENT_AUTH_SEC seconds ago. Otherwise Identity refuses with 403 IDE-1070, and the person signs in again. Identity refuses a new passkey with 409 IDE-1073 while passkey sign-in is off. It refuses with 409 IDE-1071 when the account already has a passkey. These operations need the passkeys permission of plugin-identity: get to read the status, post to add a passkey, and delete to remove it.

​
Sign in with a passkey

1

Begin the sign-in

Send the person’s email to Begin a Passkey Login. Auth answers the WebAuthn request options and a passkeyToken.
2

Get the assertion in the browser

Pass the options to navigator.credentials.get.
3

Finish the sign-in

Within 5 minutes, send the passkeyToken and the assertion to Finish a Passkey Login. Auth answers an access token and a refresh token. A passkeyToken works once.
When the tenant does not offer passkey sign-in, Auth answers 403 AUT-1016. Auth applies your IP allowlist to both calls, as it does to a password sign-in. Discover How an Email Signs In returns passkeyEnabled, so your sign-in screen can offer the passkey option.

​
Remove a passkey

A person removes their own passkey with Delete Passkey. This also works while passkey sign-in is off. When a person loses the device, turn passkey sign-in off. The person signs in with a password and removes the passkey.

​
Deployment requirements (BYOC)

  • Set MFA_SECRET in Auth. Without it, both passkey sign-in calls answer 503 AUT-0028. See MFA deployment requirements.
  • PASSKEY_RECENT_AUTH_SEC in Identity sets the maximum age, in seconds, of the token that adds or removes a passkey. The default is 600.
  • Run Caradhras v1.8.0 or later.
  • In Caradhras, set webauthnRpId and webauthnRpOrigins: the domain that your sign-in pages share, and the HTTPS origins of the pages that run a passkey ceremony.

Multi-factor authentication

Add a second verification step to password and SSO sign-in.

Error list