CredentialsContainer: get() method

The get() method of the CredentialsContainer interface returns a Promise to a single Credential instance that matches the provided parameters.

This method first collects all credentials in the CredentialsContainer that meet the necessary criteria (defined in the options argument). From the resulting set of credentials, it then selects the best one. Depending on the options, it may display a dialog to the user and ask the user to make the selection.

Note: Usage of this feature may be blocked by an identity-credentials-get or publickey-credentials-get Permissions Policy set on your server.

Syntax

get()
get(options)

Parameters

options Optional

An object that contains options for the request. The options include criteria that the credentials are required or allowed to have, and options for interacting with the user. It can contain the following properties:

password Optional

a boolean value indicating that returned Credential instances should include user (as opposed to federated) credentials.

federated Optional

An object containing requirements for returned federated credentials. The available options are:

providers

An array of string instances of identity providers to search for.

identity Optional

An object containing details of federated identity providers (IdPs) that a relying party (RP) website can use to sign users in. Causes a get() call to initiate a request for a user to sign in to a RP with an IdP (see Federated Credential Management API (FedCM)). identity can contain a single property, providers, which contains an array of objects each specifying the details of a separate IdP:

configURL

A string specifying the URL of the IdP's config file. See Provide a config file for more information.

clientId

A string specifying the the RP's client identifier, issued by the IdP to the RP in a completely separate process specific to the IdP.

nonce Optional

A random string that can be included to ensure the response is issued for this specific request, and prevent replay attacks.

publicKey Optional

An object containing requirements for returned WebAuthn credentials. The available options are:

challenge

An ArrayBuffer, a TypedArray, or a DataView emitted by 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 AuthenticatorAssertionResponse.signature.

timeout Optional

A numerical hint, in milliseconds, which indicates the time the caller is willing to wait for the retrieval operation to complete. This hint may be overridden by the browser.

rpId Optional

A string which indicates the relying party's identifier (ex. "login.example.org"). If this option is not provided, the client will use the current origin's domain.

allowCredentials Optional

An Array of credentials descriptor which restricts the acceptable existing credentials for retrieval.

userVerification Optional

A string qualifying how the user verification should be part of the authentication process.

extensions Optional

An object with several client extensions' inputs. Those extensions are used to request additional processing (e.g. dealing with legacy FIDO APIs credentials, prompting a specific text on the authenticator, etc.).

mediation Optional

A String indicating whether the user will be required to log on for every visit to the website. Valid values are "silent", "optional", "conditional", or "required".

unmediated Optional Deprecated

A boolean value indicating the returned Credential instance should not require user mediation.

signal Optional

An instance of AbortSignal that can indicate that an ongoing get() operation should be halted. An aborted operation may complete normally (generally if the abort was received after the operation finished) or reject with an "AbortError" DOMException.

Return value

A Promise that resolves with a Credential instance that matches the provided parameters. If a single credential cannot be unambiguously obtained, the Promise will resolve to null.

Exceptions

NetworkError DOMException

In the case of a get() call with an identity option, this exception is thrown if the IdP does not respond within 60 seconds, or if the provided credentials are not valid/found.

NotAllowedError DOMException

Use of this feature was blocked by an identity-credentials-get Permissions Policy.

SecurityError DOMException

Use of this feature was blocked by a publickey-credentials-get Permissions Policy.

Examples

Relying party sign-in using the FedCM API

Relying parties (RPs) can call navigator.credentials.get() with the identity option to make a request for users to sign in to the RP 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: "********",
          nonce: "******",
        },
      ],
    },
  });
}

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

Specifications

Specification
Credential Management Level 1
# dom-credentialscontainer-get

Browser compatibility

BCD tables only load in the browser

See also