CredentialsContainer: get() method
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The get()
method of the CredentialsContainer
interface returns a Promise
that fulfills with a single credential, which can then be used to authenticate a user to a website.
The method accepts a single optional options
argument, which may include:
-
A
mediation
property indicating how and whether the user should be asked to participate in the operation. This controls, for example, whether the site can silently sign a user in using a stored credential. - A
signal
property enabling the operation to be cancelled using anAbortController
. - One or more properties —
password
,federated
,identity
,otp
,publicKey
— which indicate the types of credential being requested. If set, the values of these properties include any parameters that the browser needs in order to find an appropriate credential of the requested type.
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
options
Optional-
An object that contains options for the request. It can contain the following properties:
mediation
Optional-
A string indicating whether the user will be required to login for every visit to a client app. 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 Sign in with a passkey through form autofill for more details of how this is used;PublicKeyCredential.isConditionalMediationAvailable()
also provides some useful information."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, even if prevent silent access (seeCredentialsContainer.preventSilentAccess()
) is set tofalse
. 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 withnull
. 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 ofoptional
orsilent
may result in attempted auto-reauthentication. Whether this occurred is communicated to the identity provider (IdP) via theis_auto_selected
parameter sent to the IdP'sid_assertion_endpoint
during validation and the relying party (RP) via theIdentityCredential.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 ongoingget()
operation to be aborted. An aborted operation may complete normally (generally if the abort was received after the operation finished) or reject with anAbortError
DOMException
. 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 theidentity
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
:
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 theAbortController
associated with this method'ssignal
option. IdentityCredentialError
DOMException
-
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:
- Use of this API was blocked by one of the following permissions policies:
- 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: "********",
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 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);
});
Specifications
Specification |
---|
Credential Management Level 1 # dom-credentialscontainer-get |
Browser compatibility
BCD tables only load in the browser