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
, orDataView
representing the ID of the public key credential to retrieve. This value is mirrored by therawId
property of thePublicKeyCredential
object returned by a successfulget()
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 thePublicKeyCredential
object returned by thecreate()
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 thetype
property of thePublicKeyCredential
object returned by a successfulget()
call.
This value defaults to an empty array.
challenge
-
An
ArrayBuffer
,TypedArray
, orDataView
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 theAuthenticatorAssertionResponse.signature
(available in theresponse
property of thePublicKeyCredential
object returned by a successfulget()
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 therpId
of the credential used for the authentication ceremony.
This value defaults to the current origin's domain.
- The calling web app verifies that
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 |