PublicKeyCredential: parseCreationOptionsFromJSON() static method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The parseCreationOptionsFromJSON()
static method of the PublicKeyCredential
interface converts a JSON type representation into its corresponding publicKey
create credentials options object structure.
The method is a convenience function for converting credential options information provided by a relying party server to the form that a web app can use to create a credential.
Syntax
PublicKeyCredential.parseCreationOptionsFromJSON(options)
Parameters
options
-
An object with the same structure as the Web Authentication API
publicKey
create credentials options object, but with base64url-encoded strings used in place of buffer properties.
Return value
An object with the Web Authentication API publicKey
create credentials options object structure.
Exceptions
EncodingError
DOMException
-
Thrown if any part of the
options
object cannot be converted into thepublicKey
create credentials options object structure.
Description
The Web Authentication process for creating a key pair and registering a user involves a relying party server sending the web app information needed to create a credential, including details about the user identity, the relying party, and a "challenge".
The web app passes this information to an authenticator to create the credential, by calling navigator.credentials.create()
with an argument that contains the server-supplied data in the publicKey
create credentials options object structure.
The specification does not define how the information needed for creating a credential is sent.
A convenient approach is for the server to encapsulate the information in a JSON type representation of the publicKey
create credentials options object that mirrors its structure but encodes buffer properties such as the challenge
and user.id
as base64url strings.
This object can be serialized to a JSON string, sent to the web app and deserialized, and then converted to the publicKey
create credentials options object structure using parseCreationOptionsFromJSON()
.
Examples
When registering a new user, a relying party server will supply information about the expected credentials to the web app.
The code below defines this information in the form described in the options
parameter above (taken from the "getting an AuthenticatorAttestationResponse" in AuthenticatorResponse
):
const createCredentialOptionsJSON = {
challenge:
"21, 31, 105, " /* 29 more random bytes generated by the server in this string */,
rp: {
name: "Example CORP",
id: "login.example.com",
},
user: {
id: "16",
name: "canand@example.com",
displayName: "Carina Anand",
},
pubKeyCredParams: [
{
type: "public-key",
alg: -7,
},
],
};
Because this object only uses JSON data types, it can be serialized to JSON using JSON.stringify()
and sent to the web app.
JSON.stringify(createCredentialOptionsJSON);
The web app can deserialize the JSON string back to a createCredentialOptionsJSON
object (not shown).
The parseCreationOptionsFromJSON()
method is used to convert that object to the form that can be used in navigator.credentials.create()
:
// Convert options to form used by create()
const createCredentialOptions =
PublicKeyCredential.parseCreationOptionsFromJSON(
createCredentialOptionsJSON, // JSON-type representation
);
navigator.credentials
.create({ createCredentialOptions })
.then((newCredentialInfo) => {
// Handle the new credential information here.
})
.catch((err) => {
console.error(err);
});
Specifications
Specification |
---|
Web Authentication: An API for accessing Public Key Credentials - Level 3 # dom-publickeycredential-parsecreationoptionsfromjson |
Browser compatibility
BCD tables only load in the browser