Skip to content
Migrating from NextAuth.js v4? Read our migration guide.

providers/webauthn

WebAuthnConfig

Shared across all ProviderType

Extends

Properties

authenticationOptions?

optional authenticationOptions: Partial<ConfigurableAuthenticationOptions>;

Authentication options that are passed to

Simplewebauthn

during authentication.

enableConditionalUI

enableConditionalUI: boolean;

Enable conditional UI.

NOTE: Only one provider can have this option enabled at a time. Defaults to true.

formFields

formFields: Record<string, CredentialInput>;

Form fields displayed in the default Passkey sign in/up form. These are not validated or enforced beyond the default Auth.js authentication page.

By default it displays an email field.

getRelayingParty()

getRelayingParty: (options, request) => RelayingParty;

Function that returns the relaying party for the current request.

Parameters
ParameterType
optionsInternalOptions<"webauthn">
requestRequestInternal
Returns

RelayingParty

getUserInfo

getUserInfo: GetUserInfo;

Function that returns the user info that the authenticator will use during registration and authentication.

  • It accepts the provider options, the request object, and returns the user info.
  • If the request contains an existing user’s data (e.g. email address), the function must return the existing user and exists must be true.
  • If the request contains enough information to create a new user, the function must return a new user info and exists must be false.
  • If the request does not contain enough information to create a new user, the function must return null.

It should not have any side effects (i.e. it shall not modify the database).

During passkey creation:

  • The passkey’s user ID will be a random string.
  • The passkey’s user name will be user.email
  • The passkey’s user display name will be user.name, if present, or user.email

By default, it looks for and uses the “email” request parameter to look up the user in the database.

id

id: string;

Uniquely identifies the provider in AuthConfig.providers It’s also part of the URL

Inherited from

CommonProviderOptions.id

name

name: string;

The provider name used on the default sign-in page’s sign-in button. For example if it’s “Google”, the corresponding button will say: “Sign in with Google”

Inherited from

CommonProviderOptions.name

registrationOptions

registrationOptions: Partial<ConfigurableRegistrationOptions>;

Registration options that are passed to

Simplewebauthn

during registration.

relayingParty?

optional relayingParty: Partial<RelayingPartyArray>;

Relaying party (RP) configuration

If not provided, the request URL will be used.

simpleWebAuthn

simpleWebAuthn: {
  generateAuthenticationOptions: (options?) => Promise<PublicKeyCredentialRequestOptionsJSON>;
  generateRegistrationOptions: (options) => Promise<PublicKeyCredentialCreationOptionsJSON>;
  verifyAuthenticationResponse: (options) => Promise<VerifiedAuthenticationResponse>;
  verifyRegistrationResponse: (options) => Promise<VerifiedRegistrationResponse>;
};

SimpleWebAuthn instance to use for registration and authentication.

generateAuthenticationOptions()
generateAuthenticationOptions: (options?) => Promise<PublicKeyCredentialRequestOptionsJSON>;

Prepare a value to pass into navigator.credentials.get(…) for authenticator “login”

Parameters
ParameterType
options?GenerateAuthenticationOptionsOpts
Returns

Promise<PublicKeyCredentialRequestOptionsJSON>

generateRegistrationOptions()
generateRegistrationOptions: (options) => Promise<PublicKeyCredentialCreationOptionsJSON>;

Prepare a value to pass into navigator.credentials.create(…) for authenticator “registration”

Options:

Parameters
ParameterType
optionsGenerateRegistrationOptionsOpts
Returns

Promise<PublicKeyCredentialCreationOptionsJSON>

verifyAuthenticationResponse()
verifyAuthenticationResponse: (options) => Promise<VerifiedAuthenticationResponse>;

Verify that the user has legitimately completed the login process

Options:

Parameters
ParameterType
optionsVerifyAuthenticationResponseOpts
Returns

Promise<VerifiedAuthenticationResponse>

verifyRegistrationResponse()
verifyRegistrationResponse: (options) => Promise<VerifiedRegistrationResponse>;

Verify that the user has legitimately completed the registration process

Options:

Parameters
ParameterType
optionsVerifyRegistrationResponseOpts
Returns

Promise<VerifiedRegistrationResponse>

simpleWebAuthnBrowserVersion

simpleWebAuthnBrowserVersion: false | SemverString;

Version of SimpleWebAuthn browser script to load in the sign in page.

This is only loaded if the provider has conditional UI enabled. If set to false, it won’t load any script. Defaults to v9.0.0.

type

type: "webauthn";

See ProviderType

Overrides

CommonProviderOptions.type

verifyAuthenticationOptions?

optional verifyAuthenticationOptions: Partial<ConfigurableVerifyAuthenticationOptions>;

Verify Authentication options that are passed to

Simplewebauthn

during authentication.

verifyRegistrationOptions?

optional verifyRegistrationOptions: Partial<ConfigurableVerifyRegistrationOptions>;

Verify Registration options that are passed to

Simplewebauthn

during registration.


GetUserInfo()

type GetUserInfo: (options, request) => Promise<{
  exists: true;
  user: User;
  } | {
  exists: false;
  user: Omit<User, "id">;
} | null>;

Parameters

ParameterType
optionsInternalOptions<WebAuthnProviderType>
requestRequestInternal

Returns

Promise<{ exists: true; user: User; } | { exists: false; user: Omit<User, "id">; } | null>


RelayingParty

type RelayingParty: {
  id: string;
  name: string;
  origin: string;
};

Type declaration

id

id: string;

Relaying Party ID. Use the website’s domain name.

name

name: string;

Relaying Party name. Use the website’s name.

origin

origin: string;

Relaying Party origin. Use the website’s origin.


WebAuthnProviderType

type WebAuthnProviderType: "webauthn";

DEFAULT_SIMPLEWEBAUTHN_BROWSER_VERSION

const DEFAULT_SIMPLEWEBAUTHN_BROWSER_VERSION: SemverString = "v9.0.1";

DEFAULT_WEBAUTHN_TIMEOUT

const DEFAULT_WEBAUTHN_TIMEOUT: number;

default()

default(config): WebAuthnConfig

Add WebAuthn login to your page.

Setup

Configuration

import { Auth } from "@auth/core"
import WebAuthn from "@auth/core/providers/webauthn"
 
const request = new Request(origin)
const response = await Auth(request, {
  providers: [WebAuthn],
})

Resources

💡

The WebAuthn provider comes with a default configuration. To override the defaults for your use case, check out customizing the built-in WebAuthn provider.

Disclaimer If you think you found a bug in the default configuration, you can open an issue.

Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec, we might not pursue a resolution. You can ask for more help in Discussions.

Parameters

ParameterType
configPartial<WebAuthnConfig>

Returns

WebAuthnConfig

Auth.js © Balázs Orbán and Team - 2024