PublicKeyCredentialRequestOptions

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The PublicKeyCredentialRequestOptions dictionary represents the object passed to CredentialsContainer.get() as the value of the publicKey option:.

It is used to request a PublicKeyCredential provided by an authenticator that supports the Web Authentication API.

Instance properties

allowCredentials Optional

An array of objects used to restrict the list of acceptable credentials. An empty array indicates that any credential is acceptable.

Each object in the array will contain the following properties:

id

An ArrayBuffer, TypedArray, or DataView representing the ID of the public key credential to retrieve. This value is mirrored by the rawId property of the PublicKeyCredential object returned by a successful get() call.

transports

An array of strings providing hints as to the methods the client could use to communicate with the relevant authenticator of the public key credential to retrieve. Possible transports are: "ble", "hybrid", "internal", "nfc", and "usb".

Note: This value is mirrored by the return value of the PublicKeyCredential.response.getTransports() method of the PublicKeyCredential object returned by the create() call that originally created the credential. At that point, it should be stored by the app for later use.

type

A string defining the type of the public key credential to retrieve. This can currently take a single value, "public-key", but more values may be added in the future. This value is mirrored by the type property of the PublicKeyCredential object returned by a successful get() call.

This value defaults to an empty array.

challenge

An ArrayBuffer, TypedArray, or DataView originating from the relying party's server and used as a cryptographic challenge. This value will be signed by the authenticator and the signature will be sent back as part of the AuthenticatorAssertionResponse.signature (available in the response property of the PublicKeyCredential object returned by a successful get() call).

extensions Optional

An object containing properties representing the input values for any requested extensions. These extensions are used to specific additional processing by the client or authenticator during the authentication process. Examples include dealing with legacy FIDO API credentials, and evaluating outputs from a pseudo-random function (PRF) associated with a credential.

Extensions are optional and different browsers may recognize different extensions. Processing extensions is always optional for the client: if a browser does not recognize a given extension, it will just ignore it. For information on using extensions, and which ones are supported by which browsers, see Web Authentication extensions.

hints Optional

An array of strings providing hints as to what authentication UI the user-agent should provide for the user.

The values can be any of the following:

"security-key"

Authentication requires a separate dedicated physical device to provide the key.

"client-device"

The user authenticates using their own device, such as a phone.

"hybrid"

Authentication relies on a combination of authorization/authentication methods, potentially relying on both user and server-based mechanisms.

rpId Optional

A string that specifies the relying party's identifier (for example "login.example.org"). For security purposes:

  • The calling web app verifies that rpId matches the relying party's origin.
  • The authenticator verifies that rpId matches the rpId of the credential used for the authentication ceremony.

This value defaults to the current origin's domain.

timeout Optional

A numerical hint, in milliseconds, indicating the time the relying party is willing to wait for the retrieval operation to complete. This hint may be overridden by the browser.

userVerification Optional

A string specifying the relying party's requirements for user verification of the authentication process. This verification is initiated by the authenticator, which will request the user to provide an available factor (for example a PIN or a biometric input of some kind).

The value can be one of the following:

"required"

The relying party requires user verification, and the operation will fail if it does not occur.

"preferred"

The relying party prefers user verification if possible, but the operation will not fail if it does not occur.

"discouraged"

The relying party does not want user verification, in the interests of making user interaction as smooth as possible.

This value defaults to "preferred".

Specifications

Specification
Web Authentication: An API for accessing Public Key Credentials - Level 3
# dictdef-publickeycredentialrequestoptions