docs.rodeo

MDN Web Docs mirror

CredentialsContainer: get() method

{{APIRef("Credential Management API")}} {{SecureContext_Header}} 

The get() method of the {{domxref("CredentialsContainer")}}  interface returns a {{jsxref("Promise")}}  that fulfills with a single {{glossary("credential")}} , which can then be used to authenticate a user to a website.

The method accepts a single optional options argument, which may include:

The API always fulfills with a single credential or null. If multiple credentials are available and user mediation is allowed, then the browser will ask the user to select a single credential.

Syntax

get()
get(options)

Parameters

Return value

A {{jsxref("Promise")}}  that resolves with one of the following subclasses of {{domxref("Credential")}} :

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 a single credential cannot be unambiguously obtained, the promise resolves with null.

Exceptions

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: "********",
          nonce: "******",
        },
      ],
    },
  });
}

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: "********",
          nonce: "******",
          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: "********",
            nonce: "******",
          },
        ],
      },
    });
  } 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 {{domxref("PublicKeyCredential")}}  object instance, representing a public key credential previously created via a WebAuthn {{domxref("CredentialsContainer.create()", "create()")}}  that has now been used to authenticate a user. Its {{domxref("PublicKeyCredential.response")}}  property contains an {{domxref("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 {{htmlelement("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);
  });

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

In this article

View on MDN