CredentialsContainer: get() method

Syntax

get()
get(options)

Parameters

options Optional

An object that contains options for the request. It can contain the following properties:

mediation Optional

A string indicating how the user is involved in retrieving the credential. The value can be one of the following:

"conditional"

Discovered credentials are presented to the user in a non-modal dialog box along with an indication of the origin requesting credentials. In practice, this means autofilling available credentials; see Autofill UI for more details of how this is used.

"optional"

If credentials can be handed over for a given operation without user mediation, they will be, enabling automatic reauthentication without user mediation. If user mediation is required, then the user agent will ask the user to authenticate. This value is intended for situations where you have reasonable confidence that a user won't be surprised or confused at seeing a login dialog box — for example on a site that doesn't automatically log users in, when a user has just clicked a "Login/Signup" button.

"required"

The user will always be asked to authenticate. This value is intended for situations where you want to force user authentication — for example if you want a user to reauthenticate when a sensitive operation is being performed (like confirming a credit card payment), or when switching users.

"silent"

The user will not be asked to authenticate. The user agent will automatically reauthenticate the user and log them in if possible. If consent is required, the promise will fulfill with null. This value is intended for situations where you would want to automatically sign a user in upon visiting a web app if possible, but if not, you don't want to present them with a confusing login dialog box. Instead, you'd want to wait for them to explicitly click a "Login/Signup" button.

The default value is "optional".

Note: In the case of a federated authentication (FedCM API) request, a mediation value of optional or silent may result in attempted auto-reauthentication. Whether this occurred is communicated to the identity provider (IdP) via the is_auto_selected parameter sent to the IdP's id_assertion_endpoint during validation and the relying party (RP) via the IdentityCredential.isAutoSelected property. This is useful for performance evaluation, security requirements (the IdP may wish to reject automatic reauthentication requests and always require user mediation), and general UX (an IdP or RP may wish to present different UX for auto and non-auto login experiences).

signal Optional

An AbortSignal object instance that allows an ongoing get() operation to be aborted. An aborted operation may complete normally (generally if the abort was received after the operation finished) or reject with the signal's reason (which is an AbortError DOMException by default, or a custom value if one was provided when calling abort()).

password Optional

This option asks the browser to retrieve a stored password as a PasswordCredential object. It is a boolean value.

identity Optional

This option asks the browser to retrieve a federated identity credential as an IdentityCredential object, using the Federated Credential Management API.

This option's value is an IdentityCredentialRequestOptions object containing details of the specific identity providers that the website wants to use.

federated Optional

This option asks the browser to retrieve a federated identity credential as a FederatedCredential object. This interface is now superseded, and developers should prefer to use the identity option, if it is available.

This option's value is an object with the following properties:

protocols

An array of strings representing the protocols of the requested credentials' federated identity providers (for example, "openidconnect").

providers

An array of strings representing the credentials' federated identity providers (for example "https://www.facebook.com" or "https://accounts.google.com").

otp Optional

This option asks the browser to retrieve a one-time password (OTP) as an OTPCredential object.

This option's value is an array of strings which may only contain the string value "sms".

publicKey Optional

This option asks the browser to retrieve an assertion signed using the Web Authentication API as a PublicKeyCredential.

This option's value is a PublicKeyCredentialRequestOptions object.

Return value

A Promise that resolves with one of the following subclasses of Credential:

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

If conditional mediation was specified in the get() call, the browser UI dialog is shown and the promise remains pending until the user picks an account to sign-in with from available autofill suggestions:

• If the user then makes a gesture outside of the browser UI dialog, it closes without resolving or rejecting the promise and without causing a user-visible error condition.
• If the user selects a credential, the relevant PublicKeyCredential is returned to the caller.

If a single credential cannot be unambiguously obtained, the promise resolves with null.

Exceptions

AbortError DOMException

The request was aborted by a call to the abort() method of the AbortController associated with this method's signal option. Note that if the caller of abort() provided a reason argument, then get() will be rejected with the value of reason, instead of an AbortController exception.

TimeoutError DOMException

The request was automatically aborted due to a timeout set using AbortSignal.timeout().

IdentityCredentialError

When requesting an IdentityCredential, the request to the ID assertion endpoint is unable to validate the authentication, and rejects with an error response containing information about the reason.

NetworkError DOMException

When requesting an IdentityCredential, the identity provider (IdP) did not respond within 60 seconds, the provided credentials were not valid/found, or the browser's login status for the IdP is set to "logged-out" (see Update login status using the Login Status API for more information about FedCM login status). In the latter case, there may be some delay in the rejection to avoid leaking the IdP login status to the RP.

NotAllowedError DOMException

Thrown in one of the following situations:

• The user canceled the request.

• Use of this API was blocked by one of the following permissions policies:

  • identity-credentials-get
  • publickey-credentials-get
  • otp-credentials

• The calling origin is an opaque origin.

SecurityError DOMException

The calling domain is not a valid domain.

Examples

Retrieving a federated identity credential

Relying parties can call get() with the identity option to make a request for users to sign in to the relying party via an identity provider (IdP), using identity federation. A typical request would look like this:

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          params: {
            /* IdP-specific parameters */
          },
        },
      ],
    },
  });
}

Check out Federated Credential Management (FedCM) API for more details on how this works. This call will start off the sign-in flow described in FedCM sign-in flow.

A similar call including the context and loginHint extensions would look like so:

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      context: "signup",
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          params: {
            /* IdP-specific parameters */
          },
          loginHint: "user1@example.com",
        },
      ],
    },
  });
}

If the IdP is unable to validate a request to the ID assertion endpoint it will reject the promise returned from CredentialsContainer.get():

async function signIn() {
  try {
    const identityCredential = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: "https://accounts.idp.example/config.json",
            clientId: "********",
            params: {
              /* IdP-specific parameters */
            },
          },
        ],
      },
    });
  } catch (e) {
    // Handle the error in some way, for example provide information
    // to help the user succeed in a future sign-in attempt
    console.error(e);
  }
}

Retrieving a public key credential

The following snippet shows a typical get() call with the WebAuthn publicKey option:

const publicKey = {
  challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* ,… */]),
  rpId: "acme.com",
  allowCredentials: [
    {
      type: "public-key",
      id: new Uint8Array([64, 66, 25, 78, 168, 226, 174 /* ,… */]),
    },
  ],
  userVerification: "required",
};

navigator.credentials.get({ publicKey });

A successful get() call returns a promise that resolves with a PublicKeyCredential object instance, representing a public key credential previously created via a WebAuthn create() that has now been used to authenticate a user. Its PublicKeyCredential.response property contains an AuthenticatorAssertionResponse object providing access to several useful pieces of information including the authenticator data, signature, and user handle.

navigator.credentials.get({ publicKey }).then((publicKeyCredential) => {
  const response = publicKeyCredential.response;

  // Access authenticator data ArrayBuffer
  const authenticatorData = response.authenticatorData;

  // Access client JSON
  const clientJSON = response.clientDataJSON;

  // Access signature ArrayBuffer
  const signature = response.signature;

  // Access userHandle ArrayBuffer
  const userHandle = response.userHandle;
});

Some of this data will need to be stored on the server — for example the signature to provide proof that authenticator possesses the genuine private key used to create the credential, and the userHandle to link the user with the credential, sign in attempt, and other data.

See Authenticating a user for more information about how the overall flow works.

Retrieving a one-time password

The code below triggers the browser's permission flow when an SMS message arrives. If permission is granted, then the promise resolves with an OTPCredential object. The contained code value is then set as the value of an <input> form element, which is then submitted.

navigator.credentials
  .get({
    otp: { transport: ["sms"] },
    signal: ac.signal,
  })
  .then((otp) => {
    input.value = otp.code;
    if (form) form.submit();
  })
  .catch((err) => {
    console.error(err);
  });

Implementing a timeout

In this example, we use AbortSignal.timeout() to automatically abort the request if it takes longer than 10 seconds.

async function authenticateUser() {
  const publicKey = {
    challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* ,… */]),
    rpId: "acme.com",
    allowCredentials: [
      {
        type: "public-key",
        id: new Uint8Array([64, 66, 25, 78, 168, 226, 174 /* ,… */]),
      },
    ],
    userVerification: "required",
  };

  try {
    const credential = await navigator.credentials.get({
      publicKey,
      signal: AbortSignal.timeout(10000), // Abort after 10 seconds
    });
    console.log("Authentication successful:", credential);
  } catch (err) {
    if (err.name === "TimeoutError") {
      console.error("The authentication request timed out.");
    } else if (err.name === "AbortError") {
      console.log("The request was cancelled by the user.");
    } else {
      console.error("An unexpected error occurred:", err);
    }
  }
}

Specifications

Browser compatibility