Credential Management Level 1
-Editor’s Draft,
+Editor’s Draft,
- This version:
@@ -1483,7 +1483,7 @@
https://github.com/w3c/webappsec-credential-management/commits/master/index.src.html
- Feedback: -
- public-webappsec@w3.org with subject line “[credential-management] … message topic …” (archives) +
- public-webappsec@w3.org with subject line “[credential-management] … message topic …” (archives)
- Editor:
- Participate: @@ -1498,8 +1498,8 @@
Abstract
This specification describes an imperative API enabling a website to request a -user’s credentials from a user agent, and to help the user agent correctly -store user credentials for future use.
+ user’s credentials from a user agent, and to help the user agent correctly + store user credentials for future use.
Status of this document
hodgepodge of heuristics meant to detect and fill sign-in forms, password change forms, etc.
A few problems with the status quo stand out as being particularly noteworthy:
- -
+
-
User agents have an incredibly difficult time helping users with
federated identity providers. While detecting a username/password
form submission is fairly straightforward, detecting sign-in via a
third-party is quite difficult to reliably do well. It would be nice
if a website could help the user agent understand the intent behind the
redirects associated with a typical federated sign-in action.
- -
+
-
Likewise, user agents struggle to detect more esoteric sign-in
mechanisms than simple username/password forms. Authors increasingly
asynchronously sign users in via XMLHttpRequest or similar
@@ -1707,7 +1707,7 @@
integrate into their password managers. It would be nice if a website
could help the user agent make sense of the sign-in mechanism they
choose to use.
- -
+
-
Finally, changing passwords is less well-supported than it could be if
the website explicitly informed the user agent that credentials had
changed.
@@ -1715,7 +1715,7 @@
2. Core API
- From a developer’s perspective, a credential is an
+
From a developer’s perspective, a credential is an
object which allows a developer to make an authentication decision for a particular action. This
section defines a generic and extensible Credential interface which serves as a base class
for credentials defined in this and other documents, along with a set of APIs
@@ -1723,18 +1723,18 @@
2.
Various types of credentials are represented to JavaScript as an interface which inherits, either directly or indirectly, from the Credential interface. This
document defines two such interfaces, PasswordCredential and FederatedCredential.
- A credential is effective for a particular origin if it
+
A credential is effective for a particular origin if it
is accepted as authentication on that origin. Even if a credential is effective at a particular
point in time, the UA can’t assume that the same credential will be effective at any future time,
for a couple reasons:
- -
+
-
A password credential may stop being effective if the account holder changes their password.
- -
+
-
A credential made from a token received over SMS is likely to only be effective for a single
use.
- Single-use credentials are generated by a credential source, which could be
+
Single-use credentials are generated by a credential source, which could be
a private key, access to a federated account, the ability to receive SMS messages at a particular
phone number, or something else. Credential sources are not exposed to Javascript or explicitly
represented in this specification. To unify the model, we consider a password to be a credential
@@ -1746,80 +1746,80 @@
2. offering effective credential
sources to the user in the future.
2.1. Infrastructure
- User agents MUST internally provide a credential
+ User agents MUST internally provide a credential
store, which is a vendor-specific, opaque storage mechanism to record which credentials have been effective. It offers the following capabilities for credential access and
persistence:
- -
-
-
+
Store a credential for later retrieval.
This accepts a credential, and inserts it into the credential store.
- -
-
Retrieve a list of credentials. This
+
-
+
Retrieve a list of credentials. This
accepts an arbitrary filter, and returns a set of credentials that match the filter.
- -
-
Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store.
+ -
+
Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store.
- Additionally, the credential store should maintain a prevent silent access flag for origins (which is set to true unless otherwise specified).
- An origin requires user mediation if its flag is set to true.
+ Additionally, the credential store should maintain a prevent silent access flag for origins (which is set to true unless otherwise specified).
+ An origin requires user mediation if its flag is set to true.
Note: The importance of user mediation is discussed in more detail in §5 User Mediation.
Note: The credential store is an internal implementation detail of a user agent’s
implementation of the API specified in this document, and is not exposed to the web directly.
More capabilities may be specified by other documents in support of specific credential types.
This document depends on the Infra Standard for a number of foundational concepts used in its
algorithms and prose [INFRA].
- An environment settings object (settings) is same-origin with its
+ An environment settings object (settings) is same-origin with its
ancestors if the following algorithm returns true:
- -
+
-
If settings has no responsible browsing context,
return false.
- -
+
-
Let origin be settings’ origin.
- -
+
-
Let current be settings’ responsible browsing context.
- -
+
-
While current has a parent browsing context:
- -
+
-
Set current to current’s parent browsing context.
- -
+
-
If current’s active document's origin is not same origin with origin,
return false.
- -
+
-
Return true.
2.2. The Credential Interface
-[Exposed=Window, SecureContext]
-interface Credential {
- readonly attribute USVString id;
- readonly attribute DOMString type;
+[Exposed =Window , SecureContext ]
+interface Credential readonly attribute USVString id ;
+ readonly attribute DOMString type ;
};
- id, of type USVString, readonly
- -
+
id, of type USVString, readonly
+ -
The credential’s identifier. The requirements for the identifier are distinct for each type
of credential. It might represent a username for username/password tuples, for example.
- type, of type DOMString, readonly
- -
+
type, of type DOMString, readonly
+ -
This attribute’s getter returns the value of the object’s interface object's [[type]] slot, which specifies the kind of credential represented by this object.
- [[type]]
- -
+
[[type]]
+ -
The Credential interface object has an internal slot named [[type]], which
unsurprisingly contains a string representing the type of the credential. The slot’s value
is the empty string unless otherwise specified.
Note: The [[type]] slot’s value will be the same for all credentials implementing a
particular interface, which means that developers can rely on obj.type returning a string
that unambigiously represents the specific kind of Credential they’re dealing with.
- [[discovery]]
- -
+
[[discovery]]
+ -
The Credential interface object has an internal slot named [[discovery]],
representing the mechanism by which the user agent can collect credentials of
a given type. Its value is either
- "credential store" or
- "remote". The former value means that
+ "credential store" or
+ "remote". The former value means that
all available credential information is stored in the user agent’s credential store,
while the latter means that the user agent can discover credentials outside of those
explicitly represented in the credential store via interaction with some external device
@@ -1828,46 +1828,46 @@
Talk to Tobie/Dominic about the interface object bits, here and in §2.5.1 Request a Credential, etc. I’m not sure I’ve gotten the terminology right. interface prototype
object, maybe?
- Some Credential objects are origin bound: these contain an
- internal slot named [[origin]], which stores the origin for which the Credential may be effective.
+ Some Credential objects are origin bound: these contain an
+ internal slot named [[origin]], which stores the origin for which the Credential may be effective.
2.2.1. Credential Internal Methods
Each interface object created for interfaces which inherit from Credential defines several internal methods that allow retrieval and storage of Credential objects:
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
+ [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
set of Credential objects from the user agent’s credential store that match the options
provided. If no matching Credential objects are available, the returned set will be empty.
- -
+
-
Return an empty set.
- [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
+ [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
caller’s environment settings object is same-origin with its ancestors. It returns a Credential if one can be returned given the options provided, null if no credential is
available, or an error if discovery fails (for example, incorrect options could produce a TypeError). If this kind of Credential is only effective for a single use or a
limited time, this method is responsible for generating new credentials using a credential source.
- -
+
-
Return null.
- [[Store]](credential, sameOriginWithAncestors) is
+ [[Store]](credential, sameOriginWithAncestors) is
called with a Credential, and a boolean which is true iff the caller’s environment
settings object is same-origin with its ancestors. The algorithm returns once Credential is persisted to the credential store:
- -
+
-
Return undefined.
- [[Create]](options, sameOriginWithAncestors) is
+ [[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions, and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns
either a Credential, if one can be created, null if no credential was created, or an
error if creation fails due to exceptional situations (for example, incorrect options could
produce a TypeError):
- -
+
-
Return null.
@@ -1876,20 +1876,20 @@
2.2.2. CredentialUserData Mixin
Some Credential objects contain data which aims to give users a human-readable disambiguation
mechanism in the credential chooser by providing a friendly name and icon:
-[SecureContext]
-interface mixin CredentialUserData {
- readonly attribute USVString name;
- readonly attribute USVString iconURL;
+[SecureContext ]
+interface mixin CredentialUserData readonly attribute USVString name ;
+ readonly attribute USVString iconURL ;
};
- name, of type USVString, readonly
- -
+
name, of type USVString, readonly
+ -
A name associated with the credential, intended as a human-understandable public name for
display in a credential chooser.
- iconURL, of type USVString, readonly
- -
+
iconURL, of type USVString, readonly
+ -
A URL pointing to an image for the credential, intended for display in a credential chooser. This URL MUST be an a priori authenticated
URL.
@@ -1897,28 +1897,28 @@ 2.3. navigator.credentials
Developers retrieve Credentials and interact with the user agent’s credential store via
methods exposed on the CredentialsContainer interface, which hangs off the Navigator object as navigator.credentials.
-partial interface Navigator {
- [SecureContext, SameObject] readonly attribute CredentialsContainer credentials;
+partial interface Navigator {
+ [SecureContext , SameObject ] readonly attribute CredentialsContainer credentials ;
};
- The credentials attribute MUST return the CredentialsContainer associated with the context object.
+ The credentials attribute MUST return the CredentialsContainer associated with the context object.
Note: As discussed in §6.3 Insecure Sites, the credential management API is exposed only in Secure Contexts.
-[Exposed=Window, SecureContext]
-interface CredentialsContainer {
- Promise<Credential?> get(optional CredentialRequestOptions options);
- Promise<Credential> store(Credential credential);
- Promise<Credential?> create(optional CredentialCreationOptions options);
- Promise<void> preventSilentAccess();
+[Exposed =Window , SecureContext ]
+interface CredentialsContainer Promise <Credential ?> get (optional CredentialRequestOptions options );
+ Promise <Credential > store (Credential credential );
+ Promise <Credential ?> create (optional CredentialCreationOptions options );
+ Promise <void > preventSilentAccess ();
};
-dictionary CredentialData {
- required USVString id;
+dictionary CredentialData required USVString id
- get(options)
- -
+
get(options)
+ -
When get() is called, the user agent MUST return the result of
executing Request a Credential on options.
@@ -1932,14 +1932,14 @@ options
+ options
CredentialRequestOptions
✘
✔
The set of properties governing the scope of the request.
- store(credential)
- -
+
store(credential)
+ -
When store() is called, the user agent MUST return the result of
executing Store a Credential on credential.
@@ -1953,14 +1953,14 @@ credential
+ credential
Credential
✘
✘
The credential to be stored.
- create(options)
- -
+
create(options)
+ -
When create() is called, the user agent MUST return the result of
executing Create a Credential on options.
@@ -1974,14 +1974,14 @@ options
+ options
CredentialCreationOptions
✘
✔
The options used to create a Credential.
- preventSilentAccess()
- -
+
preventSilentAccess()
+ -
When preventSilentAccess() is called, the user agent MUST return
the result of executing Prevent Silent Access on the current settings
object.
@@ -2002,20 +2002,20 @@ Note: The CredentialRequestOptions dictionary is an extension point. If and when new types of
credentials are introduced that require options, their dictionary types will be added to the
dictionary so they can be passed into the request. See §7.2 Extension Points.
-dictionary CredentialRequestOptions {
- CredentialMediationRequirement mediation = "optional";
- AbortSignal signal;
+dictionary CredentialRequestOptions CredentialMediationRequirement mediation = "optional";
+ AbortSignal signal ;
};
- mediation, of type CredentialMediationRequirement, defaulting to "optional"
- -
+
mediation, of type CredentialMediationRequirement, defaulting to "optional"
+ -
This property specifies the mediation requirements for a given credential request. The
meaning of each enum value is described below in CredentialMediationRequirement.
Processing details are defined in §2.5.1 Request a Credential.
- signal, of type AbortSignal
- -
+
signal, of type AbortSignal
+ -
This property lets the developer abort an ongoing get() operation.
An aborted operation may complete normally (generally if the abort was received after the
operation finished) or reject with an "AbortError" DOMException."
@@ -2029,22 +2029,22 @@ mediation.
- The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
+ The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
- -
+
-
Let settings be the current settings object
- -
+
-
Let interface objects be the set of interface objects on settings’ global object.
- -
+
-
Let relevant interface objects be an empty set.
- -
+
-
For each object in interface objects:
- -
+
-
If object’s inherited interfaces do not contain Credential, continue.
- -
+
-
Let key be object’s [[type]] slot’s value.
- -
+
-
If options[key] exists, append object to relevant interface objects.
@@ -2053,17 +2053,17 @@
- A given CredentialRequestOptions options is matchable a priori if the following
+ A given CredentialRequestOptions options is matchable a priori if the following
steps return true:
- -
+
-
For each interface in options’ relevant credential interface objects:
- -
+
-
If interface’s [[discovery]] slot’s value is not
"credential store", return false.
- -
+
-
Return true.
Note: When executing get(options), we only return credentials without user mediation if
@@ -2072,20 +2072,47 @@
user mediation will be required in order
to guide the discovery process (by choosing a federated identity provider, BTLE device, etc).
+
+ To create a copy of any buffer sources' data referenced by a value V of dictionary type, run the following steps given V:
+
+ -
+
Let dictionaries be a list consisting of V and all of V’s inherited dictionaries, in order from least to most derived.
+ -
+
For each dictionary dictionary in dictionaries, in order:
+
+ -
+
For each dictionary member member declared on dictionary, in lexicographical order:
+
+ -
+
Let key be the identifier of member.
+ -
+
If the dictionary member named key is present in V, then:
+
+ -
+
Let value be the value of member on V.
+ -
+
If value’s type is a buffer source type then get a copy of the bytes held by the buffer source and
+set values’s value to be a reference to the copy of the bytes.
+
+
+
+
+
+
2.3.2. Mediation Requirements
When making a request via get(options), developers can set a case-by-case requirement for user mediation by choosing the appropriate CredentialMediationRequirement enum value.
Note: The §5 User Mediation section gives more detail on the concept in general, and its
implications on how the user agent deals with individual requests for a given origin).
-enum CredentialMediationRequirement {
- "silent",
- "optional",
- "required"
+enum CredentialMediationRequirement "silent" ,
+ "optional" ,
+ "required"
};
- silent
- -
+
silent
+ -
User mediation is suppressed for the given operation. If the operation can be performed
without user involvement, wonderful. If user involvement is necessary, then the operation
will return null rather than involving the user.
@@ -2093,8 +2120,8 @@ , where a developer may wish to silently obtain
credentials if a user should be automatically signed in, but to delay bothering the user
with a sign-in prompt until they actively choose to sign-in.
- optional
- -
+
optional
+ -
If credentials can be handed over for a given operation without user mediation, they will
be. If user mediation is required, then the user agent will
involve the user in the decision.
@@ -2102,8 +2129,8 @@ credential chooser if necessary.
- required
- -
+
required
+ -
The user agent will not hand over credentials without user mediation, even if the prevent silent access flag is unset for an origin.
Note: This requirement is intended to support reauthentication or user-switching scenarios. Further, the requirement is tied
to a specific operation, and does not affect the prevent silent access flag for the
@@ -2118,7 +2145,7 @@
§5.2 Requiring User Mediation)
are signed in, and users who haven’t opted-into such behavior won’t be bothered with a confusing credential chooser popping up without context:
window.addEventListener('load', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'silent'
});
@@ -2133,7 +2160,7 @@ opted-into signing in without user mediation, and the user agent can unambigiously choose a credential, great! If
not, a credential chooser will be presented.
document.querySelector('#sign-in').addEventListener('click', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'optional'
});
@@ -2154,7 +2181,7 @@
document.querySelector('#important-form').addEventListener('submit', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2173,7 +2200,7 @@ required" in order to ensure that that credentials aren’t
returned automatically in response to clicking on an "Add account" button:
document.querySelector('#switch-button').addEventListener('click', e => {
- var c = await navigatior.credentials.get({
+ var c = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2189,192 +2216,196 @@ Note: The CredentialCreationOptions dictionary is an extension point. If and when new types of
credentials are introduced, they will add to the dictionary so they can be passed into the
creation method. See §7.2 Extension Points, and the extensions introduced in this document: §3.2 The PasswordCredential Interface and §4.1 The FederatedCredential Interface.
-dictionary CredentialCreationOptions {
- AbortSignal signal;
+dictionary CredentialCreationOptions AbortSignal signal ;
};
- signal, of type AbortSignal
- -
+
signal, of type AbortSignal
+ -
This property lets the developer abort an ongoing create() operation. An aborted operation may complete normally (generally if the abort was received
after the operation finished) or reject with an "AbortError" DOMException."
2.5. Algorithms
2.5.1. Request a Credential
- The Request a Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
+
The Request a Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
unambigiously obtained, or with null if not.
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
If options.signal’s aborted flag is set, then return a promise rejected with an "AbortError" DOMException.
- -
+
-
Let p be a new promise.
- -
+
-
Let sameOriginWithAncestors be true if settings is same-origin with its
ancestors, and false otherwise.
- -
+
-
+
Create a copy of any buffer sources' data referenced by options.
+ -
Run the following steps in parallel:
- -
+
-
Let credentials be the result of collecting Credentials from the credential store, given options and sameOriginWithAncestors.
- -
+
-
-
-
+
-
If all of the following statements are true, resolve p with credentials[0] and
skip the remaining steps:
- -
+
-
credentials’ size is 1
- -
+
-
settings’ origin does not require user mediation
- -
+
-
options is matchable a priori.
- -
+
-
This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in.
- -
+
-
If options’ mediation is
"silent", resolve p with null, and skip
the remaining steps.
- -
+
-
Let choice be the result of asking the user to
choose a Credential, given options and credentials.
- -
+
-
If choice is null or a Credential, resolve p with choice and skip the
remaining steps.
- -
+
-
Assert: choice is an interface object.
- -
+
-
Let result be the result of executing choice’s [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), given options and sameOriginWithAncestors.
- -
+
-
If result is a Credential or null, resolve p with result.
Otherwise, reject p with result.
- -
+
-
Return p.
2.5.2. Collect Credentials from the credential store
Given a CredentialRequestOptions (options) and a boolean which is true iff the calling
- context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
+ context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
returning a set of Credential objects stored by the user agent locally that match options’
filter. If no such Credential objects are known, the returned set will be empty:
- -
+
-
Let possible matches be an empty set.
- -
+
-
For each interface in options’ relevant credential interface objects:
- -
+
-
Let r be the result of executing interface’s [[CollectFromCredentialStore]](options, sameOriginWithAncestors) internal
method on options and sameOriginWithAncestors.
- -
+
-
If r is an exception, return r.
- -
+
-
Assert: r is a list of interface objects.
- -
+
-
For each c in r:
- -
+
-
Append c to possible matches.
- -
+
-
Return possible matches.
2.5.3. Store a Credential
- The Store a Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
+ The Store a Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
Let sameOriginWithAncestors be true if the current settings object is same-origin
with its ancestors, and false otherwise.
- -
+
-
Let p be a new promise.
- -
+
-
Run the following steps in parallel:
- -
+
-
Let r be the result of executing credential’s interface object's [[Store]](credential, sameOriginWithAncestors) internal method on credential and sameOriginWithAncestors.
- -
+
-
If r is an exception, reject p with r.
Otherwise, resolve p with r.
- -
+
-
Return p.
2.5.4. Create a Credential
- The Create a Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
+
The Create a Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
using the options provided, or null if no Credential can be created. In exceptional
circumstances, the Promise may reject with an appropriate exception:
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
Let sameOriginWithAncestors be true if the current settings object is same-origin
with its ancestors, and false otherwise.
- -
+
-
Let interfaces be the set of options’ relevant credential interface objects.
- -
+
-
Return a promise rejected with NotSupportedError if any of the following statements
are true:
- -
+
-
settings does not have a responsible document.
- -
+
-
interfaces’ size is greater than 1.
Note: It may be reasonable at some point in the future to loosen this restriction, and
allow the user agent to help the user choose among one of many potential credential
types in order to support a "sign-up" use case. For the moment, though, we’re punting
on that by restricting the dictionary to a single entry.
- -
+
-
If options.signal’s aborted
flag is set, then return a promise rejected with an "AbortError" DOMException.
- -
+
-
+
Create a copy of any buffer sources' data referenced by options.
+ -
Let p be a new promise.
- -
+
-
Run the following steps in parallel:
- -
+
-
Let r be the result of executing interfaces[0] [[Create]](options, sameOriginWithAncestors) internal method on options and sameOriginWithAncestors.
- -
+
-
If r is an exception, reject p with r.
Otherwise, resolve p with r.
- -
+
-
Return p.
2.5.5. Prevent Silent Access
- The Prevent Silent Access algorithm accepts an environment settings
+ The Prevent Silent Access algorithm accepts an environment settings
object (settings), and returns a Promise which resolves once the prevent silent access flag is persisted to the credential store.
- -
+
-
Let origin be settings’ origin.
- -
+
-
Let p be a new promise
- -
+
-
Run the following seps in parallel:
- -
+
-
Set origin’s prevent silent access flag in the credential store.
- -
+
-
Resolve p with undefined.
- -
+
-
Retun p.
@@ -2386,8 +2417,8 @@ 3.
from within a credential chooser.
3.1. Examples
3.1.1. Password-based Sign-in
-
- MegaCorp, Inc. supports passwords, and can use navigator.credentials.get() to obtain
+
+ MegaCorp, Inc. supports passwords, and can use navigator.credentials.get() to obtain
username/password pairs from a user’s credential store:
navigator.credentials
.get({ 'password': true })
@@ -2429,12 +2460,12 @@ type == 'password') {
- document.getQuerySelector('input[name=username_field]').value =
- credential.id;
- document.getQuerySelector('input[name=password_field]').value =
- credential.password;
- document.getQuerySelector('#myform').submit();
+ if (credential.type === 'password') {
+ document.querySelector('input[name=username_field]').value =
+ credential.id;
+ document.querySelector('input[name=password_field]').value =
+ credential.password;
+ document.getElementById('myform').submit();
}
});
@@ -2538,51 +2569,49 @@
3.2. The PasswordCredential Interface
-typedef (FormData or URLSearchParams) CredentialBodyType;
-
-[Constructor(HTMLFormElement form),
- Constructor(PasswordCredentialData data),
- Exposed=Window,
- SecureContext]
-interface PasswordCredential : Credential {
- readonly attribute USVString password;
+[Constructor (HTMLFormElement form Constructor (PasswordCredentialData data Exposed =Window ,
+ SecureContext ]
+interface PasswordCredential Credential {
+ readonly attribute USVString password ;
};
-PasswordCredential includes CredentialUserData;
+PasswordCredential includes CredentialUserData ;
-partial dictionary CredentialRequestOptions {
- boolean password = false;
+partial dictionary CredentialRequestOptions {
+ boolean password false ;
};
- password, of type USVString, readonly
- -
+
password, of type USVString, readonly
+ -
This attribute represents the password of the credential.
- [[type]]
- -
+
[[type]]
+ -
The PasswordCredential interface object has an internal slot named [[type]] whose
- value is "password".
- [[discovery]]
- -
+ value is "
password".
+ [[discovery]]
+ -
The PasswordCredential interface object has an internal slot named [[discovery]] whose value is "credential store".
- PasswordCredential(form)
- -
+
PasswordCredential(form)
+ -
This constructor accepts an HTMLFormElement (form), and runs the following steps:
- -
+
-
Let r be the result of executing Create a PasswordCredential from
an HTMLFormElement on form.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
- PasswordCredential(data)
- -
+
PasswordCredential(data)
+ -
This constructor accepts a PasswordCredentialData (data), and runs the following steps:
- -
+
-
Let r be the result of executing Create a PasswordCredential from PasswordCredentialData on data.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
@@ -2590,16 +2619,16 @@ <
PasswordCredential objects can be created via navigator.credentials.create() either explicitly by passing in a PasswordCredentialData dictionary, or based on the contents
of an HTMLFormElement's submittable elements.
-dictionary PasswordCredentialData : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString password;
+dictionary PasswordCredentialData CredentialData {
+ USVString name USVString iconURL required USVString password PasswordCredentialInit;
+typedef (PasswordCredentialData or HTMLFormElement ) PasswordCredentialInit password;
+partial dictionary CredentialCreationOptions {
+ PasswordCredentialInit password
PasswordCredential objects are origin bound.
@@ -2607,153 +2636,153 @@ <
own implementation of [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[Create]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors).
3.3. Algorithms
3.3.1. PasswordCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors)
-
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
+
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a set of Credential objects from the credential store. If no matching Credential objects are available, or sameOriginWithAncestors is false, the returned set
will be empty.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
-
-
+
-
If |sameOriginWithAncestors is false, return a "NotAllowedError" DOMException.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
Return the empty set if options["password"] is not true.
- -
+
-
Return the result of retrieving credentials from the credential store that match the following filter:
- -
+
-
The credential is a PasswordCredential
- -
+
-
The credential’s [[origin]] is the same origin as the current settings object's origin.
3.3.2. PasswordCredential's [[Create]](options, sameOriginWithAncestors)
- [[Create]](options, sameOriginWithAncestors) is called
+
[[Create]](options, sameOriginWithAncestors) is called
with a CredentialCreationOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns a PasswordCredential if one can be created, and null otherwise. The CredentialCreationOptions dictionary must have a password member which holds either an HTMLFormElement or a PasswordCredentialData. If that member’s value cannot be
used to create a PasswordCredential, this algorithm will return a TypeError exception.
- -
+
-
Assert: options["password"] exists, and sameOriginWithAncestors is unused.
- -
+
-
If options["password"] is an HTMLFormElement, return the
result of executing Create a PasswordCredential from an HTMLFormElement on options["password"].
- -
+
-
If options["password"] is a PasswordCredentialData, return
the result of executing Create a PasswordCredential from PasswordCredentialData on options["password"].
- -
+
-
3.3.3. PasswordCredential's [[Store]](credential, sameOriginWithAncestors)
- [[Store]](credential, sameOriginWithAncestors) is
+
[[Store]](credential, sameOriginWithAncestors) is
called with a PasswordCredential (credential), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns undefined once credential is persisted to the credential store.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
Return a "NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
If the user agent’s credential store contains a PasswordCredential (stored)
whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]],
then:
- -
+
-
If the user grants permission to update credentials (as discussed when defining user mediation), then:
Otherwise, if the user grants permission to store credentials (as discussed when
defining user mediation, then:
- -
+
-
Store a PasswordCredential in the credential store with the following
properties:
- id
- -
+
id
+ -
credential’s id
- name,
- -
+
name,
+ -
credential’s name
- iconURL
- -
+
iconURL
+ -
credential’s iconURL
- [[origin]]
- -
+
[[origin]]
+ -
credential’s [[origin]]
- password
- -
+
password
+ -
credential’s password
- -
+
-
Return undefined.
3.3.4. Create a PasswordCredential from an HTMLFormElement
- To Create a PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
+ To Create a PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
Note: §3.1.2 Post-sign-in Confirmation and §3.1.3 Change Password provide examples of the intended
usage.
- -
+
-
Let data be a new PasswordCredentialData dictionary.
- -
-
Let formData be the result of executing the FormData constructor
+
-
+
Let formData be the result of executing the FormData constructor
on form.
- -
+
-
Let elements be a list of all the submittable elements whose form owner is form, in tree order.
- -
+
-
Let newPasswordObserved be false.
- -
+
-
For each field in elements, run the following steps:
- -
+
-
If field does not have an autocomplete attribute, then skip to the next field.
- -
+
-
Let name be the value of field’s name attribute.
- -
+
-
If formData’s has() method returns false when executed on name, then
skip to the next field.
- -
+
-
If field’s autocomplete attribute’s value contains one or more autofill
detail tokens (tokens), then:
- -
+
-
For each token in tokens:
- -
+
-
If token is an ASCII case-insensitive match for one
of the following strings, run the associated steps:
- - "
new-password"
- -
+
- "
new-password"
+ -
Set data’s password member’s
value to the result of executing formData’s get() method on name, and newPasswordObserved to true.
- - "
current-password"
- -
+
- "
current-password"
+ -
If newPasswordObserved is false,
set data’s password member’s
value to the result of executing formData’s get() method on name.
Note: By checking that newPasswordObserved is false, new-password fields take precedence over current-password fields.
- - "
photo"
- -
+
- "
photo"
+ -
Set data’s iconURL member’s
value to the result of executing formData’s get() method on name.
- - "
name"
- - "
nickname"
- -
+
- "
name"
+ - "
nickname"
+ -
Set data’s name member’s
value to the result of executing formData’s get() method on name.
- - "
username"
- -
+
- "
username"
+ -
Set data’s id member’s value to the
result of executing formData’s get() method
on name.
@@ -2761,106 +2790,106 @@
+
-
Let c be the result of executing Create a PasswordCredential from PasswordCredentialData on data.
- -
+
-
If c is an exception, return c.
- -
+
-
Assert: c is a PasswordCredential.
- -
+
-
Return c.
3.3.5. Create a PasswordCredential from PasswordCredentialData
- To Create a PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
+ To Create a PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
- -
+
-
Let c be a new PasswordCredential object.
- -
+
-
If any of the following are the empty string, return a TypeError exception:
- -
+
-
Set c’s properties as follows:
- -
+
-
Return c.
3.3.6. CredentialRequestOptions Matching for PasswordCredential
Given a CredentialRequestOptions (options), the following algorithm returns "Matches" if
the PasswordCredential should be available as a response to a get() request, and "Does Not Match" otherwise.
- -
+
-
If options has a password member whose value is true, then
return "Matches".
- -
+
-
Return "Does Not Match".
4. Federated Credentials
4.1. The FederatedCredential Interface
-[Constructor(FederatedCredentialInit data),
- Exposed=Window,
- SecureContext]
-interface FederatedCredential : Credential {
- readonly attribute USVString provider;
- readonly attribute DOMString? protocol;
+[Constructor (FederatedCredentialInit data Exposed =Window ,
+ SecureContext ]
+interface FederatedCredential Credential {
+ readonly attribute USVString provider ;
+ readonly attribute DOMString ? protocol ;
};
-FederatedCredential includes CredentialUserData;
+FederatedCredential includes CredentialUserData ;
-dictionary FederatedCredentialRequestOptions {
- sequence<USVString> providers;
- sequence<DOMString> protocols;
+dictionary FederatedCredentialRequestOptions sequence <USVString > providers sequence <DOMString > protocols federated;
+partial dictionary CredentialRequestOptions {
+ FederatedCredentialRequestOptions federated
- provider, of type USVString, readonly
- -
+
provider, of type USVString, readonly
+ -
The credential’s federated identity provider. See §4.1.1 Identifying Providers for
details regarding valid formats.
- protocol, of type DOMString, readonly, nullable
- -
+
protocol, of type DOMString, readonly, nullable
+ -
The credential’s federated identity provider’s protocol (e.g. "openidconnect"). If the
value is null, then the protocol can be inferred from the provider.
- [[type]]
- -
+
[[type]]
+ -
The FederatedCredential interface object has an internal slot named [[type]] whose
- value is "federated".
- [[discovery]]
- -
+ value is "
federated".
+ [[discovery]]
+ -
The FederatedCredential interface object has an internal slot named [[discovery]] whose value is "credential store".
- FederatedCredential(data)
- -
+
FederatedCredential(data)
+ -
This constructor accepts a FederatedCredentialInit (data), and runs the following steps:
- -
+
-
Let r be the result of executing Create a FederatedCredential from FederatedCredentialInit on data.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
@@ -2868,15 +2897,15 @@
FederatedCredential objects can be created by passing a FederatedCredentialInit dictionary
into navigator.credentials.create().
-dictionary FederatedCredentialInit : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString provider;
- DOMString protocol;
+dictionary FederatedCredentialInit CredentialData {
+ USVString name USVString iconURL required USVString provider DOMString protocol federated;
+partial dictionary CredentialCreationOptions {
+ FederatedCredentialInit federated
FederatedCredential objects are origin bound.
@@ -2896,116 +2925,116 @@ https://accounts.google.com.
4.2. Algorithms
4.2.1. FederatedCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors)
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
+
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
with a CredentialRequestOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns
a set of Credential objects from the credential store. If no matching Credential objects are available, the returned set will be empty.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
-
-
+
-
If |sameOriginWithAncestors is false, return a "NotAllowedError" DOMException.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
Return the empty set if options["federated"] is not true.
- -
+
-
Return the result of retrieving credentials from the credential store that match the following filter:
- -
+
-
The credential is a FederatedCredential
- -
+
-
The credential’s [[origin]] is the same origin as the current settings object's origin.
- -
+
-
If options["federated"]["providers"] exists, its value contains the credentials’s provider.
- -
+
-
If options["federated"]["protocols"] exists, its value contains the credentials’s protocol.
4.2.2. FederatedCredential's [[Create]](options, sameOriginWithAncestors)
- [[Create]](options, sameOriginWithAncestors) is
+
[[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a FederatedCredential if one can be created, null otherwise, or an exception in
exceptional circumstances:
- -
+
-
Assert: options["federated"] exists, and sameOriginWithAncestors is unused.
- -
+
-
Return the result of executing Create a FederatedCredential from FederatedCredentialInit on options["federated"].
4.2.3. FederatedCredential's [[Store]](credential, sameOriginWithAncestors)
- [[Store]](credential, sameOriginWithAncestors) is
+
[[Store]](credential, sameOriginWithAncestors) is
called with a FederatedCredential (credential), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns undefined once credential is persisted to the credential store.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
Return a "NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
If the user agent’s credential store contains a FederatedCredential whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]], and
whose provider is credential’s provider, then return.
- -
+
-
If the user grants permission to store credentials (as discussed when defining user mediation), then store a FederatedCredential in the credential store with
the following properties:
- -
+
-
Return undefined.
4.2.4. Create a FederatedCredential from FederatedCredentialInit
- To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
+ To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
- -
+
-
Let c be a new FederatedCredential object.
- -
+
-
If any of the following are the empty string, return a TypeError exception:
- -
+
-
Set c’s properties as follows:
- -
+
-
Return c.
@@ -3014,7 +3043,7 @@ user mediated if
+ We call a particular action user mediated if
it takes place after gaining a user’s explicit consent. Consent might be expressed through a
user’s direct interaction with a credential chooser interface, for example. In general, user
mediated actions will involve presenting the user some sort of UI, and asking them to make a
@@ -3031,7 +3060,7 @@
- -
+
-
Credential information SHOULD NOT be stored or updated without user mediation. For
example, the user agent could display a "Save this credential?" dialog box to the user in
response to each call to store().
@@ -3039,10 +3068,10 @@
- -
+
-
User agents SHOULD notify users when credentials are stored. This might take the form of an
icon in the address bar, or some similar location.
- -
+
-
User agents MUST allow users to manually remove stored credentials. This functionality might
be implemented as a settings page, or via interaction with a notification as described above.
@@ -3056,25 +3085,25 @@
To mitigate the risk of surprise:
- -
+
-
User agents MUST allow users to require user mediation for a given origin or for all
origins. This functionality might be implemented as a global toggle that overrides each
origin’s prevent silent access flag to return false, or via more granular
settings for specific origins (or specific credentials on specific origins).
- -
+
-
User agents MUST NOT set an origin's prevent silent access flag to false without user mediation. For example, the credential chooser described in §5.3 Credential Selection could have a checkbox which the user could toggle to mark a
credential as available without mediation for the origin, or the user agent could have an
onboarding process for its credential manager which asked a user for a default setting.
- -
+
-
User agents MUST notify users when credentials are provided to an origin. This could take the
form of an icon in the address bar, or some similar location.
- -
+
-
If a user clears her browsing data for an origin (cookies, localStorage, and so on), the user
agent MUST set the prevent silent access flag to true for that origin.
5.3. Credential Selection
When responding to a call to get() on an origin which requires user mediation, user agents MUST ask the user for permission to share credential information.
- This SHOULD take the form of a credential chooser which presents the user with a
+ This SHOULD take the form of a credential chooser which presents the user with a
list of credentials that are available for use on a site, allowing them to select one which should
be provided to the website, or to reject the request entirely.
The chooser interface SHOULD be implemented in such a way as to be distinguishable from UI which a
@@ -3092,7 +3121,7 @@
- The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
+ The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
This algorithm returns either null if the user chose not to share a credential with the site,
a Credential object if the user chose a specific credential, or a Credential interface
object if the user chose a type of credential.
@@ -3123,16 +3152,16 @@ example.com vs admin.example.com.
As a compromise between annoying users, and securing their credentials, user agents:
- -
+
-
MUST NOT share credentials between origins whose scheme components represent a downgrade in
security. That is, it may make sense to allow credentials saved on http://example.com/ to
be made available to https://example.com/ (in order to encourage developers to migrate to
secure transport), but the inverse would be dangerous.
- -
+
-
MAY use the Public Suffix List [PSL] to determine the effective scope of a credential by
comparing the registerable domain of the credential’s [[origin]] with the
origin in which get() is called. That is: credentials saved on https://admin.example.com/ and https://example.com/ MAY be offered to users when get() is called from https://www.example.com/, and vice versa.
- -
+
-
MUST NOT offer credentials to an origin in response to get() without user mediation if the credential’s origin is not an exact match for the calling origin.
That is, Credential objects for https://example.com would not be returned directly to https://www.example.com, but could be offered to the user via the chooser.
@@ -3142,14 +3171,14 @@ [CSP] which restricts the endpoints to which data can be sent. In particular, developers should ensure
that the following directives are set, explicitly or implicitly, in their pages' policies:
- -
+
-
script-src and object-src both restrict script execution on a page, making
it less likely that a cross-site scripting attack will succeed in the first place. If sites
are populating form elements, also form-action directives should be set.
- -
+
-
connect-src restricts the origins to which fetch() may submit data (which
mitigates the risk that credentials could be exfiltrated to evil.com.
- -
+
-
child-src restricts the nested browsing contexts which may be embedded in a page,
making it more difficult to inject a malicious postMessage() target. [WEBMESSAGING]
@@ -3221,7 +3250,7 @@ Add some thoughts here about when and how the API
should be used, especially with regard to mediation. <https://github.com/w3c/webappsec/issues/290>
Describe encoding restrictions of submitting credentials by fetch() with
- a FormData body.
+ a FormData body.
When performing feature detection for a given credential type, developers are encouraged to verify
that the relevant Credential specialization is present, rather than relying on the presence of navigator.credentals. The latter verifies the existence of the API itself, but does not ensure
that the specific kind of credential necessary for a given site is supported. For example, if a
@@ -3232,7 +3261,7 @@
credentials that serve specific authentication needs. Doing so is, hopefully,
straightforward:
- -
+
-
Define a new interface that inherits from Credential:
- -
+
-
Define appropriate [[Create]](options, sameOriginWithAncestors), [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors) methods on ExampleCredential's interface object. [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is appropriate for credentials that remain effective forever and
can therefore simply be copied out of the credential store, while [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is
appropriate for credentials that need to be re-generated from a credential source.
@@ -3254,27 +3283,27 @@ true iff the calling context is same-origin with its ancestors. The algorithm
returns a set of Credential objects that match the options provided. If no matching Credential objects are available, the returned set will be empty.
- -
+
-
Assert: options[example] exists.
- -
+
-
If options[example] is not truthy, return the empty set.
- -
+
-
For each credential in the credential store:
- -
+
-
...
-
-
+
-
Define the value of the ExampleCredential interface object's [[type]] slot:
The ExampleCredential interface object has an internal slot named [[type]] whose
value is the string "example".
- -
+
-
Define the value of the ExampleCredential interface object's [[discovery]] slot:
The ExampleCredential interface object has an internal slot named [[type]] whose
value is "credential store".
- -
+
-
Extend CredentialRequestOptions with the options the new credential type needs to respond
reasonably to get():
@@ -3288,7 +3317,7 @@
- -
+
-
Extend CredentialCreationOptions with the data the new credential type needs to create Credential objects in response to create():
@@ -3384,6 +3413,7 @@ collect local, in §2.5.2
- create(), in §2.3
+
- create a copy of any buffer sources' data, in §2.3.1
- Create a Credential, in §2.5.4
- Create a FederatedCredential from FederatedCredentialInit, in §4.2.4
- Create a PasswordCredential from an HTMLFormElement, in §3.3.4
@@ -3398,7 +3428,6 @@
Credential, in §2.2
- credential, in §2
-
- CredentialBodyType, in §3.2
- credential chooser, in §5.3
- CredentialCreationOptions, in §2.4
- CredentialData, in §2.3
@@ -3547,6 +3576,12 @@
6.2. Credential Leakage
+
-
+
+
+
+
+ do we need to explicitly free the bytes we just orphaned? ↵
This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in. ↵
@@ -4895,6 +4950,13 @@ 5.3. Credential Selection
+
+
+ To create a copy of any buffer sources' data referenced by a value |V| of
+ [=dictionary=] type, run the following steps given |V|:
+
+
+ 1. Let |dictionaries| be a list consisting of |V| and all of |V|'s
+ [=inherited dictionaries=], in order from least to most derived.
+
+ 2. For each dictionary |dictionary| in |dictionaries|, in order:
+
+ 1. For each dictionary member |member| declared on
+ |dictionary|, in lexicographical order:
+
+ 1. Let |key| be the [=identifier=] of |member|.
+
+ 2. If the dictionary member named |key| is [=present=] in |V|, then:
+
+ 1. Let |value| be the value of |member| on |V|.
+
+ 2. If |value|'s type is a [=buffer source type=] then
+ [=get a copy of the bytes held by the buffer source=] and
+ set |values|'s value to be a reference to the copy of the bytes.
+
+ issue: do we need to explicitly free the bytes we just orphaned?
+
+
+
+
### Mediation Requirements ### {#mediation-requirements}
When making a request via {{get(options)}}, developers can set a case-by-case requirement for
@@ -729,8 +757,10 @@ Request a `Credential`
5. Let |sameOriginWithAncestors| be `true` if |settings| is [=same-origin with its
ancestors=], and `false` otherwise.
+
+ 6. [=Create a copy of any buffer sources' data=] referenced by |options|.
- 6. Run the following steps [=in parallel=]:
+ 7. Run the following steps [=in parallel=]:
1. Let |credentials| be the result of collecting
`Credential`s from the credential store, given |options| and
@@ -775,7 +805,7 @@ Request a `Credential`
Otherwise, [=reject=] |p| with |result|.
- 7. Return |p|.
+ 8. Return |p|.
Collect `Credential`s from the credential store
@@ -868,9 +898,11 @@ Create a `Credential`
6. If |options|.{{CredentialCreationOptions/signal}}'s [=AbortSignal/aborted
flag=] is set, then return [=a promise rejected with=] an "{{AbortError}}" {{DOMException}}.
- 7. Let |p| be [=a new promise=].
+ 7. [=Create a copy of any buffer sources' data=] referenced by |options|.
+
+ 8. Let |p| be [=a new promise=].
- 8. Run the following steps [=in parallel=]:
+ 9. Run the following steps [=in parallel=]:
1. Let |r| be the result of executing |interfaces|[0]
{{Credential/[[Create]](options, sameOriginWithAncestors)}} internal method on |options|
@@ -880,7 +912,7 @@ Create a `Credential`
Otherwise, [=resolve=] |p| with |r|.
- 9. Return |p|.
+ 10. Return |p|.
Prevent Silent Access
User agents have an incredibly difficult time helping users with federated identity providers. While detecting a username/password form submission is fairly straightforward, detecting sign-in via a third-party is quite difficult to reliably do well. It would be nice if a website could help the user agent understand the intent behind the redirects associated with a typical federated sign-in action.
-Likewise, user agents struggle to detect more esoteric sign-in
mechanisms than simple username/password forms. Authors increasingly
asynchronously sign users in via XMLHttpRequest or similar
@@ -1707,7 +1707,7 @@
integrate into their password managers. It would be nice if a website
could help the user agent make sense of the sign-in mechanism they
choose to use.
- -
+
-
Finally, changing passwords is less well-supported than it could be if
the website explicitly informed the user agent that credentials had
changed.
@@ -1715,7 +1715,7 @@
2. Core API
- From a developer’s perspective, a credential is an
+
From a developer’s perspective, a credential is an
object which allows a developer to make an authentication decision for a particular action. This
section defines a generic and extensible Credential interface which serves as a base class
for credentials defined in this and other documents, along with a set of APIs
@@ -1723,18 +1723,18 @@
2.
Various types of credentials are represented to JavaScript as an interface which inherits, either directly or indirectly, from the Credential interface. This
document defines two such interfaces, PasswordCredential and FederatedCredential.
- A credential is effective for a particular origin if it
+
A credential is effective for a particular origin if it
is accepted as authentication on that origin. Even if a credential is effective at a particular
point in time, the UA can’t assume that the same credential will be effective at any future time,
for a couple reasons:
- -
+
-
A password credential may stop being effective if the account holder changes their password.
- -
+
-
A credential made from a token received over SMS is likely to only be effective for a single
use.
- Single-use credentials are generated by a credential source, which could be
+
Single-use credentials are generated by a credential source, which could be
a private key, access to a federated account, the ability to receive SMS messages at a particular
phone number, or something else. Credential sources are not exposed to Javascript or explicitly
represented in this specification. To unify the model, we consider a password to be a credential
@@ -1746,80 +1746,80 @@
2. offering effective credential
sources to the user in the future.
2.1. Infrastructure
- User agents MUST internally provide a credential
+ User agents MUST internally provide a credential
store, which is a vendor-specific, opaque storage mechanism to record which credentials have been effective. It offers the following capabilities for credential access and
persistence:
- -
-
-
+
Store a credential for later retrieval.
This accepts a credential, and inserts it into the credential store.
- -
-
Retrieve a list of credentials. This
+
-
+
Retrieve a list of credentials. This
accepts an arbitrary filter, and returns a set of credentials that match the filter.
- -
-
Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store.
+ -
+
Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store.
- Additionally, the credential store should maintain a prevent silent access flag for origins (which is set to true unless otherwise specified).
- An origin requires user mediation if its flag is set to true.
+ Additionally, the credential store should maintain a prevent silent access flag for origins (which is set to true unless otherwise specified).
+ An origin requires user mediation if its flag is set to true.
Note: The importance of user mediation is discussed in more detail in §5 User Mediation.
Note: The credential store is an internal implementation detail of a user agent’s
implementation of the API specified in this document, and is not exposed to the web directly.
More capabilities may be specified by other documents in support of specific credential types.
This document depends on the Infra Standard for a number of foundational concepts used in its
algorithms and prose [INFRA].
- An environment settings object (settings) is same-origin with its
+ An environment settings object (settings) is same-origin with its
ancestors if the following algorithm returns true:
- -
+
-
If settings has no responsible browsing context,
return false.
- -
+
-
Let origin be settings’ origin.
- -
+
-
Let current be settings’ responsible browsing context.
- -
+
-
While current has a parent browsing context:
- -
+
-
Set current to current’s parent browsing context.
- -
+
-
If current’s active document's origin is not same origin with origin,
return false.
- -
+
-
Return true.
2.2. The Credential Interface
-[Exposed=Window, SecureContext]
-interface Credential {
- readonly attribute USVString id;
- readonly attribute DOMString type;
+[Exposed =Window , SecureContext ]
+interface Credential readonly attribute USVString id ;
+ readonly attribute DOMString type ;
};
- id, of type USVString, readonly
- -
+
id, of type USVString, readonly
+ -
The credential’s identifier. The requirements for the identifier are distinct for each type
of credential. It might represent a username for username/password tuples, for example.
- type, of type DOMString, readonly
- -
+
type, of type DOMString, readonly
+ -
This attribute’s getter returns the value of the object’s interface object's [[type]] slot, which specifies the kind of credential represented by this object.
- [[type]]
- -
+
[[type]]
+ -
The Credential interface object has an internal slot named [[type]], which
unsurprisingly contains a string representing the type of the credential. The slot’s value
is the empty string unless otherwise specified.
Note: The [[type]] slot’s value will be the same for all credentials implementing a
particular interface, which means that developers can rely on obj.type returning a string
that unambigiously represents the specific kind of Credential they’re dealing with.
- [[discovery]]
- -
+
[[discovery]]
+ -
The Credential interface object has an internal slot named [[discovery]],
representing the mechanism by which the user agent can collect credentials of
a given type. Its value is either
- "credential store" or
- "remote". The former value means that
+ "credential store" or
+ "remote". The former value means that
all available credential information is stored in the user agent’s credential store,
while the latter means that the user agent can discover credentials outside of those
explicitly represented in the credential store via interaction with some external device
@@ -1828,46 +1828,46 @@
Talk to Tobie/Dominic about the interface object bits, here and in §2.5.1 Request a Credential, etc. I’m not sure I’ve gotten the terminology right. interface prototype
object, maybe?
- Some Credential objects are origin bound: these contain an
- internal slot named [[origin]], which stores the origin for which the Credential may be effective.
+ Some Credential objects are origin bound: these contain an
+ internal slot named [[origin]], which stores the origin for which the Credential may be effective.
2.2.1. Credential Internal Methods
Each interface object created for interfaces which inherit from Credential defines several internal methods that allow retrieval and storage of Credential objects:
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
+ [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
set of Credential objects from the user agent’s credential store that match the options
provided. If no matching Credential objects are available, the returned set will be empty.
- -
+
-
Return an empty set.
- [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
+ [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
caller’s environment settings object is same-origin with its ancestors. It returns a Credential if one can be returned given the options provided, null if no credential is
available, or an error if discovery fails (for example, incorrect options could produce a TypeError). If this kind of Credential is only effective for a single use or a
limited time, this method is responsible for generating new credentials using a credential source.
- -
+
-
Return null.
- [[Store]](credential, sameOriginWithAncestors) is
+ [[Store]](credential, sameOriginWithAncestors) is
called with a Credential, and a boolean which is true iff the caller’s environment
settings object is same-origin with its ancestors. The algorithm returns once Credential is persisted to the credential store:
- -
+
-
Return undefined.
- [[Create]](options, sameOriginWithAncestors) is
+ [[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions, and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns
either a Credential, if one can be created, null if no credential was created, or an
error if creation fails due to exceptional situations (for example, incorrect options could
produce a TypeError):
- -
+
-
Return null.
@@ -1876,20 +1876,20 @@
2.2.2. CredentialUserData Mixin
Some Credential objects contain data which aims to give users a human-readable disambiguation
mechanism in the credential chooser by providing a friendly name and icon:
-[SecureContext]
-interface mixin CredentialUserData {
- readonly attribute USVString name;
- readonly attribute USVString iconURL;
+[SecureContext ]
+interface mixin CredentialUserData readonly attribute USVString name ;
+ readonly attribute USVString iconURL ;
};
- name, of type USVString, readonly
- -
+
name, of type USVString, readonly
+ -
A name associated with the credential, intended as a human-understandable public name for
display in a credential chooser.
- iconURL, of type USVString, readonly
- -
+
iconURL, of type USVString, readonly
+ -
A URL pointing to an image for the credential, intended for display in a credential chooser. This URL MUST be an a priori authenticated
URL.
@@ -1897,28 +1897,28 @@ 2.3. navigator.credentials
Developers retrieve Credentials and interact with the user agent’s credential store via
methods exposed on the CredentialsContainer interface, which hangs off the Navigator object as navigator.credentials.
-partial interface Navigator {
- [SecureContext, SameObject] readonly attribute CredentialsContainer credentials;
+partial interface Navigator {
+ [SecureContext , SameObject ] readonly attribute CredentialsContainer credentials ;
};
- The credentials attribute MUST return the CredentialsContainer associated with the context object.
+ The credentials attribute MUST return the CredentialsContainer associated with the context object.
Note: As discussed in §6.3 Insecure Sites, the credential management API is exposed only in Secure Contexts.
-[Exposed=Window, SecureContext]
-interface CredentialsContainer {
- Promise<Credential?> get(optional CredentialRequestOptions options);
- Promise<Credential> store(Credential credential);
- Promise<Credential?> create(optional CredentialCreationOptions options);
- Promise<void> preventSilentAccess();
+[Exposed =Window , SecureContext ]
+interface CredentialsContainer Promise <Credential ?> get (optional CredentialRequestOptions options );
+ Promise <Credential > store (Credential credential );
+ Promise <Credential ?> create (optional CredentialCreationOptions options );
+ Promise <void > preventSilentAccess ();
};
-dictionary CredentialData {
- required USVString id;
+dictionary CredentialData required USVString id
- get(options)
- -
+
get(options)
+ -
When get() is called, the user agent MUST return the result of
executing Request a Credential on options.
@@ -1932,14 +1932,14 @@ options
+ options
CredentialRequestOptions
✘
✔
The set of properties governing the scope of the request.
- store(credential)
- -
+
store(credential)
+ -
When store() is called, the user agent MUST return the result of
executing Store a Credential on credential.
@@ -1953,14 +1953,14 @@ credential
+ credential
Credential
✘
✘
The credential to be stored.
- create(options)
- -
+
create(options)
+ -
When create() is called, the user agent MUST return the result of
executing Create a Credential on options.
@@ -1974,14 +1974,14 @@ options
+ options
CredentialCreationOptions
✘
✔
The options used to create a Credential.
- preventSilentAccess()
- -
+
preventSilentAccess()
+ -
When preventSilentAccess() is called, the user agent MUST return
the result of executing Prevent Silent Access on the current settings
object.
@@ -2002,20 +2002,20 @@ Note: The CredentialRequestOptions dictionary is an extension point. If and when new types of
credentials are introduced that require options, their dictionary types will be added to the
dictionary so they can be passed into the request. See §7.2 Extension Points.
-dictionary CredentialRequestOptions {
- CredentialMediationRequirement mediation = "optional";
- AbortSignal signal;
+dictionary CredentialRequestOptions CredentialMediationRequirement mediation = "optional";
+ AbortSignal signal ;
};
- mediation, of type CredentialMediationRequirement, defaulting to "optional"
- -
+
mediation, of type CredentialMediationRequirement, defaulting to "optional"
+ -
This property specifies the mediation requirements for a given credential request. The
meaning of each enum value is described below in CredentialMediationRequirement.
Processing details are defined in §2.5.1 Request a Credential.
- signal, of type AbortSignal
- -
+
signal, of type AbortSignal
+ -
This property lets the developer abort an ongoing get() operation.
An aborted operation may complete normally (generally if the abort was received after the
operation finished) or reject with an "AbortError" DOMException."
@@ -2029,22 +2029,22 @@ mediation.
- The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
+ The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
- -
+
-
Let settings be the current settings object
- -
+
-
Let interface objects be the set of interface objects on settings’ global object.
- -
+
-
Let relevant interface objects be an empty set.
- -
+
-
For each object in interface objects:
- -
+
-
If object’s inherited interfaces do not contain Credential, continue.
- -
+
-
Let key be object’s [[type]] slot’s value.
- -
+
-
If options[key] exists, append object to relevant interface objects.
@@ -2053,17 +2053,17 @@
- A given CredentialRequestOptions options is matchable a priori if the following
+ A given CredentialRequestOptions options is matchable a priori if the following
steps return true:
- -
+
-
For each interface in options’ relevant credential interface objects:
- -
+
-
If interface’s [[discovery]] slot’s value is not
"credential store", return false.
- -
+
-
Return true.
Note: When executing get(options), we only return credentials without user mediation if
@@ -2072,20 +2072,47 @@
user mediation will be required in order
to guide the discovery process (by choosing a federated identity provider, BTLE device, etc).
+
+ To create a copy of any buffer sources' data referenced by a value V of dictionary type, run the following steps given V:
+
+ -
+
Let dictionaries be a list consisting of V and all of V’s inherited dictionaries, in order from least to most derived.
+ -
+
For each dictionary dictionary in dictionaries, in order:
+
+ -
+
For each dictionary member member declared on dictionary, in lexicographical order:
+
+ -
+
Let key be the identifier of member.
+ -
+
If the dictionary member named key is present in V, then:
+
+ -
+
Let value be the value of member on V.
+ -
+
If value’s type is a buffer source type then get a copy of the bytes held by the buffer source and
+set values’s value to be a reference to the copy of the bytes.
+
+
+
+
+
+
2.3.2. Mediation Requirements
When making a request via get(options), developers can set a case-by-case requirement for user mediation by choosing the appropriate CredentialMediationRequirement enum value.
Note: The §5 User Mediation section gives more detail on the concept in general, and its
implications on how the user agent deals with individual requests for a given origin).
-enum CredentialMediationRequirement {
- "silent",
- "optional",
- "required"
+enum CredentialMediationRequirement "silent" ,
+ "optional" ,
+ "required"
};
- silent
- -
+
silent
+ -
User mediation is suppressed for the given operation. If the operation can be performed
without user involvement, wonderful. If user involvement is necessary, then the operation
will return null rather than involving the user.
@@ -2093,8 +2120,8 @@ , where a developer may wish to silently obtain
credentials if a user should be automatically signed in, but to delay bothering the user
with a sign-in prompt until they actively choose to sign-in.
- optional
- -
+
optional
+ -
If credentials can be handed over for a given operation without user mediation, they will
be. If user mediation is required, then the user agent will
involve the user in the decision.
@@ -2102,8 +2129,8 @@ credential chooser if necessary.
- required
- -
+
required
+ -
The user agent will not hand over credentials without user mediation, even if the prevent silent access flag is unset for an origin.
Note: This requirement is intended to support reauthentication or user-switching scenarios. Further, the requirement is tied
to a specific operation, and does not affect the prevent silent access flag for the
@@ -2118,7 +2145,7 @@
§5.2 Requiring User Mediation)
are signed in, and users who haven’t opted-into such behavior won’t be bothered with a confusing credential chooser popping up without context:
window.addEventListener('load', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'silent'
});
@@ -2133,7 +2160,7 @@ opted-into signing in without user mediation, and the user agent can unambigiously choose a credential, great! If
not, a credential chooser will be presented.
document.querySelector('#sign-in').addEventListener('click', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'optional'
});
@@ -2154,7 +2181,7 @@
document.querySelector('#important-form').addEventListener('submit', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2173,7 +2200,7 @@ required" in order to ensure that that credentials aren’t
returned automatically in response to clicking on an "Add account" button:
document.querySelector('#switch-button').addEventListener('click', e => {
- var c = await navigatior.credentials.get({
+ var c = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2189,192 +2216,196 @@ Note: The CredentialCreationOptions dictionary is an extension point. If and when new types of
credentials are introduced, they will add to the dictionary so they can be passed into the
creation method. See §7.2 Extension Points, and the extensions introduced in this document: §3.2 The PasswordCredential Interface and §4.1 The FederatedCredential Interface.
-dictionary CredentialCreationOptions {
- AbortSignal signal;
+dictionary CredentialCreationOptions AbortSignal signal ;
};
- signal, of type AbortSignal
- -
+
signal, of type AbortSignal
+ -
This property lets the developer abort an ongoing create() operation. An aborted operation may complete normally (generally if the abort was received
after the operation finished) or reject with an "AbortError" DOMException."
2.5. Algorithms
2.5.1. Request a Credential
- The Request a Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
+
The Request a Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
unambigiously obtained, or with null if not.
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
If options.signal’s aborted flag is set, then return a promise rejected with an "AbortError" DOMException.
- -
+
-
Let p be a new promise.
- -
+
-
Let sameOriginWithAncestors be true if settings is same-origin with its
ancestors, and false otherwise.
- -
+
-
+
Create a copy of any buffer sources' data referenced by options.
+ -
Run the following steps in parallel:
- -
+
-
Let credentials be the result of collecting Credentials from the credential store, given options and sameOriginWithAncestors.
- -
+
-
-
-
+
-
If all of the following statements are true, resolve p with credentials[0] and
skip the remaining steps:
- -
+
-
credentials’ size is 1
- -
+
-
settings’ origin does not require user mediation
- -
+
-
options is matchable a priori.
- -
+
-
This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in.
- -
+
-
If options’ mediation is
"silent", resolve p with null, and skip
the remaining steps.
- -
+
-
Let choice be the result of asking the user to
choose a Credential, given options and credentials.
- -
+
-
If choice is null or a Credential, resolve p with choice and skip the
remaining steps.
- -
+
-
Assert: choice is an interface object.
- -
+
-
Let result be the result of executing choice’s [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), given options and sameOriginWithAncestors.
- -
+
-
If result is a Credential or null, resolve p with result.
Otherwise, reject p with result.
- -
+
-
Return p.
2.5.2. Collect Credentials from the credential store
Given a CredentialRequestOptions (options) and a boolean which is true iff the calling
- context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
+ context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
returning a set of Credential objects stored by the user agent locally that match options’
filter. If no such Credential objects are known, the returned set will be empty:
- -
+
-
Let possible matches be an empty set.
- -
+
-
For each interface in options’ relevant credential interface objects:
- -
+
-
Let r be the result of executing interface’s [[CollectFromCredentialStore]](options, sameOriginWithAncestors) internal
method on options and sameOriginWithAncestors.
- -
+
-
If r is an exception, return r.
- -
+
-
Assert: r is a list of interface objects.
- -
+
-
For each c in r:
- -
+
-
Append c to possible matches.
- -
+
-
Return possible matches.
2.5.3. Store a Credential
- The Store a Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
+ The Store a Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
Let sameOriginWithAncestors be true if the current settings object is same-origin
with its ancestors, and false otherwise.
- -
+
-
Let p be a new promise.
- -
+
-
Run the following steps in parallel:
- -
+
-
Let r be the result of executing credential’s interface object's [[Store]](credential, sameOriginWithAncestors) internal method on credential and sameOriginWithAncestors.
- -
+
-
If r is an exception, reject p with r.
Otherwise, resolve p with r.
- -
+
-
Return p.
2.5.4. Create a Credential
- The Create a Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
+
The Create a Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
using the options provided, or null if no Credential can be created. In exceptional
circumstances, the Promise may reject with an appropriate exception:
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
Let sameOriginWithAncestors be true if the current settings object is same-origin
with its ancestors, and false otherwise.
- -
+
-
Let interfaces be the set of options’ relevant credential interface objects.
- -
+
-
Return a promise rejected with NotSupportedError if any of the following statements
are true:
- -
+
-
settings does not have a responsible document.
- -
+
-
interfaces’ size is greater than 1.
Note: It may be reasonable at some point in the future to loosen this restriction, and
allow the user agent to help the user choose among one of many potential credential
types in order to support a "sign-up" use case. For the moment, though, we’re punting
on that by restricting the dictionary to a single entry.
- -
+
-
If options.signal’s aborted
flag is set, then return a promise rejected with an "AbortError" DOMException.
- -
+
-
+
Create a copy of any buffer sources' data referenced by options.
+ -
Let p be a new promise.
- -
+
-
Run the following steps in parallel:
- -
+
-
Let r be the result of executing interfaces[0] [[Create]](options, sameOriginWithAncestors) internal method on options and sameOriginWithAncestors.
- -
+
-
If r is an exception, reject p with r.
Otherwise, resolve p with r.
- -
+
-
Return p.
2.5.5. Prevent Silent Access
- The Prevent Silent Access algorithm accepts an environment settings
+ The Prevent Silent Access algorithm accepts an environment settings
object (settings), and returns a Promise which resolves once the prevent silent access flag is persisted to the credential store.
- -
+
-
Let origin be settings’ origin.
- -
+
-
Let p be a new promise
- -
+
-
Run the following seps in parallel:
- -
+
-
Set origin’s prevent silent access flag in the credential store.
- -
+
-
Resolve p with undefined.
- -
+
-
Retun p.
@@ -2386,8 +2417,8 @@ 3.
from within a credential chooser.
3.1. Examples
3.1.1. Password-based Sign-in
-
- MegaCorp, Inc. supports passwords, and can use navigator.credentials.get() to obtain
+
+ MegaCorp, Inc. supports passwords, and can use navigator.credentials.get() to obtain
username/password pairs from a user’s credential store:
navigator.credentials
.get({ 'password': true })
@@ -2429,12 +2460,12 @@ type == 'password') {
- document.getQuerySelector('input[name=username_field]').value =
- credential.id;
- document.getQuerySelector('input[name=password_field]').value =
- credential.password;
- document.getQuerySelector('#myform').submit();
+ if (credential.type === 'password') {
+ document.querySelector('input[name=username_field]').value =
+ credential.id;
+ document.querySelector('input[name=password_field]').value =
+ credential.password;
+ document.getElementById('myform').submit();
}
});
@@ -2538,51 +2569,49 @@
3.2. The PasswordCredential Interface
-typedef (FormData or URLSearchParams) CredentialBodyType;
-
-[Constructor(HTMLFormElement form),
- Constructor(PasswordCredentialData data),
- Exposed=Window,
- SecureContext]
-interface PasswordCredential : Credential {
- readonly attribute USVString password;
+[Constructor (HTMLFormElement form Constructor (PasswordCredentialData data Exposed =Window ,
+ SecureContext ]
+interface PasswordCredential Credential {
+ readonly attribute USVString password ;
};
-PasswordCredential includes CredentialUserData;
+PasswordCredential includes CredentialUserData ;
-partial dictionary CredentialRequestOptions {
- boolean password = false;
+partial dictionary CredentialRequestOptions {
+ boolean password false ;
};
- password, of type USVString, readonly
- -
+
password, of type USVString, readonly
+ -
This attribute represents the password of the credential.
- [[type]]
- -
+
[[type]]
+ -
The PasswordCredential interface object has an internal slot named [[type]] whose
- value is "password".
- [[discovery]]
- -
+ value is "
password".
+ [[discovery]]
+ -
The PasswordCredential interface object has an internal slot named [[discovery]] whose value is "credential store".
- PasswordCredential(form)
- -
+
PasswordCredential(form)
+ -
This constructor accepts an HTMLFormElement (form), and runs the following steps:
- -
+
-
Let r be the result of executing Create a PasswordCredential from
an HTMLFormElement on form.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
- PasswordCredential(data)
- -
+
PasswordCredential(data)
+ -
This constructor accepts a PasswordCredentialData (data), and runs the following steps:
- -
+
-
Let r be the result of executing Create a PasswordCredential from PasswordCredentialData on data.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
@@ -2590,16 +2619,16 @@ <
PasswordCredential objects can be created via navigator.credentials.create() either explicitly by passing in a PasswordCredentialData dictionary, or based on the contents
of an HTMLFormElement's submittable elements.
-dictionary PasswordCredentialData : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString password;
+dictionary PasswordCredentialData CredentialData {
+ USVString name USVString iconURL required USVString password PasswordCredentialInit;
+typedef (PasswordCredentialData or HTMLFormElement ) PasswordCredentialInit password;
+partial dictionary CredentialCreationOptions {
+ PasswordCredentialInit password
PasswordCredential objects are origin bound.
@@ -2607,153 +2636,153 @@ <
own implementation of [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[Create]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors).
3.3. Algorithms
3.3.1. PasswordCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors)
-
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
+
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a set of Credential objects from the credential store. If no matching Credential objects are available, or sameOriginWithAncestors is false, the returned set
will be empty.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
-
-
+
-
If |sameOriginWithAncestors is false, return a "NotAllowedError" DOMException.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
Return the empty set if options["password"] is not true.
- -
+
-
Return the result of retrieving credentials from the credential store that match the following filter:
- -
+
-
The credential is a PasswordCredential
- -
+
-
The credential’s [[origin]] is the same origin as the current settings object's origin.
3.3.2. PasswordCredential's [[Create]](options, sameOriginWithAncestors)
- [[Create]](options, sameOriginWithAncestors) is called
+
[[Create]](options, sameOriginWithAncestors) is called
with a CredentialCreationOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns a PasswordCredential if one can be created, and null otherwise. The CredentialCreationOptions dictionary must have a password member which holds either an HTMLFormElement or a PasswordCredentialData. If that member’s value cannot be
used to create a PasswordCredential, this algorithm will return a TypeError exception.
- -
+
-
Assert: options["password"] exists, and sameOriginWithAncestors is unused.
- -
+
-
If options["password"] is an HTMLFormElement, return the
result of executing Create a PasswordCredential from an HTMLFormElement on options["password"].
- -
+
-
If options["password"] is a PasswordCredentialData, return
the result of executing Create a PasswordCredential from PasswordCredentialData on options["password"].
- -
+
-
3.3.3. PasswordCredential's [[Store]](credential, sameOriginWithAncestors)
- [[Store]](credential, sameOriginWithAncestors) is
+
[[Store]](credential, sameOriginWithAncestors) is
called with a PasswordCredential (credential), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns undefined once credential is persisted to the credential store.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
Return a "NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
If the user agent’s credential store contains a PasswordCredential (stored)
whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]],
then:
- -
+
-
If the user grants permission to update credentials (as discussed when defining user mediation), then:
Otherwise, if the user grants permission to store credentials (as discussed when
defining user mediation, then:
- -
+
-
Store a PasswordCredential in the credential store with the following
properties:
- id
- -
+
id
+ -
credential’s id
- name,
- -
+
name,
+ -
credential’s name
- iconURL
- -
+
iconURL
+ -
credential’s iconURL
- [[origin]]
- -
+
[[origin]]
+ -
credential’s [[origin]]
- password
- -
+
password
+ -
credential’s password
- -
+
-
Return undefined.
3.3.4. Create a PasswordCredential from an HTMLFormElement
- To Create a PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
+ To Create a PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
Note: §3.1.2 Post-sign-in Confirmation and §3.1.3 Change Password provide examples of the intended
usage.
- -
+
-
Let data be a new PasswordCredentialData dictionary.
- -
-
Let formData be the result of executing the FormData constructor
+
-
+
Let formData be the result of executing the FormData constructor
on form.
- -
+
-
Let elements be a list of all the submittable elements whose form owner is form, in tree order.
- -
+
-
Let newPasswordObserved be false.
- -
+
-
For each field in elements, run the following steps:
- -
+
-
If field does not have an autocomplete attribute, then skip to the next field.
- -
+
-
Let name be the value of field’s name attribute.
- -
+
-
If formData’s has() method returns false when executed on name, then
skip to the next field.
- -
+
-
If field’s autocomplete attribute’s value contains one or more autofill
detail tokens (tokens), then:
- -
+
-
For each token in tokens:
- -
+
-
If token is an ASCII case-insensitive match for one
of the following strings, run the associated steps:
- - "
new-password"
- -
+
- "
new-password"
+ -
Set data’s password member’s
value to the result of executing formData’s get() method on name, and newPasswordObserved to true.
- - "
current-password"
- -
+
- "
current-password"
+ -
If newPasswordObserved is false,
set data’s password member’s
value to the result of executing formData’s get() method on name.
Note: By checking that newPasswordObserved is false, new-password fields take precedence over current-password fields.
- - "
photo"
- -
+
- "
photo"
+ -
Set data’s iconURL member’s
value to the result of executing formData’s get() method on name.
- - "
name"
- - "
nickname"
- -
+
- "
name"
+ - "
nickname"
+ -
Set data’s name member’s
value to the result of executing formData’s get() method on name.
- - "
username"
- -
+
- "
username"
+ -
Set data’s id member’s value to the
result of executing formData’s get() method
on name.
@@ -2761,106 +2790,106 @@
+
-
Let c be the result of executing Create a PasswordCredential from PasswordCredentialData on data.
- -
+
-
If c is an exception, return c.
- -
+
-
Assert: c is a PasswordCredential.
- -
+
-
Return c.
3.3.5. Create a PasswordCredential from PasswordCredentialData
- To Create a PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
+ To Create a PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
- -
+
-
Let c be a new PasswordCredential object.
- -
+
-
If any of the following are the empty string, return a TypeError exception:
- -
+
-
Set c’s properties as follows:
- -
+
-
Return c.
3.3.6. CredentialRequestOptions Matching for PasswordCredential
Given a CredentialRequestOptions (options), the following algorithm returns "Matches" if
the PasswordCredential should be available as a response to a get() request, and "Does Not Match" otherwise.
- -
+
-
If options has a password member whose value is true, then
return "Matches".
- -
+
-
Return "Does Not Match".
4. Federated Credentials
4.1. The FederatedCredential Interface
-[Constructor(FederatedCredentialInit data),
- Exposed=Window,
- SecureContext]
-interface FederatedCredential : Credential {
- readonly attribute USVString provider;
- readonly attribute DOMString? protocol;
+[Constructor (FederatedCredentialInit data Exposed =Window ,
+ SecureContext ]
+interface FederatedCredential Credential {
+ readonly attribute USVString provider ;
+ readonly attribute DOMString ? protocol ;
};
-FederatedCredential includes CredentialUserData;
+FederatedCredential includes CredentialUserData ;
-dictionary FederatedCredentialRequestOptions {
- sequence<USVString> providers;
- sequence<DOMString> protocols;
+dictionary FederatedCredentialRequestOptions sequence <USVString > providers sequence <DOMString > protocols federated;
+partial dictionary CredentialRequestOptions {
+ FederatedCredentialRequestOptions federated
- provider, of type USVString, readonly
- -
+
provider, of type USVString, readonly
+ -
The credential’s federated identity provider. See §4.1.1 Identifying Providers for
details regarding valid formats.
- protocol, of type DOMString, readonly, nullable
- -
+
protocol, of type DOMString, readonly, nullable
+ -
The credential’s federated identity provider’s protocol (e.g. "openidconnect"). If the
value is null, then the protocol can be inferred from the provider.
- [[type]]
- -
+
[[type]]
+ -
The FederatedCredential interface object has an internal slot named [[type]] whose
- value is "federated".
- [[discovery]]
- -
+ value is "
federated".
+ [[discovery]]
+ -
The FederatedCredential interface object has an internal slot named [[discovery]] whose value is "credential store".
- FederatedCredential(data)
- -
+
FederatedCredential(data)
+ -
This constructor accepts a FederatedCredentialInit (data), and runs the following steps:
- -
+
-
Let r be the result of executing Create a FederatedCredential from FederatedCredentialInit on data.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
@@ -2868,15 +2897,15 @@
FederatedCredential objects can be created by passing a FederatedCredentialInit dictionary
into navigator.credentials.create().
-dictionary FederatedCredentialInit : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString provider;
- DOMString protocol;
+dictionary FederatedCredentialInit CredentialData {
+ USVString name USVString iconURL required USVString provider DOMString protocol federated;
+partial dictionary CredentialCreationOptions {
+ FederatedCredentialInit federated
FederatedCredential objects are origin bound.
@@ -2896,116 +2925,116 @@ https://accounts.google.com.
4.2. Algorithms
4.2.1. FederatedCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors)
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
+
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
with a CredentialRequestOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns
a set of Credential objects from the credential store. If no matching Credential objects are available, the returned set will be empty.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
-
-
+
-
If |sameOriginWithAncestors is false, return a "NotAllowedError" DOMException.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
Return the empty set if options["federated"] is not true.
- -
+
-
Return the result of retrieving credentials from the credential store that match the following filter:
- -
+
-
The credential is a FederatedCredential
- -
+
-
The credential’s [[origin]] is the same origin as the current settings object's origin.
- -
+
-
If options["federated"]["providers"] exists, its value contains the credentials’s provider.
- -
+
-
If options["federated"]["protocols"] exists, its value contains the credentials’s protocol.
4.2.2. FederatedCredential's [[Create]](options, sameOriginWithAncestors)
- [[Create]](options, sameOriginWithAncestors) is
+
[[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a FederatedCredential if one can be created, null otherwise, or an exception in
exceptional circumstances:
- -
+
-
Assert: options["federated"] exists, and sameOriginWithAncestors is unused.
- -
+
-
Return the result of executing Create a FederatedCredential from FederatedCredentialInit on options["federated"].
4.2.3. FederatedCredential's [[Store]](credential, sameOriginWithAncestors)
- [[Store]](credential, sameOriginWithAncestors) is
+
[[Store]](credential, sameOriginWithAncestors) is
called with a FederatedCredential (credential), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns undefined once credential is persisted to the credential store.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
Return a "NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
If the user agent’s credential store contains a FederatedCredential whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]], and
whose provider is credential’s provider, then return.
- -
+
-
If the user grants permission to store credentials (as discussed when defining user mediation), then store a FederatedCredential in the credential store with
the following properties:
- -
+
-
Return undefined.
4.2.4. Create a FederatedCredential from FederatedCredentialInit
- To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
+ To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
- -
+
-
Let c be a new FederatedCredential object.
- -
+
-
If any of the following are the empty string, return a TypeError exception:
- -
+
-
Set c’s properties as follows:
- -
+
-
Return c.
@@ -3014,7 +3043,7 @@ user mediated if
+ We call a particular action user mediated if
it takes place after gaining a user’s explicit consent. Consent might be expressed through a
user’s direct interaction with a credential chooser interface, for example. In general, user
mediated actions will involve presenting the user some sort of UI, and asking them to make a
@@ -3031,7 +3060,7 @@
- -
+
-
Credential information SHOULD NOT be stored or updated without user mediation. For
example, the user agent could display a "Save this credential?" dialog box to the user in
response to each call to store().
@@ -3039,10 +3068,10 @@
- -
+
-
User agents SHOULD notify users when credentials are stored. This might take the form of an
icon in the address bar, or some similar location.
- -
+
-
User agents MUST allow users to manually remove stored credentials. This functionality might
be implemented as a settings page, or via interaction with a notification as described above.
@@ -3056,25 +3085,25 @@
To mitigate the risk of surprise:
- -
+
-
User agents MUST allow users to require user mediation for a given origin or for all
origins. This functionality might be implemented as a global toggle that overrides each
origin’s prevent silent access flag to return false, or via more granular
settings for specific origins (or specific credentials on specific origins).
- -
+
-
User agents MUST NOT set an origin's prevent silent access flag to false without user mediation. For example, the credential chooser described in §5.3 Credential Selection could have a checkbox which the user could toggle to mark a
credential as available without mediation for the origin, or the user agent could have an
onboarding process for its credential manager which asked a user for a default setting.
- -
+
-
User agents MUST notify users when credentials are provided to an origin. This could take the
form of an icon in the address bar, or some similar location.
- -
+
-
If a user clears her browsing data for an origin (cookies, localStorage, and so on), the user
agent MUST set the prevent silent access flag to true for that origin.
5.3. Credential Selection
When responding to a call to get() on an origin which requires user mediation, user agents MUST ask the user for permission to share credential information.
- This SHOULD take the form of a credential chooser which presents the user with a
+ This SHOULD take the form of a credential chooser which presents the user with a
list of credentials that are available for use on a site, allowing them to select one which should
be provided to the website, or to reject the request entirely.
The chooser interface SHOULD be implemented in such a way as to be distinguishable from UI which a
@@ -3092,7 +3121,7 @@
- The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
+ The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
This algorithm returns either null if the user chose not to share a credential with the site,
a Credential object if the user chose a specific credential, or a Credential interface
object if the user chose a type of credential.
@@ -3123,16 +3152,16 @@ example.com vs admin.example.com.
As a compromise between annoying users, and securing their credentials, user agents:
- -
+
-
MUST NOT share credentials between origins whose scheme components represent a downgrade in
security. That is, it may make sense to allow credentials saved on http://example.com/ to
be made available to https://example.com/ (in order to encourage developers to migrate to
secure transport), but the inverse would be dangerous.
- -
+
-
MAY use the Public Suffix List [PSL] to determine the effective scope of a credential by
comparing the registerable domain of the credential’s [[origin]] with the
origin in which get() is called. That is: credentials saved on https://admin.example.com/ and https://example.com/ MAY be offered to users when get() is called from https://www.example.com/, and vice versa.
- -
+
-
MUST NOT offer credentials to an origin in response to get() without user mediation if the credential’s origin is not an exact match for the calling origin.
That is, Credential objects for https://example.com would not be returned directly to https://www.example.com, but could be offered to the user via the chooser.
@@ -3142,14 +3171,14 @@ [CSP] which restricts the endpoints to which data can be sent. In particular, developers should ensure
that the following directives are set, explicitly or implicitly, in their pages' policies:
- -
+
-
script-src and object-src both restrict script execution on a page, making
it less likely that a cross-site scripting attack will succeed in the first place. If sites
are populating form elements, also form-action directives should be set.
- -
+
-
connect-src restricts the origins to which fetch() may submit data (which
mitigates the risk that credentials could be exfiltrated to evil.com.
- -
+
-
child-src restricts the nested browsing contexts which may be embedded in a page,
making it more difficult to inject a malicious postMessage() target. [WEBMESSAGING]
@@ -3221,7 +3250,7 @@ Add some thoughts here about when and how the API
should be used, especially with regard to mediation. <https://github.com/w3c/webappsec/issues/290>
Describe encoding restrictions of submitting credentials by fetch() with
- a FormData body.
+ a FormData body.
When performing feature detection for a given credential type, developers are encouraged to verify
that the relevant Credential specialization is present, rather than relying on the presence of navigator.credentals. The latter verifies the existence of the API itself, but does not ensure
that the specific kind of credential necessary for a given site is supported. For example, if a
@@ -3232,7 +3261,7 @@
credentials that serve specific authentication needs. Doing so is, hopefully,
straightforward:
- -
+
-
Define a new interface that inherits from Credential:
- -
+
-
Define appropriate [[Create]](options, sameOriginWithAncestors), [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors) methods on ExampleCredential's interface object. [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is appropriate for credentials that remain effective forever and
can therefore simply be copied out of the credential store, while [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is
appropriate for credentials that need to be re-generated from a credential source.
@@ -3254,27 +3283,27 @@ true iff the calling context is same-origin with its ancestors. The algorithm
returns a set of Credential objects that match the options provided. If no matching Credential objects are available, the returned set will be empty.
- -
+
-
Assert: options[example] exists.
- -
+
-
If options[example] is not truthy, return the empty set.
- -
+
-
For each credential in the credential store:
- -
+
-
...
-
-
+
-
Define the value of the ExampleCredential interface object's [[type]] slot:
The ExampleCredential interface object has an internal slot named [[type]] whose
value is the string "example".
- -
+
-
Define the value of the ExampleCredential interface object's [[discovery]] slot:
The ExampleCredential interface object has an internal slot named [[type]] whose
value is "credential store".
- -
+
-
Extend CredentialRequestOptions with the options the new credential type needs to respond
reasonably to get():
@@ -3288,7 +3317,7 @@
- -
+
-
Extend CredentialCreationOptions with the data the new credential type needs to create Credential objects in response to create():
@@ -3384,6 +3413,7 @@ collect local, in §2.5.2
- create(), in §2.3
+
- create a copy of any buffer sources' data, in §2.3.1
- Create a Credential, in §2.5.4
- Create a FederatedCredential from FederatedCredentialInit, in §4.2.4
- Create a PasswordCredential from an HTMLFormElement, in §3.3.4
@@ -3398,7 +3428,6 @@
Credential, in §2.2
- credential, in §2
-
- CredentialBodyType, in §3.2
- credential chooser, in §5.3
- CredentialCreationOptions, in §2.4
- CredentialData, in §2.3
@@ -3547,6 +3576,12 @@
6.2. Credential Leakage
+
-
+
+
+
+
+ do we need to explicitly free the bytes we just orphaned? ↵
This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in. ↵
@@ -4895,6 +4950,13 @@ 5.3. Credential Selection
+
+
+ To create a copy of any buffer sources' data referenced by a value |V| of
+ [=dictionary=] type, run the following steps given |V|:
+
+
+ 1. Let |dictionaries| be a list consisting of |V| and all of |V|'s
+ [=inherited dictionaries=], in order from least to most derived.
+
+ 2. For each dictionary |dictionary| in |dictionaries|, in order:
+
+ 1. For each dictionary member |member| declared on
+ |dictionary|, in lexicographical order:
+
+ 1. Let |key| be the [=identifier=] of |member|.
+
+ 2. If the dictionary member named |key| is [=present=] in |V|, then:
+
+ 1. Let |value| be the value of |member| on |V|.
+
+ 2. If |value|'s type is a [=buffer source type=] then
+ [=get a copy of the bytes held by the buffer source=] and
+ set |values|'s value to be a reference to the copy of the bytes.
+
+ issue: do we need to explicitly free the bytes we just orphaned?
+
+
+
+
### Mediation Requirements ### {#mediation-requirements}
When making a request via {{get(options)}}, developers can set a case-by-case requirement for
@@ -729,8 +757,10 @@ Request a `Credential`
5. Let |sameOriginWithAncestors| be `true` if |settings| is [=same-origin with its
ancestors=], and `false` otherwise.
+
+ 6. [=Create a copy of any buffer sources' data=] referenced by |options|.
- 6. Run the following steps [=in parallel=]:
+ 7. Run the following steps [=in parallel=]:
1. Let |credentials| be the result of collecting
`Credential`s from the credential store, given |options| and
@@ -775,7 +805,7 @@ Request a `Credential`
Otherwise, [=reject=] |p| with |result|.
- 7. Return |p|.
+ 8. Return |p|.
Collect `Credential`s from the credential store
@@ -868,9 +898,11 @@ Create a `Credential`
6. If |options|.{{CredentialCreationOptions/signal}}'s [=AbortSignal/aborted
flag=] is set, then return [=a promise rejected with=] an "{{AbortError}}" {{DOMException}}.
- 7. Let |p| be [=a new promise=].
+ 7. [=Create a copy of any buffer sources' data=] referenced by |options|.
+
+ 8. Let |p| be [=a new promise=].
- 8. Run the following steps [=in parallel=]:
+ 9. Run the following steps [=in parallel=]:
1. Let |r| be the result of executing |interfaces|[0]
{{Credential/[[Create]](options, sameOriginWithAncestors)}} internal method on |options|
@@ -880,7 +912,7 @@ Create a `Credential`
Otherwise, [=resolve=] |p| with |r|.
- 9. Return |p|.
+ 10. Return |p|.
Prevent Silent Access
Finally, changing passwords is less well-supported than it could be if the website explicitly informed the user agent that credentials had changed.
@@ -1715,7 +1715,7 @@
2. Core API
- From a developer’s perspective, a credential is an
+
From a developer’s perspective, a credential is an
object which allows a developer to make an authentication decision for a particular action. This
section defines a generic and extensible Credential interface which serves as a base class
for credentials defined in this and other documents, along with a set of APIs
@@ -1723,18 +1723,18 @@
2.
Various types of credentials are represented to JavaScript as an interface which inherits, either directly or indirectly, from the Credential interface. This
document defines two such interfaces, PasswordCredential and FederatedCredential.
- A credential is effective for a particular origin if it
+
A credential is effective for a particular origin if it
is accepted as authentication on that origin. Even if a credential is effective at a particular
point in time, the UA can’t assume that the same credential will be effective at any future time,
for a couple reasons:
- -
+
-
A password credential may stop being effective if the account holder changes their password.
- -
+
-
A credential made from a token received over SMS is likely to only be effective for a single
use.
- Single-use credentials are generated by a credential source, which could be
+
Single-use credentials are generated by a credential source, which could be
a private key, access to a federated account, the ability to receive SMS messages at a particular
phone number, or something else. Credential sources are not exposed to Javascript or explicitly
represented in this specification. To unify the model, we consider a password to be a credential
@@ -1746,80 +1746,80 @@
2. offering effective credential
sources to the user in the future.
2.1. Infrastructure
- User agents MUST internally provide a credential
+ User agents MUST internally provide a credential
store, which is a vendor-specific, opaque storage mechanism to record which credentials have been effective. It offers the following capabilities for credential access and
persistence:
- -
-
-
+
Store a credential for later retrieval.
This accepts a credential, and inserts it into the credential store.
- -
-
Retrieve a list of credentials. This
+
-
+
Retrieve a list of credentials. This
accepts an arbitrary filter, and returns a set of credentials that match the filter.
- -
-
Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store.
+ -
+
Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store.
- Additionally, the credential store should maintain a prevent silent access flag for origins (which is set to true unless otherwise specified).
- An origin requires user mediation if its flag is set to true.
+ Additionally, the credential store should maintain a prevent silent access flag for origins (which is set to true unless otherwise specified).
+ An origin requires user mediation if its flag is set to true.
Note: The importance of user mediation is discussed in more detail in §5 User Mediation.
Note: The credential store is an internal implementation detail of a user agent’s
implementation of the API specified in this document, and is not exposed to the web directly.
More capabilities may be specified by other documents in support of specific credential types.
This document depends on the Infra Standard for a number of foundational concepts used in its
algorithms and prose [INFRA].
- An environment settings object (settings) is same-origin with its
+ An environment settings object (settings) is same-origin with its
ancestors if the following algorithm returns true:
- -
+
-
If settings has no responsible browsing context,
return false.
- -
+
-
Let origin be settings’ origin.
- -
+
-
Let current be settings’ responsible browsing context.
- -
+
-
While current has a parent browsing context:
- -
+
-
Set current to current’s parent browsing context.
- -
+
-
If current’s active document's origin is not same origin with origin,
return false.
- -
+
-
Return true.
2.2. The Credential Interface
-[Exposed=Window, SecureContext]
-interface Credential {
- readonly attribute USVString id;
- readonly attribute DOMString type;
+[Exposed =Window , SecureContext ]
+interface Credential readonly attribute USVString id ;
+ readonly attribute DOMString type ;
};
- id, of type USVString, readonly
- -
+
id, of type USVString, readonly
+ -
The credential’s identifier. The requirements for the identifier are distinct for each type
of credential. It might represent a username for username/password tuples, for example.
- type, of type DOMString, readonly
- -
+
type, of type DOMString, readonly
+ -
This attribute’s getter returns the value of the object’s interface object's [[type]] slot, which specifies the kind of credential represented by this object.
- [[type]]
- -
+
[[type]]
+ -
The Credential interface object has an internal slot named [[type]], which
unsurprisingly contains a string representing the type of the credential. The slot’s value
is the empty string unless otherwise specified.
Note: The [[type]] slot’s value will be the same for all credentials implementing a
particular interface, which means that developers can rely on obj.type returning a string
that unambigiously represents the specific kind of Credential they’re dealing with.
- [[discovery]]
- -
+
[[discovery]]
+ -
The Credential interface object has an internal slot named [[discovery]],
representing the mechanism by which the user agent can collect credentials of
a given type. Its value is either
- "credential store" or
- "remote". The former value means that
+ "credential store" or
+ "remote". The former value means that
all available credential information is stored in the user agent’s credential store,
while the latter means that the user agent can discover credentials outside of those
explicitly represented in the credential store via interaction with some external device
@@ -1828,46 +1828,46 @@
Talk to Tobie/Dominic about the interface object bits, here and in §2.5.1 Request a Credential, etc. I’m not sure I’ve gotten the terminology right. interface prototype
object, maybe?
- Some Credential objects are origin bound: these contain an
- internal slot named [[origin]], which stores the origin for which the Credential may be effective.
+ Some Credential objects are origin bound: these contain an
+ internal slot named [[origin]], which stores the origin for which the Credential may be effective.
2.2.1. Credential Internal Methods
Each interface object created for interfaces which inherit from Credential defines several internal methods that allow retrieval and storage of Credential objects:
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
+ [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
set of Credential objects from the user agent’s credential store that match the options
provided. If no matching Credential objects are available, the returned set will be empty.
- -
+
-
Return an empty set.
- [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
+ [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
caller’s environment settings object is same-origin with its ancestors. It returns a Credential if one can be returned given the options provided, null if no credential is
available, or an error if discovery fails (for example, incorrect options could produce a TypeError). If this kind of Credential is only effective for a single use or a
limited time, this method is responsible for generating new credentials using a credential source.
- -
+
-
Return null.
- [[Store]](credential, sameOriginWithAncestors) is
+ [[Store]](credential, sameOriginWithAncestors) is
called with a Credential, and a boolean which is true iff the caller’s environment
settings object is same-origin with its ancestors. The algorithm returns once Credential is persisted to the credential store:
- -
+
-
Return undefined.
- [[Create]](options, sameOriginWithAncestors) is
+ [[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions, and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns
either a Credential, if one can be created, null if no credential was created, or an
error if creation fails due to exceptional situations (for example, incorrect options could
produce a TypeError):
- -
+
-
Return null.
@@ -1876,20 +1876,20 @@
2.2.2. CredentialUserData Mixin
Some Credential objects contain data which aims to give users a human-readable disambiguation
mechanism in the credential chooser by providing a friendly name and icon:
-[SecureContext]
-interface mixin CredentialUserData {
- readonly attribute USVString name;
- readonly attribute USVString iconURL;
+[SecureContext ]
+interface mixin CredentialUserData readonly attribute USVString name ;
+ readonly attribute USVString iconURL ;
};
- name, of type USVString, readonly
- -
+
name, of type USVString, readonly
+ -
A name associated with the credential, intended as a human-understandable public name for
display in a credential chooser.
- iconURL, of type USVString, readonly
- -
+
iconURL, of type USVString, readonly
+ -
A URL pointing to an image for the credential, intended for display in a credential chooser. This URL MUST be an a priori authenticated
URL.
@@ -1897,28 +1897,28 @@ 2.3. navigator.credentials
Developers retrieve Credentials and interact with the user agent’s credential store via
methods exposed on the CredentialsContainer interface, which hangs off the Navigator object as navigator.credentials.
-partial interface Navigator {
- [SecureContext, SameObject] readonly attribute CredentialsContainer credentials;
+partial interface Navigator {
+ [SecureContext , SameObject ] readonly attribute CredentialsContainer credentials ;
};
- The credentials attribute MUST return the CredentialsContainer associated with the context object.
+ The credentials attribute MUST return the CredentialsContainer associated with the context object.
Note: As discussed in §6.3 Insecure Sites, the credential management API is exposed only in Secure Contexts.
-[Exposed=Window, SecureContext]
-interface CredentialsContainer {
- Promise<Credential?> get(optional CredentialRequestOptions options);
- Promise<Credential> store(Credential credential);
- Promise<Credential?> create(optional CredentialCreationOptions options);
- Promise<void> preventSilentAccess();
+[Exposed =Window , SecureContext ]
+interface CredentialsContainer Promise <Credential ?> get (optional CredentialRequestOptions options );
+ Promise <Credential > store (Credential credential );
+ Promise <Credential ?> create (optional CredentialCreationOptions options );
+ Promise <void > preventSilentAccess ();
};
-dictionary CredentialData {
- required USVString id;
+dictionary CredentialData required USVString id
- get(options)
- -
+
get(options)
+ -
When get() is called, the user agent MUST return the result of
executing Request a Credential on options.
@@ -1932,14 +1932,14 @@ options
+ options
CredentialRequestOptions
✘
✔
The set of properties governing the scope of the request.
- store(credential)
- -
+
store(credential)
+ -
When store() is called, the user agent MUST return the result of
executing Store a Credential on credential.
@@ -1953,14 +1953,14 @@ credential
+ credential
Credential
✘
✘
The credential to be stored.
- create(options)
- -
+
create(options)
+ -
When create() is called, the user agent MUST return the result of
executing Create a Credential on options.
@@ -1974,14 +1974,14 @@ options
+ options
CredentialCreationOptions
✘
✔
The options used to create a Credential.
- preventSilentAccess()
- -
+
preventSilentAccess()
+ -
When preventSilentAccess() is called, the user agent MUST return
the result of executing Prevent Silent Access on the current settings
object.
@@ -2002,20 +2002,20 @@ Note: The CredentialRequestOptions dictionary is an extension point. If and when new types of
credentials are introduced that require options, their dictionary types will be added to the
dictionary so they can be passed into the request. See §7.2 Extension Points.
-dictionary CredentialRequestOptions {
- CredentialMediationRequirement mediation = "optional";
- AbortSignal signal;
+dictionary CredentialRequestOptions CredentialMediationRequirement mediation = "optional";
+ AbortSignal signal ;
};
- mediation, of type CredentialMediationRequirement, defaulting to "optional"
- -
+
mediation, of type CredentialMediationRequirement, defaulting to "optional"
+ -
This property specifies the mediation requirements for a given credential request. The
meaning of each enum value is described below in CredentialMediationRequirement.
Processing details are defined in §2.5.1 Request a Credential.
- signal, of type AbortSignal
- -
+
signal, of type AbortSignal
+ -
This property lets the developer abort an ongoing get() operation.
An aborted operation may complete normally (generally if the abort was received after the
operation finished) or reject with an "AbortError" DOMException."
@@ -2029,22 +2029,22 @@ mediation.
- The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
+ The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
- -
+
-
Let settings be the current settings object
- -
+
-
Let interface objects be the set of interface objects on settings’ global object.
- -
+
-
Let relevant interface objects be an empty set.
- -
+
-
For each object in interface objects:
- -
+
-
If object’s inherited interfaces do not contain Credential, continue.
- -
+
-
Let key be object’s [[type]] slot’s value.
- -
+
-
If options[key] exists, append object to relevant interface objects.
@@ -2053,17 +2053,17 @@
- A given CredentialRequestOptions options is matchable a priori if the following
+ A given CredentialRequestOptions options is matchable a priori if the following
steps return true:
- -
+
-
For each interface in options’ relevant credential interface objects:
- -
+
-
If interface’s [[discovery]] slot’s value is not
"credential store", return false.
- -
+
-
Return true.
Note: When executing get(options), we only return credentials without user mediation if
@@ -2072,20 +2072,47 @@
user mediation will be required in order
to guide the discovery process (by choosing a federated identity provider, BTLE device, etc).
+
+ To create a copy of any buffer sources' data referenced by a value V of dictionary type, run the following steps given V:
+
+ -
+
Let dictionaries be a list consisting of V and all of V’s inherited dictionaries, in order from least to most derived.
+ -
+
For each dictionary dictionary in dictionaries, in order:
+
+ -
+
For each dictionary member member declared on dictionary, in lexicographical order:
+
+ -
+
Let key be the identifier of member.
+ -
+
If the dictionary member named key is present in V, then:
+
+ -
+
Let value be the value of member on V.
+ -
+
If value’s type is a buffer source type then get a copy of the bytes held by the buffer source and
+set values’s value to be a reference to the copy of the bytes.
+
+
+
+
+
+
2.3.2. Mediation Requirements
When making a request via get(options), developers can set a case-by-case requirement for user mediation by choosing the appropriate CredentialMediationRequirement enum value.
Note: The §5 User Mediation section gives more detail on the concept in general, and its
implications on how the user agent deals with individual requests for a given origin).
-enum CredentialMediationRequirement {
- "silent",
- "optional",
- "required"
+enum CredentialMediationRequirement "silent" ,
+ "optional" ,
+ "required"
};
- silent
- -
+
silent
+ -
User mediation is suppressed for the given operation. If the operation can be performed
without user involvement, wonderful. If user involvement is necessary, then the operation
will return null rather than involving the user.
@@ -2093,8 +2120,8 @@ , where a developer may wish to silently obtain
credentials if a user should be automatically signed in, but to delay bothering the user
with a sign-in prompt until they actively choose to sign-in.
- optional
- -
+
optional
+ -
If credentials can be handed over for a given operation without user mediation, they will
be. If user mediation is required, then the user agent will
involve the user in the decision.
@@ -2102,8 +2129,8 @@ credential chooser if necessary.
- required
- -
+
required
+ -
The user agent will not hand over credentials without user mediation, even if the prevent silent access flag is unset for an origin.
Note: This requirement is intended to support reauthentication or user-switching scenarios. Further, the requirement is tied
to a specific operation, and does not affect the prevent silent access flag for the
@@ -2118,7 +2145,7 @@
§5.2 Requiring User Mediation)
are signed in, and users who haven’t opted-into such behavior won’t be bothered with a confusing credential chooser popping up without context:
window.addEventListener('load', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'silent'
});
@@ -2133,7 +2160,7 @@ opted-into signing in without user mediation, and the user agent can unambigiously choose a credential, great! If
not, a credential chooser will be presented.
document.querySelector('#sign-in').addEventListener('click', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'optional'
});
@@ -2154,7 +2181,7 @@
document.querySelector('#important-form').addEventListener('submit', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2173,7 +2200,7 @@ required" in order to ensure that that credentials aren’t
returned automatically in response to clicking on an "Add account" button:
document.querySelector('#switch-button').addEventListener('click', e => {
- var c = await navigatior.credentials.get({
+ var c = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2189,192 +2216,196 @@ Note: The CredentialCreationOptions dictionary is an extension point. If and when new types of
credentials are introduced, they will add to the dictionary so they can be passed into the
creation method. See §7.2 Extension Points, and the extensions introduced in this document: §3.2 The PasswordCredential Interface and §4.1 The FederatedCredential Interface.
-dictionary CredentialCreationOptions {
- AbortSignal signal;
+dictionary CredentialCreationOptions AbortSignal signal ;
};
- signal, of type AbortSignal
- -
+
signal, of type AbortSignal
+ -
This property lets the developer abort an ongoing create() operation. An aborted operation may complete normally (generally if the abort was received
after the operation finished) or reject with an "AbortError" DOMException."
2.5. Algorithms
2.5.1. Request a Credential
- The Request a Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
+
The Request a Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
unambigiously obtained, or with null if not.
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
If options.signal’s aborted flag is set, then return a promise rejected with an "AbortError" DOMException.
- -
+
-
Let p be a new promise.
- -
+
-
Let sameOriginWithAncestors be true if settings is same-origin with its
ancestors, and false otherwise.
- -
+
-
+
Create a copy of any buffer sources' data referenced by options.
+ -
Run the following steps in parallel:
- -
+
-
Let credentials be the result of collecting Credentials from the credential store, given options and sameOriginWithAncestors.
- -
+
-
-
-
+
-
If all of the following statements are true, resolve p with credentials[0] and
skip the remaining steps:
- -
+
-
credentials’ size is 1
- -
+
-
settings’ origin does not require user mediation
- -
+
-
options is matchable a priori.
- -
+
-
This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in.
- -
+
-
If options’ mediation is
"silent", resolve p with null, and skip
the remaining steps.
- -
+
-
Let choice be the result of asking the user to
choose a Credential, given options and credentials.
- -
+
-
If choice is null or a Credential, resolve p with choice and skip the
remaining steps.
- -
+
-
Assert: choice is an interface object.
- -
+
-
Let result be the result of executing choice’s [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), given options and sameOriginWithAncestors.
- -
+
-
If result is a Credential or null, resolve p with result.
Otherwise, reject p with result.
- -
+
-
Return p.
2.5.2. Collect Credentials from the credential store
Given a CredentialRequestOptions (options) and a boolean which is true iff the calling
- context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
+ context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
returning a set of Credential objects stored by the user agent locally that match options’
filter. If no such Credential objects are known, the returned set will be empty:
- -
+
-
Let possible matches be an empty set.
- -
+
-
For each interface in options’ relevant credential interface objects:
- -
+
-
Let r be the result of executing interface’s [[CollectFromCredentialStore]](options, sameOriginWithAncestors) internal
method on options and sameOriginWithAncestors.
- -
+
-
If r is an exception, return r.
- -
+
-
Assert: r is a list of interface objects.
- -
+
-
For each c in r:
- -
+
-
Append c to possible matches.
- -
+
-
Return possible matches.
2.5.3. Store a Credential
- The Store a Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
+ The Store a Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
Let sameOriginWithAncestors be true if the current settings object is same-origin
with its ancestors, and false otherwise.
- -
+
-
Let p be a new promise.
- -
+
-
Run the following steps in parallel:
- -
+
-
Let r be the result of executing credential’s interface object's [[Store]](credential, sameOriginWithAncestors) internal method on credential and sameOriginWithAncestors.
- -
+
-
If r is an exception, reject p with r.
Otherwise, resolve p with r.
- -
+
-
Return p.
2.5.4. Create a Credential
- The Create a Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
+
The Create a Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
using the options provided, or null if no Credential can be created. In exceptional
circumstances, the Promise may reject with an appropriate exception:
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
Let sameOriginWithAncestors be true if the current settings object is same-origin
with its ancestors, and false otherwise.
- -
+
-
Let interfaces be the set of options’ relevant credential interface objects.
- -
+
-
Return a promise rejected with NotSupportedError if any of the following statements
are true:
- -
+
-
settings does not have a responsible document.
- -
+
-
interfaces’ size is greater than 1.
Note: It may be reasonable at some point in the future to loosen this restriction, and
allow the user agent to help the user choose among one of many potential credential
types in order to support a "sign-up" use case. For the moment, though, we’re punting
on that by restricting the dictionary to a single entry.
- -
+
-
If options.signal’s aborted
flag is set, then return a promise rejected with an "AbortError" DOMException.
- -
+
-
+
Create a copy of any buffer sources' data referenced by options.
+ -
Let p be a new promise.
- -
+
-
Run the following steps in parallel:
- -
+
-
Let r be the result of executing interfaces[0] [[Create]](options, sameOriginWithAncestors) internal method on options and sameOriginWithAncestors.
- -
+
-
If r is an exception, reject p with r.
Otherwise, resolve p with r.
- -
+
-
Return p.
2.5.5. Prevent Silent Access
- The Prevent Silent Access algorithm accepts an environment settings
+ The Prevent Silent Access algorithm accepts an environment settings
object (settings), and returns a Promise which resolves once the prevent silent access flag is persisted to the credential store.
- -
+
-
Let origin be settings’ origin.
- -
+
-
Let p be a new promise
- -
+
-
Run the following seps in parallel:
- -
+
-
Set origin’s prevent silent access flag in the credential store.
- -
+
-
Resolve p with undefined.
- -
+
-
Retun p.
@@ -2386,8 +2417,8 @@ 3.
from within a credential chooser.
3.1. Examples
3.1.1. Password-based Sign-in
-
- MegaCorp, Inc. supports passwords, and can use navigator.credentials.get() to obtain
+
+ MegaCorp, Inc. supports passwords, and can use navigator.credentials.get() to obtain
username/password pairs from a user’s credential store:
navigator.credentials
.get({ 'password': true })
@@ -2429,12 +2460,12 @@ type == 'password') {
- document.getQuerySelector('input[name=username_field]').value =
- credential.id;
- document.getQuerySelector('input[name=password_field]').value =
- credential.password;
- document.getQuerySelector('#myform').submit();
+ if (credential.type === 'password') {
+ document.querySelector('input[name=username_field]').value =
+ credential.id;
+ document.querySelector('input[name=password_field]').value =
+ credential.password;
+ document.getElementById('myform').submit();
}
});
@@ -2538,51 +2569,49 @@
3.2. The PasswordCredential Interface
-typedef (FormData or URLSearchParams) CredentialBodyType;
-
-[Constructor(HTMLFormElement form),
- Constructor(PasswordCredentialData data),
- Exposed=Window,
- SecureContext]
-interface PasswordCredential : Credential {
- readonly attribute USVString password;
+[Constructor (HTMLFormElement form Constructor (PasswordCredentialData data Exposed =Window ,
+ SecureContext ]
+interface PasswordCredential Credential {
+ readonly attribute USVString password ;
};
-PasswordCredential includes CredentialUserData;
+PasswordCredential includes CredentialUserData ;
-partial dictionary CredentialRequestOptions {
- boolean password = false;
+partial dictionary CredentialRequestOptions {
+ boolean password false ;
};
- password, of type USVString, readonly
- -
+
password, of type USVString, readonly
+ -
This attribute represents the password of the credential.
- [[type]]
- -
+
[[type]]
+ -
The PasswordCredential interface object has an internal slot named [[type]] whose
- value is "password".
- [[discovery]]
- -
+ value is "
password".
+ [[discovery]]
+ -
The PasswordCredential interface object has an internal slot named [[discovery]] whose value is "credential store".
- PasswordCredential(form)
- -
+
PasswordCredential(form)
+ -
This constructor accepts an HTMLFormElement (form), and runs the following steps:
- -
+
-
Let r be the result of executing Create a PasswordCredential from
an HTMLFormElement on form.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
- PasswordCredential(data)
- -
+
PasswordCredential(data)
+ -
This constructor accepts a PasswordCredentialData (data), and runs the following steps:
- -
+
-
Let r be the result of executing Create a PasswordCredential from PasswordCredentialData on data.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
@@ -2590,16 +2619,16 @@ <
PasswordCredential objects can be created via navigator.credentials.create() either explicitly by passing in a PasswordCredentialData dictionary, or based on the contents
of an HTMLFormElement's submittable elements.
-dictionary PasswordCredentialData : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString password;
+dictionary PasswordCredentialData CredentialData {
+ USVString name USVString iconURL required USVString password PasswordCredentialInit;
+typedef (PasswordCredentialData or HTMLFormElement ) PasswordCredentialInit password;
+partial dictionary CredentialCreationOptions {
+ PasswordCredentialInit password
PasswordCredential objects are origin bound.
@@ -2607,153 +2636,153 @@ <
own implementation of [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[Create]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors).
3.3. Algorithms
3.3.1. PasswordCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors)
-
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
+
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a set of Credential objects from the credential store. If no matching Credential objects are available, or sameOriginWithAncestors is false, the returned set
will be empty.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
-
-
+
-
If |sameOriginWithAncestors is false, return a "NotAllowedError" DOMException.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
Return the empty set if options["password"] is not true.
- -
+
-
Return the result of retrieving credentials from the credential store that match the following filter:
- -
+
-
The credential is a PasswordCredential
- -
+
-
The credential’s [[origin]] is the same origin as the current settings object's origin.
3.3.2. PasswordCredential's [[Create]](options, sameOriginWithAncestors)
- [[Create]](options, sameOriginWithAncestors) is called
+
[[Create]](options, sameOriginWithAncestors) is called
with a CredentialCreationOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns a PasswordCredential if one can be created, and null otherwise. The CredentialCreationOptions dictionary must have a password member which holds either an HTMLFormElement or a PasswordCredentialData. If that member’s value cannot be
used to create a PasswordCredential, this algorithm will return a TypeError exception.
- -
+
-
Assert: options["password"] exists, and sameOriginWithAncestors is unused.
- -
+
-
If options["password"] is an HTMLFormElement, return the
result of executing Create a PasswordCredential from an HTMLFormElement on options["password"].
- -
+
-
If options["password"] is a PasswordCredentialData, return
the result of executing Create a PasswordCredential from PasswordCredentialData on options["password"].
- -
+
-
3.3.3. PasswordCredential's [[Store]](credential, sameOriginWithAncestors)
- [[Store]](credential, sameOriginWithAncestors) is
+
[[Store]](credential, sameOriginWithAncestors) is
called with a PasswordCredential (credential), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns undefined once credential is persisted to the credential store.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
Return a "NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
If the user agent’s credential store contains a PasswordCredential (stored)
whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]],
then:
- -
+
-
If the user grants permission to update credentials (as discussed when defining user mediation), then:
Otherwise, if the user grants permission to store credentials (as discussed when
defining user mediation, then:
- -
+
-
Store a PasswordCredential in the credential store with the following
properties:
- id
- -
+
id
+ -
credential’s id
- name,
- -
+
name,
+ -
credential’s name
- iconURL
- -
+
iconURL
+ -
credential’s iconURL
- [[origin]]
- -
+
[[origin]]
+ -
credential’s [[origin]]
- password
- -
+
password
+ -
credential’s password
- -
+
-
Return undefined.
3.3.4. Create a PasswordCredential from an HTMLFormElement
- To Create a PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
+ To Create a PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
Note: §3.1.2 Post-sign-in Confirmation and §3.1.3 Change Password provide examples of the intended
usage.
- -
+
-
Let data be a new PasswordCredentialData dictionary.
- -
-
Let formData be the result of executing the FormData constructor
+
-
+
Let formData be the result of executing the FormData constructor
on form.
- -
+
-
Let elements be a list of all the submittable elements whose form owner is form, in tree order.
- -
+
-
Let newPasswordObserved be false.
- -
+
-
For each field in elements, run the following steps:
- -
+
-
If field does not have an autocomplete attribute, then skip to the next field.
- -
+
-
Let name be the value of field’s name attribute.
- -
+
-
If formData’s has() method returns false when executed on name, then
skip to the next field.
- -
+
-
If field’s autocomplete attribute’s value contains one or more autofill
detail tokens (tokens), then:
- -
+
-
For each token in tokens:
- -
+
-
If token is an ASCII case-insensitive match for one
of the following strings, run the associated steps:
- - "
new-password"
- -
+
- "
new-password"
+ -
Set data’s password member’s
value to the result of executing formData’s get() method on name, and newPasswordObserved to true.
- - "
current-password"
- -
+
- "
current-password"
+ -
If newPasswordObserved is false,
set data’s password member’s
value to the result of executing formData’s get() method on name.
Note: By checking that newPasswordObserved is false, new-password fields take precedence over current-password fields.
- - "
photo"
- -
+
- "
photo"
+ -
Set data’s iconURL member’s
value to the result of executing formData’s get() method on name.
- - "
name"
- - "
nickname"
- -
+
- "
name"
+ - "
nickname"
+ -
Set data’s name member’s
value to the result of executing formData’s get() method on name.
- - "
username"
- -
+
- "
username"
+ -
Set data’s id member’s value to the
result of executing formData’s get() method
on name.
@@ -2761,106 +2790,106 @@
+
-
Let c be the result of executing Create a PasswordCredential from PasswordCredentialData on data.
- -
+
-
If c is an exception, return c.
- -
+
-
Assert: c is a PasswordCredential.
- -
+
-
Return c.
3.3.5. Create a PasswordCredential from PasswordCredentialData
- To Create a PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
+ To Create a PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
- -
+
-
Let c be a new PasswordCredential object.
- -
+
-
If any of the following are the empty string, return a TypeError exception:
- -
+
-
Set c’s properties as follows:
- -
+
-
Return c.
3.3.6. CredentialRequestOptions Matching for PasswordCredential
Given a CredentialRequestOptions (options), the following algorithm returns "Matches" if
the PasswordCredential should be available as a response to a get() request, and "Does Not Match" otherwise.
- -
+
-
If options has a password member whose value is true, then
return "Matches".
- -
+
-
Return "Does Not Match".
4. Federated Credentials
4.1. The FederatedCredential Interface
-[Constructor(FederatedCredentialInit data),
- Exposed=Window,
- SecureContext]
-interface FederatedCredential : Credential {
- readonly attribute USVString provider;
- readonly attribute DOMString? protocol;
+[Constructor (FederatedCredentialInit data Exposed =Window ,
+ SecureContext ]
+interface FederatedCredential Credential {
+ readonly attribute USVString provider ;
+ readonly attribute DOMString ? protocol ;
};
-FederatedCredential includes CredentialUserData;
+FederatedCredential includes CredentialUserData ;
-dictionary FederatedCredentialRequestOptions {
- sequence<USVString> providers;
- sequence<DOMString> protocols;
+dictionary FederatedCredentialRequestOptions sequence <USVString > providers sequence <DOMString > protocols federated;
+partial dictionary CredentialRequestOptions {
+ FederatedCredentialRequestOptions federated
- provider, of type USVString, readonly
- -
+
provider, of type USVString, readonly
+ -
The credential’s federated identity provider. See §4.1.1 Identifying Providers for
details regarding valid formats.
- protocol, of type DOMString, readonly, nullable
- -
+
protocol, of type DOMString, readonly, nullable
+ -
The credential’s federated identity provider’s protocol (e.g. "openidconnect"). If the
value is null, then the protocol can be inferred from the provider.
- [[type]]
- -
+
[[type]]
+ -
The FederatedCredential interface object has an internal slot named [[type]] whose
- value is "federated".
- [[discovery]]
- -
+ value is "
federated".
+ [[discovery]]
+ -
The FederatedCredential interface object has an internal slot named [[discovery]] whose value is "credential store".
- FederatedCredential(data)
- -
+
FederatedCredential(data)
+ -
This constructor accepts a FederatedCredentialInit (data), and runs the following steps:
- -
+
-
Let r be the result of executing Create a FederatedCredential from FederatedCredentialInit on data.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
@@ -2868,15 +2897,15 @@
FederatedCredential objects can be created by passing a FederatedCredentialInit dictionary
into navigator.credentials.create().
-dictionary FederatedCredentialInit : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString provider;
- DOMString protocol;
+dictionary FederatedCredentialInit CredentialData {
+ USVString name USVString iconURL required USVString provider DOMString protocol federated;
+partial dictionary CredentialCreationOptions {
+ FederatedCredentialInit federated
FederatedCredential objects are origin bound.
@@ -2896,116 +2925,116 @@ https://accounts.google.com.
4.2. Algorithms
4.2.1. FederatedCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors)
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
+
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
with a CredentialRequestOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns
a set of Credential objects from the credential store. If no matching Credential objects are available, the returned set will be empty.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
-
-
+
-
If |sameOriginWithAncestors is false, return a "NotAllowedError" DOMException.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
Return the empty set if options["federated"] is not true.
- -
+
-
Return the result of retrieving credentials from the credential store that match the following filter:
- -
+
-
The credential is a FederatedCredential
- -
+
-
The credential’s [[origin]] is the same origin as the current settings object's origin.
- -
+
-
If options["federated"]["providers"] exists, its value contains the credentials’s provider.
- -
+
-
If options["federated"]["protocols"] exists, its value contains the credentials’s protocol.
4.2.2. FederatedCredential's [[Create]](options, sameOriginWithAncestors)
- [[Create]](options, sameOriginWithAncestors) is
+
[[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a FederatedCredential if one can be created, null otherwise, or an exception in
exceptional circumstances:
- -
+
-
Assert: options["federated"] exists, and sameOriginWithAncestors is unused.
- -
+
-
Return the result of executing Create a FederatedCredential from FederatedCredentialInit on options["federated"].
4.2.3. FederatedCredential's [[Store]](credential, sameOriginWithAncestors)
- [[Store]](credential, sameOriginWithAncestors) is
+
[[Store]](credential, sameOriginWithAncestors) is
called with a FederatedCredential (credential), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns undefined once credential is persisted to the credential store.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
Return a "NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
If the user agent’s credential store contains a FederatedCredential whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]], and
whose provider is credential’s provider, then return.
- -
+
-
If the user grants permission to store credentials (as discussed when defining user mediation), then store a FederatedCredential in the credential store with
the following properties:
- -
+
-
Return undefined.
4.2.4. Create a FederatedCredential from FederatedCredentialInit
- To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
+ To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
- -
+
-
Let c be a new FederatedCredential object.
- -
+
-
If any of the following are the empty string, return a TypeError exception:
- -
+
-
Set c’s properties as follows:
- -
+
-
Return c.
@@ -3014,7 +3043,7 @@ user mediated if
+ We call a particular action user mediated if
it takes place after gaining a user’s explicit consent. Consent might be expressed through a
user’s direct interaction with a credential chooser interface, for example. In general, user
mediated actions will involve presenting the user some sort of UI, and asking them to make a
@@ -3031,7 +3060,7 @@
- -
+
-
Credential information SHOULD NOT be stored or updated without user mediation. For
example, the user agent could display a "Save this credential?" dialog box to the user in
response to each call to store().
@@ -3039,10 +3068,10 @@
- -
+
-
User agents SHOULD notify users when credentials are stored. This might take the form of an
icon in the address bar, or some similar location.
- -
+
-
User agents MUST allow users to manually remove stored credentials. This functionality might
be implemented as a settings page, or via interaction with a notification as described above.
@@ -3056,25 +3085,25 @@
To mitigate the risk of surprise:
- -
+
-
User agents MUST allow users to require user mediation for a given origin or for all
origins. This functionality might be implemented as a global toggle that overrides each
origin’s prevent silent access flag to return false, or via more granular
settings for specific origins (or specific credentials on specific origins).
- -
+
-
User agents MUST NOT set an origin's prevent silent access flag to false without user mediation. For example, the credential chooser described in §5.3 Credential Selection could have a checkbox which the user could toggle to mark a
credential as available without mediation for the origin, or the user agent could have an
onboarding process for its credential manager which asked a user for a default setting.
- -
+
-
User agents MUST notify users when credentials are provided to an origin. This could take the
form of an icon in the address bar, or some similar location.
- -
+
-
If a user clears her browsing data for an origin (cookies, localStorage, and so on), the user
agent MUST set the prevent silent access flag to true for that origin.
5.3. Credential Selection
When responding to a call to get() on an origin which requires user mediation, user agents MUST ask the user for permission to share credential information.
- This SHOULD take the form of a credential chooser which presents the user with a
+ This SHOULD take the form of a credential chooser which presents the user with a
list of credentials that are available for use on a site, allowing them to select one which should
be provided to the website, or to reject the request entirely.
The chooser interface SHOULD be implemented in such a way as to be distinguishable from UI which a
@@ -3092,7 +3121,7 @@
- The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
+ The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
This algorithm returns either null if the user chose not to share a credential with the site,
a Credential object if the user chose a specific credential, or a Credential interface
object if the user chose a type of credential.
@@ -3123,16 +3152,16 @@ example.com vs admin.example.com.
As a compromise between annoying users, and securing their credentials, user agents:
- -
+
-
MUST NOT share credentials between origins whose scheme components represent a downgrade in
security. That is, it may make sense to allow credentials saved on http://example.com/ to
be made available to https://example.com/ (in order to encourage developers to migrate to
secure transport), but the inverse would be dangerous.
- -
+
-
MAY use the Public Suffix List [PSL] to determine the effective scope of a credential by
comparing the registerable domain of the credential’s [[origin]] with the
origin in which get() is called. That is: credentials saved on https://admin.example.com/ and https://example.com/ MAY be offered to users when get() is called from https://www.example.com/, and vice versa.
- -
+
-
MUST NOT offer credentials to an origin in response to get() without user mediation if the credential’s origin is not an exact match for the calling origin.
That is, Credential objects for https://example.com would not be returned directly to https://www.example.com, but could be offered to the user via the chooser.
@@ -3142,14 +3171,14 @@ [CSP] which restricts the endpoints to which data can be sent. In particular, developers should ensure
that the following directives are set, explicitly or implicitly, in their pages' policies:
- -
+
-
script-src and object-src both restrict script execution on a page, making
it less likely that a cross-site scripting attack will succeed in the first place. If sites
are populating form elements, also form-action directives should be set.
- -
+
-
connect-src restricts the origins to which fetch() may submit data (which
mitigates the risk that credentials could be exfiltrated to evil.com.
- -
+
-
child-src restricts the nested browsing contexts which may be embedded in a page,
making it more difficult to inject a malicious postMessage() target. [WEBMESSAGING]
@@ -3221,7 +3250,7 @@ Add some thoughts here about when and how the API
should be used, especially with regard to mediation. <https://github.com/w3c/webappsec/issues/290>
Describe encoding restrictions of submitting credentials by fetch() with
- a FormData body.
+ a FormData body.
When performing feature detection for a given credential type, developers are encouraged to verify
that the relevant Credential specialization is present, rather than relying on the presence of navigator.credentals. The latter verifies the existence of the API itself, but does not ensure
that the specific kind of credential necessary for a given site is supported. For example, if a
@@ -3232,7 +3261,7 @@
credentials that serve specific authentication needs. Doing so is, hopefully,
straightforward:
- -
+
-
Define a new interface that inherits from Credential:
- -
+
-
Define appropriate [[Create]](options, sameOriginWithAncestors), [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors) methods on ExampleCredential's interface object. [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is appropriate for credentials that remain effective forever and
can therefore simply be copied out of the credential store, while [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is
appropriate for credentials that need to be re-generated from a credential source.
@@ -3254,27 +3283,27 @@ true iff the calling context is same-origin with its ancestors. The algorithm
returns a set of Credential objects that match the options provided. If no matching Credential objects are available, the returned set will be empty.
- -
+
-
Assert: options[example] exists.
- -
+
-
If options[example] is not truthy, return the empty set.
- -
+
-
For each credential in the credential store:
- -
+
-
...
-
-
+
-
Define the value of the ExampleCredential interface object's [[type]] slot:
The ExampleCredential interface object has an internal slot named [[type]] whose
value is the string "example".
- -
+
-
Define the value of the ExampleCredential interface object's [[discovery]] slot:
The ExampleCredential interface object has an internal slot named [[type]] whose
value is "credential store".
- -
+
-
Extend CredentialRequestOptions with the options the new credential type needs to respond
reasonably to get():
@@ -3288,7 +3317,7 @@
- -
+
-
Extend CredentialCreationOptions with the data the new credential type needs to create Credential objects in response to create():
@@ -3384,6 +3413,7 @@ collect local, in §2.5.2
- create(), in §2.3
+
- create a copy of any buffer sources' data, in §2.3.1
- Create a Credential, in §2.5.4
- Create a FederatedCredential from FederatedCredentialInit, in §4.2.4
- Create a PasswordCredential from an HTMLFormElement, in §3.3.4
@@ -3398,7 +3428,6 @@
Credential, in §2.2
- credential, in §2
-
- CredentialBodyType, in §3.2
- credential chooser, in §5.3
- CredentialCreationOptions, in §2.4
- CredentialData, in §2.3
@@ -3547,6 +3576,12 @@
6.2. Credential Leakage
+
-
+
+
+
+
+ do we need to explicitly free the bytes we just orphaned? ↵
This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in. ↵
@@ -4895,6 +4950,13 @@ 5.3. Credential Selection
+
+
+ To create a copy of any buffer sources' data referenced by a value |V| of
+ [=dictionary=] type, run the following steps given |V|:
+
+
+ 1. Let |dictionaries| be a list consisting of |V| and all of |V|'s
+ [=inherited dictionaries=], in order from least to most derived.
+
+ 2. For each dictionary |dictionary| in |dictionaries|, in order:
+
+ 1. For each dictionary member |member| declared on
+ |dictionary|, in lexicographical order:
+
+ 1. Let |key| be the [=identifier=] of |member|.
+
+ 2. If the dictionary member named |key| is [=present=] in |V|, then:
+
+ 1. Let |value| be the value of |member| on |V|.
+
+ 2. If |value|'s type is a [=buffer source type=] then
+ [=get a copy of the bytes held by the buffer source=] and
+ set |values|'s value to be a reference to the copy of the bytes.
+
+ issue: do we need to explicitly free the bytes we just orphaned?
+
+
+
+
### Mediation Requirements ### {#mediation-requirements}
When making a request via {{get(options)}}, developers can set a case-by-case requirement for
@@ -729,8 +757,10 @@ Request a `Credential`
5. Let |sameOriginWithAncestors| be `true` if |settings| is [=same-origin with its
ancestors=], and `false` otherwise.
+
+ 6. [=Create a copy of any buffer sources' data=] referenced by |options|.
- 6. Run the following steps [=in parallel=]:
+ 7. Run the following steps [=in parallel=]:
1. Let |credentials| be the result of collecting
`Credential`s from the credential store, given |options| and
@@ -775,7 +805,7 @@ Request a `Credential`
Otherwise, [=reject=] |p| with |result|.
- 7. Return |p|.
+ 8. Return |p|.
Collect `Credential`s from the credential store
@@ -868,9 +898,11 @@ Create a `Credential`
6. If |options|.{{CredentialCreationOptions/signal}}'s [=AbortSignal/aborted
flag=] is set, then return [=a promise rejected with=] an "{{AbortError}}" {{DOMException}}.
- 7. Let |p| be [=a new promise=].
+ 7. [=Create a copy of any buffer sources' data=] referenced by |options|.
+
+ 8. Let |p| be [=a new promise=].
- 8. Run the following steps [=in parallel=]:
+ 9. Run the following steps [=in parallel=]:
1. Let |r| be the result of executing |interfaces|[0]
{{Credential/[[Create]](options, sameOriginWithAncestors)}} internal method on |options|
@@ -880,7 +912,7 @@ Create a `Credential`
Otherwise, [=resolve=] |p| with |r|.
- 9. Return |p|.
+ 10. Return |p|.
Prevent Silent Access
2. Core API
-From a developer’s perspective, a credential is an +
From a developer’s perspective, a credential is an
object which allows a developer to make an authentication decision for a particular action. This
section defines a generic and extensible Credential interface which serves as a base class
for credentials defined in this and other documents, along with a set of APIs
@@ -1723,18 +1723,18 @@
2.
Various types of credentials are represented to JavaScript as an interface which inherits, either directly or indirectly, from the Credential interface. This
document defines two such interfaces, PasswordCredential and FederatedCredential.
- A credential is effective for a particular origin if it
+
A credential is effective for a particular origin if it
is accepted as authentication on that origin. Even if a credential is effective at a particular
point in time, the UA can’t assume that the same credential will be effective at any future time,
for a couple reasons:
- -
+
-
A password credential may stop being effective if the account holder changes their password.
- -
+
-
A credential made from a token received over SMS is likely to only be effective for a single
use.
- Single-use credentials are generated by a credential source, which could be
+
Single-use credentials are generated by a credential source, which could be
a private key, access to a federated account, the ability to receive SMS messages at a particular
phone number, or something else. Credential sources are not exposed to Javascript or explicitly
represented in this specification. To unify the model, we consider a password to be a credential
@@ -1746,80 +1746,80 @@
2. offering effective credential
sources to the user in the future.
2.1. Infrastructure
- User agents MUST internally provide a credential
+ User agents MUST internally provide a credential
store, which is a vendor-specific, opaque storage mechanism to record which credentials have been effective. It offers the following capabilities for credential access and
persistence:
- -
-
-
+
Store a credential for later retrieval.
This accepts a credential, and inserts it into the credential store.
- -
-
Retrieve a list of credentials. This
+
-
+
Retrieve a list of credentials. This
accepts an arbitrary filter, and returns a set of credentials that match the filter.
- -
-
Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store.
+ -
+
Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store.
- Additionally, the credential store should maintain a prevent silent access flag for origins (which is set to true unless otherwise specified).
- An origin requires user mediation if its flag is set to true.
+ Additionally, the credential store should maintain a prevent silent access flag for origins (which is set to true unless otherwise specified).
+ An origin requires user mediation if its flag is set to true.
Note: The importance of user mediation is discussed in more detail in §5 User Mediation.
Note: The credential store is an internal implementation detail of a user agent’s
implementation of the API specified in this document, and is not exposed to the web directly.
More capabilities may be specified by other documents in support of specific credential types.
This document depends on the Infra Standard for a number of foundational concepts used in its
algorithms and prose [INFRA].
- An environment settings object (settings) is same-origin with its
+ An environment settings object (settings) is same-origin with its
ancestors if the following algorithm returns true:
- -
+
-
If settings has no responsible browsing context,
return false.
- -
+
-
Let origin be settings’ origin.
- -
+
-
Let current be settings’ responsible browsing context.
- -
+
-
While current has a parent browsing context:
- -
+
-
Set current to current’s parent browsing context.
- -
+
-
If current’s active document's origin is not same origin with origin,
return false.
- -
+
-
Return true.
2.2. The Credential Interface
-[Exposed=Window, SecureContext]
-interface Credential {
- readonly attribute USVString id;
- readonly attribute DOMString type;
+[Exposed =Window , SecureContext ]
+interface Credential readonly attribute USVString id ;
+ readonly attribute DOMString type ;
};
- id, of type USVString, readonly
- -
+
id, of type USVString, readonly
+ -
The credential’s identifier. The requirements for the identifier are distinct for each type
of credential. It might represent a username for username/password tuples, for example.
- type, of type DOMString, readonly
- -
+
type, of type DOMString, readonly
+ -
This attribute’s getter returns the value of the object’s interface object's [[type]] slot, which specifies the kind of credential represented by this object.
- [[type]]
- -
+
[[type]]
+ -
The Credential interface object has an internal slot named [[type]], which
unsurprisingly contains a string representing the type of the credential. The slot’s value
is the empty string unless otherwise specified.
Note: The [[type]] slot’s value will be the same for all credentials implementing a
particular interface, which means that developers can rely on obj.type returning a string
that unambigiously represents the specific kind of Credential they’re dealing with.
- [[discovery]]
- -
+
[[discovery]]
+ -
The Credential interface object has an internal slot named [[discovery]],
representing the mechanism by which the user agent can collect credentials of
a given type. Its value is either
- "credential store" or
- "remote". The former value means that
+ "credential store" or
+ "remote". The former value means that
all available credential information is stored in the user agent’s credential store,
while the latter means that the user agent can discover credentials outside of those
explicitly represented in the credential store via interaction with some external device
@@ -1828,46 +1828,46 @@
Talk to Tobie/Dominic about the interface object bits, here and in §2.5.1 Request a Credential, etc. I’m not sure I’ve gotten the terminology right. interface prototype
object, maybe?
- Some Credential objects are origin bound: these contain an
- internal slot named [[origin]], which stores the origin for which the Credential may be effective.
+ Some Credential objects are origin bound: these contain an
+ internal slot named [[origin]], which stores the origin for which the Credential may be effective.
2.2.1. Credential Internal Methods
Each interface object created for interfaces which inherit from Credential defines several internal methods that allow retrieval and storage of Credential objects:
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
+ [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
set of Credential objects from the user agent’s credential store that match the options
provided. If no matching Credential objects are available, the returned set will be empty.
- -
+
-
Return an empty set.
- [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
+ [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
caller’s environment settings object is same-origin with its ancestors. It returns a Credential if one can be returned given the options provided, null if no credential is
available, or an error if discovery fails (for example, incorrect options could produce a TypeError). If this kind of Credential is only effective for a single use or a
limited time, this method is responsible for generating new credentials using a credential source.
- -
+
-
Return null.
- [[Store]](credential, sameOriginWithAncestors) is
+ [[Store]](credential, sameOriginWithAncestors) is
called with a Credential, and a boolean which is true iff the caller’s environment
settings object is same-origin with its ancestors. The algorithm returns once Credential is persisted to the credential store:
- -
+
-
Return undefined.
- [[Create]](options, sameOriginWithAncestors) is
+ [[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions, and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns
either a Credential, if one can be created, null if no credential was created, or an
error if creation fails due to exceptional situations (for example, incorrect options could
produce a TypeError):
- -
+
-
Return null.
@@ -1876,20 +1876,20 @@
2.2.2. CredentialUserData Mixin
Some Credential objects contain data which aims to give users a human-readable disambiguation
mechanism in the credential chooser by providing a friendly name and icon:
-[SecureContext]
-interface mixin CredentialUserData {
- readonly attribute USVString name;
- readonly attribute USVString iconURL;
+[SecureContext ]
+interface mixin CredentialUserData readonly attribute USVString name ;
+ readonly attribute USVString iconURL ;
};
- name, of type USVString, readonly
- -
+
name, of type USVString, readonly
+ -
A name associated with the credential, intended as a human-understandable public name for
display in a credential chooser.
- iconURL, of type USVString, readonly
- -
+
iconURL, of type USVString, readonly
+ -
A URL pointing to an image for the credential, intended for display in a credential chooser. This URL MUST be an a priori authenticated
URL.
@@ -1897,28 +1897,28 @@ 2.3. navigator.credentials
Developers retrieve Credentials and interact with the user agent’s credential store via
methods exposed on the CredentialsContainer interface, which hangs off the Navigator object as navigator.credentials.
-partial interface Navigator {
- [SecureContext, SameObject] readonly attribute CredentialsContainer credentials;
+partial interface Navigator {
+ [SecureContext , SameObject ] readonly attribute CredentialsContainer credentials ;
};
- The credentials attribute MUST return the CredentialsContainer associated with the context object.
+ The credentials attribute MUST return the CredentialsContainer associated with the context object.
Note: As discussed in §6.3 Insecure Sites, the credential management API is exposed only in Secure Contexts.
-[Exposed=Window, SecureContext]
-interface CredentialsContainer {
- Promise<Credential?> get(optional CredentialRequestOptions options);
- Promise<Credential> store(Credential credential);
- Promise<Credential?> create(optional CredentialCreationOptions options);
- Promise<void> preventSilentAccess();
+[Exposed =Window , SecureContext ]
+interface CredentialsContainer Promise <Credential ?> get (optional CredentialRequestOptions options );
+ Promise <Credential > store (Credential credential );
+ Promise <Credential ?> create (optional CredentialCreationOptions options );
+ Promise <void > preventSilentAccess ();
};
-dictionary CredentialData {
- required USVString id;
+dictionary CredentialData required USVString id
- get(options)
- -
+
get(options)
+ -
When get() is called, the user agent MUST return the result of
executing Request a Credential on options.
@@ -1932,14 +1932,14 @@ options
+ options
CredentialRequestOptions
✘
✔
The set of properties governing the scope of the request.
- store(credential)
- -
+
store(credential)
+ -
When store() is called, the user agent MUST return the result of
executing Store a Credential on credential.
@@ -1953,14 +1953,14 @@ credential
+ credential
Credential
✘
✘
The credential to be stored.
- create(options)
- -
+
create(options)
+ -
When create() is called, the user agent MUST return the result of
executing Create a Credential on options.
@@ -1974,14 +1974,14 @@ options
+ options
CredentialCreationOptions
✘
✔
The options used to create a Credential.
- preventSilentAccess()
- -
+
preventSilentAccess()
+ -
When preventSilentAccess() is called, the user agent MUST return
the result of executing Prevent Silent Access on the current settings
object.
@@ -2002,20 +2002,20 @@ Note: The CredentialRequestOptions dictionary is an extension point. If and when new types of
credentials are introduced that require options, their dictionary types will be added to the
dictionary so they can be passed into the request. See §7.2 Extension Points.
-dictionary CredentialRequestOptions {
- CredentialMediationRequirement mediation = "optional";
- AbortSignal signal;
+dictionary CredentialRequestOptions CredentialMediationRequirement mediation = "optional";
+ AbortSignal signal ;
};
- mediation, of type CredentialMediationRequirement, defaulting to "optional"
- -
+
mediation, of type CredentialMediationRequirement, defaulting to "optional"
+ -
This property specifies the mediation requirements for a given credential request. The
meaning of each enum value is described below in CredentialMediationRequirement.
Processing details are defined in §2.5.1 Request a Credential.
- signal, of type AbortSignal
- -
+
signal, of type AbortSignal
+ -
This property lets the developer abort an ongoing get() operation.
An aborted operation may complete normally (generally if the abort was received after the
operation finished) or reject with an "AbortError" DOMException."
@@ -2029,22 +2029,22 @@ mediation.
- The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
+ The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
- -
+
-
Let settings be the current settings object
- -
+
-
Let interface objects be the set of interface objects on settings’ global object.
- -
+
-
Let relevant interface objects be an empty set.
- -
+
-
For each object in interface objects:
- -
+
-
If object’s inherited interfaces do not contain Credential, continue.
- -
+
-
Let key be object’s [[type]] slot’s value.
- -
+
-
If options[key] exists, append object to relevant interface objects.
@@ -2053,17 +2053,17 @@
- A given CredentialRequestOptions options is matchable a priori if the following
+ A given CredentialRequestOptions options is matchable a priori if the following
steps return true:
- -
+
-
For each interface in options’ relevant credential interface objects:
- -
+
-
If interface’s [[discovery]] slot’s value is not
"credential store", return false.
- -
+
-
Return true.
Note: When executing get(options), we only return credentials without user mediation if
@@ -2072,20 +2072,47 @@
user mediation will be required in order
to guide the discovery process (by choosing a federated identity provider, BTLE device, etc).
+
+ To create a copy of any buffer sources' data referenced by a value V of dictionary type, run the following steps given V:
+
+ -
+
Let dictionaries be a list consisting of V and all of V’s inherited dictionaries, in order from least to most derived.
+ -
+
For each dictionary dictionary in dictionaries, in order:
+
+ -
+
For each dictionary member member declared on dictionary, in lexicographical order:
+
+ -
+
Let key be the identifier of member.
+ -
+
If the dictionary member named key is present in V, then:
+
+ -
+
Let value be the value of member on V.
+ -
+
If value’s type is a buffer source type then get a copy of the bytes held by the buffer source and
+set values’s value to be a reference to the copy of the bytes.
+
+
+
+
+
+
2.3.2. Mediation Requirements
When making a request via get(options), developers can set a case-by-case requirement for user mediation by choosing the appropriate CredentialMediationRequirement enum value.
Note: The §5 User Mediation section gives more detail on the concept in general, and its
implications on how the user agent deals with individual requests for a given origin).
-enum CredentialMediationRequirement {
- "silent",
- "optional",
- "required"
+enum CredentialMediationRequirement "silent" ,
+ "optional" ,
+ "required"
};
- silent
- -
+
silent
+ -
User mediation is suppressed for the given operation. If the operation can be performed
without user involvement, wonderful. If user involvement is necessary, then the operation
will return null rather than involving the user.
@@ -2093,8 +2120,8 @@ , where a developer may wish to silently obtain
credentials if a user should be automatically signed in, but to delay bothering the user
with a sign-in prompt until they actively choose to sign-in.
- optional
- -
+
optional
+ -
If credentials can be handed over for a given operation without user mediation, they will
be. If user mediation is required, then the user agent will
involve the user in the decision.
@@ -2102,8 +2129,8 @@ credential chooser if necessary.
- required
- -
+
required
+ -
The user agent will not hand over credentials without user mediation, even if the prevent silent access flag is unset for an origin.
Note: This requirement is intended to support reauthentication or user-switching scenarios. Further, the requirement is tied
to a specific operation, and does not affect the prevent silent access flag for the
@@ -2118,7 +2145,7 @@
§5.2 Requiring User Mediation)
are signed in, and users who haven’t opted-into such behavior won’t be bothered with a confusing credential chooser popping up without context:
window.addEventListener('load', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'silent'
});
@@ -2133,7 +2160,7 @@ opted-into signing in without user mediation, and the user agent can unambigiously choose a credential, great! If
not, a credential chooser will be presented.
document.querySelector('#sign-in').addEventListener('click', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'optional'
});
@@ -2154,7 +2181,7 @@
document.querySelector('#important-form').addEventListener('submit', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2173,7 +2200,7 @@ required" in order to ensure that that credentials aren’t
returned automatically in response to clicking on an "Add account" button:
document.querySelector('#switch-button').addEventListener('click', e => {
- var c = await navigatior.credentials.get({
+ var c = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2189,192 +2216,196 @@ Note: The CredentialCreationOptions dictionary is an extension point. If and when new types of
credentials are introduced, they will add to the dictionary so they can be passed into the
creation method. See §7.2 Extension Points, and the extensions introduced in this document: §3.2 The PasswordCredential Interface and §4.1 The FederatedCredential Interface.
-dictionary CredentialCreationOptions {
- AbortSignal signal;
+dictionary CredentialCreationOptions AbortSignal signal ;
};
- signal, of type AbortSignal
- -
+
signal, of type AbortSignal
+ -
This property lets the developer abort an ongoing create() operation. An aborted operation may complete normally (generally if the abort was received
after the operation finished) or reject with an "AbortError" DOMException."
2.5. Algorithms
2.5.1. Request a Credential
- The Request a Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
+
The Request a Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
unambigiously obtained, or with null if not.
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
If options.signal’s aborted flag is set, then return a promise rejected with an "AbortError" DOMException.
- -
+
-
Let p be a new promise.
- -
+
-
Let sameOriginWithAncestors be true if settings is same-origin with its
ancestors, and false otherwise.
- -
+
-
+
Create a copy of any buffer sources' data referenced by options.
+ -
Run the following steps in parallel:
- -
+
-
Let credentials be the result of collecting Credentials from the credential store, given options and sameOriginWithAncestors.
- -
+
-
-
-
+
-
If all of the following statements are true, resolve p with credentials[0] and
skip the remaining steps:
- -
+
-
credentials’ size is 1
- -
+
-
settings’ origin does not require user mediation
- -
+
-
options is matchable a priori.
- -
+
-
This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in.
- -
+
-
If options’ mediation is
"silent", resolve p with null, and skip
the remaining steps.
- -
+
-
Let choice be the result of asking the user to
choose a Credential, given options and credentials.
- -
+
-
If choice is null or a Credential, resolve p with choice and skip the
remaining steps.
- -
+
-
Assert: choice is an interface object.
- -
+
-
Let result be the result of executing choice’s [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), given options and sameOriginWithAncestors.
- -
+
-
If result is a Credential or null, resolve p with result.
Otherwise, reject p with result.
- -
+
-
Return p.
2.5.2. Collect Credentials from the credential store
Given a CredentialRequestOptions (options) and a boolean which is true iff the calling
- context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
+ context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
returning a set of Credential objects stored by the user agent locally that match options’
filter. If no such Credential objects are known, the returned set will be empty:
- -
+
-
Let possible matches be an empty set.
- -
+
-
For each interface in options’ relevant credential interface objects:
- -
+
-
Let r be the result of executing interface’s [[CollectFromCredentialStore]](options, sameOriginWithAncestors) internal
method on options and sameOriginWithAncestors.
- -
+
-
If r is an exception, return r.
- -
+
-
Assert: r is a list of interface objects.
- -
+
-
For each c in r:
- -
+
-
Append c to possible matches.
- -
+
-
Return possible matches.
2.5.3. Store a Credential
- The Store a Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
+ The Store a Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
Let sameOriginWithAncestors be true if the current settings object is same-origin
with its ancestors, and false otherwise.
- -
+
-
Let p be a new promise.
- -
+
-
Run the following steps in parallel:
- -
+
-
Let r be the result of executing credential’s interface object's [[Store]](credential, sameOriginWithAncestors) internal method on credential and sameOriginWithAncestors.
- -
+
-
If r is an exception, reject p with r.
Otherwise, resolve p with r.
- -
+
-
Return p.
2.5.4. Create a Credential
- The Create a Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
+
The Create a Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
using the options provided, or null if no Credential can be created. In exceptional
circumstances, the Promise may reject with an appropriate exception:
- -
+
-
Let settings be the current settings object
- -
+
-
Assert: settings is a secure context.
- -
+
-
Let sameOriginWithAncestors be true if the current settings object is same-origin
with its ancestors, and false otherwise.
- -
+
-
Let interfaces be the set of options’ relevant credential interface objects.
- -
+
-
Return a promise rejected with NotSupportedError if any of the following statements
are true:
- -
+
-
settings does not have a responsible document.
- -
+
-
interfaces’ size is greater than 1.
Note: It may be reasonable at some point in the future to loosen this restriction, and
allow the user agent to help the user choose among one of many potential credential
types in order to support a "sign-up" use case. For the moment, though, we’re punting
on that by restricting the dictionary to a single entry.
- -
+
-
If options.signal’s aborted
flag is set, then return a promise rejected with an "AbortError" DOMException.
- -
+
-
+
Create a copy of any buffer sources' data referenced by options.
+ -
Let p be a new promise.
- -
+
-
Run the following steps in parallel:
- -
+
-
Let r be the result of executing interfaces[0] [[Create]](options, sameOriginWithAncestors) internal method on options and sameOriginWithAncestors.
- -
+
-
If r is an exception, reject p with r.
Otherwise, resolve p with r.
- -
+
-
Return p.
2.5.5. Prevent Silent Access
- The Prevent Silent Access algorithm accepts an environment settings
+ The Prevent Silent Access algorithm accepts an environment settings
object (settings), and returns a Promise which resolves once the prevent silent access flag is persisted to the credential store.
- -
+
-
Let origin be settings’ origin.
- -
+
-
Let p be a new promise
- -
+
-
Run the following seps in parallel:
- -
+
-
Set origin’s prevent silent access flag in the credential store.
- -
+
-
Resolve p with undefined.
- -
+
-
Retun p.
@@ -2386,8 +2417,8 @@ 3.
from within a credential chooser.
3.1. Examples
3.1.1. Password-based Sign-in
-
- MegaCorp, Inc. supports passwords, and can use navigator.credentials.get() to obtain
+
+ MegaCorp, Inc. supports passwords, and can use navigator.credentials.get() to obtain
username/password pairs from a user’s credential store:
navigator.credentials
.get({ 'password': true })
@@ -2429,12 +2460,12 @@ type == 'password') {
- document.getQuerySelector('input[name=username_field]').value =
- credential.id;
- document.getQuerySelector('input[name=password_field]').value =
- credential.password;
- document.getQuerySelector('#myform').submit();
+ if (credential.type === 'password') {
+ document.querySelector('input[name=username_field]').value =
+ credential.id;
+ document.querySelector('input[name=password_field]').value =
+ credential.password;
+ document.getElementById('myform').submit();
}
});
@@ -2538,51 +2569,49 @@
3.2. The PasswordCredential Interface
-typedef (FormData or URLSearchParams) CredentialBodyType;
-
-[Constructor(HTMLFormElement form),
- Constructor(PasswordCredentialData data),
- Exposed=Window,
- SecureContext]
-interface PasswordCredential : Credential {
- readonly attribute USVString password;
+[Constructor (HTMLFormElement form Constructor (PasswordCredentialData data Exposed =Window ,
+ SecureContext ]
+interface PasswordCredential Credential {
+ readonly attribute USVString password ;
};
-PasswordCredential includes CredentialUserData;
+PasswordCredential includes CredentialUserData ;
-partial dictionary CredentialRequestOptions {
- boolean password = false;
+partial dictionary CredentialRequestOptions {
+ boolean password false ;
};
- password, of type USVString, readonly
- -
+
password, of type USVString, readonly
+ -
This attribute represents the password of the credential.
- [[type]]
- -
+
[[type]]
+ -
The PasswordCredential interface object has an internal slot named [[type]] whose
- value is "password".
- [[discovery]]
- -
+ value is "
password".
+ [[discovery]]
+ -
The PasswordCredential interface object has an internal slot named [[discovery]] whose value is "credential store".
- PasswordCredential(form)
- -
+
PasswordCredential(form)
+ -
This constructor accepts an HTMLFormElement (form), and runs the following steps:
- -
+
-
Let r be the result of executing Create a PasswordCredential from
an HTMLFormElement on form.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
- PasswordCredential(data)
- -
+
PasswordCredential(data)
+ -
This constructor accepts a PasswordCredentialData (data), and runs the following steps:
- -
+
-
Let r be the result of executing Create a PasswordCredential from PasswordCredentialData on data.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
@@ -2590,16 +2619,16 @@ <
PasswordCredential objects can be created via navigator.credentials.create() either explicitly by passing in a PasswordCredentialData dictionary, or based on the contents
of an HTMLFormElement's submittable elements.
-dictionary PasswordCredentialData : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString password;
+dictionary PasswordCredentialData CredentialData {
+ USVString name USVString iconURL required USVString password PasswordCredentialInit;
+typedef (PasswordCredentialData or HTMLFormElement ) PasswordCredentialInit password;
+partial dictionary CredentialCreationOptions {
+ PasswordCredentialInit password
PasswordCredential objects are origin bound.
@@ -2607,153 +2636,153 @@ <
own implementation of [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[Create]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors).
3.3. Algorithms
3.3.1. PasswordCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors)
-
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
+
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a set of Credential objects from the credential store. If no matching Credential objects are available, or sameOriginWithAncestors is false, the returned set
will be empty.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
-
-
+
-
If |sameOriginWithAncestors is false, return a "NotAllowedError" DOMException.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
Return the empty set if options["password"] is not true.
- -
+
-
Return the result of retrieving credentials from the credential store that match the following filter:
- -
+
-
The credential is a PasswordCredential
- -
+
-
The credential’s [[origin]] is the same origin as the current settings object's origin.
3.3.2. PasswordCredential's [[Create]](options, sameOriginWithAncestors)
- [[Create]](options, sameOriginWithAncestors) is called
+
[[Create]](options, sameOriginWithAncestors) is called
with a CredentialCreationOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns a PasswordCredential if one can be created, and null otherwise. The CredentialCreationOptions dictionary must have a password member which holds either an HTMLFormElement or a PasswordCredentialData. If that member’s value cannot be
used to create a PasswordCredential, this algorithm will return a TypeError exception.
- -
+
-
Assert: options["password"] exists, and sameOriginWithAncestors is unused.
- -
+
-
If options["password"] is an HTMLFormElement, return the
result of executing Create a PasswordCredential from an HTMLFormElement on options["password"].
- -
+
-
If options["password"] is a PasswordCredentialData, return
the result of executing Create a PasswordCredential from PasswordCredentialData on options["password"].
- -
+
-
3.3.3. PasswordCredential's [[Store]](credential, sameOriginWithAncestors)
- [[Store]](credential, sameOriginWithAncestors) is
+
[[Store]](credential, sameOriginWithAncestors) is
called with a PasswordCredential (credential), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns undefined once credential is persisted to the credential store.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
Return a "NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
If the user agent’s credential store contains a PasswordCredential (stored)
whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]],
then:
- -
+
-
If the user grants permission to update credentials (as discussed when defining user mediation), then:
Otherwise, if the user grants permission to store credentials (as discussed when
defining user mediation, then:
- -
+
-
Store a PasswordCredential in the credential store with the following
properties:
- id
- -
+
id
+ -
credential’s id
- name,
- -
+
name,
+ -
credential’s name
- iconURL
- -
+
iconURL
+ -
credential’s iconURL
- [[origin]]
- -
+
[[origin]]
+ -
credential’s [[origin]]
- password
- -
+
password
+ -
credential’s password
- -
+
-
Return undefined.
3.3.4. Create a PasswordCredential from an HTMLFormElement
- To Create a PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
+ To Create a PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
Note: §3.1.2 Post-sign-in Confirmation and §3.1.3 Change Password provide examples of the intended
usage.
- -
+
-
Let data be a new PasswordCredentialData dictionary.
- -
-
Let formData be the result of executing the FormData constructor
+
-
+
Let formData be the result of executing the FormData constructor
on form.
- -
+
-
Let elements be a list of all the submittable elements whose form owner is form, in tree order.
- -
+
-
Let newPasswordObserved be false.
- -
+
-
For each field in elements, run the following steps:
- -
+
-
If field does not have an autocomplete attribute, then skip to the next field.
- -
+
-
Let name be the value of field’s name attribute.
- -
+
-
If formData’s has() method returns false when executed on name, then
skip to the next field.
- -
+
-
If field’s autocomplete attribute’s value contains one or more autofill
detail tokens (tokens), then:
- -
+
-
For each token in tokens:
- -
+
-
If token is an ASCII case-insensitive match for one
of the following strings, run the associated steps:
- - "
new-password"
- -
+
- "
new-password"
+ -
Set data’s password member’s
value to the result of executing formData’s get() method on name, and newPasswordObserved to true.
- - "
current-password"
- -
+
- "
current-password"
+ -
If newPasswordObserved is false,
set data’s password member’s
value to the result of executing formData’s get() method on name.
Note: By checking that newPasswordObserved is false, new-password fields take precedence over current-password fields.
- - "
photo"
- -
+
- "
photo"
+ -
Set data’s iconURL member’s
value to the result of executing formData’s get() method on name.
- - "
name"
- - "
nickname"
- -
+
- "
name"
+ - "
nickname"
+ -
Set data’s name member’s
value to the result of executing formData’s get() method on name.
- - "
username"
- -
+
- "
username"
+ -
Set data’s id member’s value to the
result of executing formData’s get() method
on name.
@@ -2761,106 +2790,106 @@
+
-
Let c be the result of executing Create a PasswordCredential from PasswordCredentialData on data.
- -
+
-
If c is an exception, return c.
- -
+
-
Assert: c is a PasswordCredential.
- -
+
-
Return c.
3.3.5. Create a PasswordCredential from PasswordCredentialData
- To Create a PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
+ To Create a PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
- -
+
-
Let c be a new PasswordCredential object.
- -
+
-
If any of the following are the empty string, return a TypeError exception:
- -
+
-
Set c’s properties as follows:
- -
+
-
Return c.
3.3.6. CredentialRequestOptions Matching for PasswordCredential
Given a CredentialRequestOptions (options), the following algorithm returns "Matches" if
the PasswordCredential should be available as a response to a get() request, and "Does Not Match" otherwise.
- -
+
-
If options has a password member whose value is true, then
return "Matches".
- -
+
-
Return "Does Not Match".
4. Federated Credentials
4.1. The FederatedCredential Interface
-[Constructor(FederatedCredentialInit data),
- Exposed=Window,
- SecureContext]
-interface FederatedCredential : Credential {
- readonly attribute USVString provider;
- readonly attribute DOMString? protocol;
+[Constructor (FederatedCredentialInit data Exposed =Window ,
+ SecureContext ]
+interface FederatedCredential Credential {
+ readonly attribute USVString provider ;
+ readonly attribute DOMString ? protocol ;
};
-FederatedCredential includes CredentialUserData;
+FederatedCredential includes CredentialUserData ;
-dictionary FederatedCredentialRequestOptions {
- sequence<USVString> providers;
- sequence<DOMString> protocols;
+dictionary FederatedCredentialRequestOptions sequence <USVString > providers sequence <DOMString > protocols federated;
+partial dictionary CredentialRequestOptions {
+ FederatedCredentialRequestOptions federated
- provider, of type USVString, readonly
- -
+
provider, of type USVString, readonly
+ -
The credential’s federated identity provider. See §4.1.1 Identifying Providers for
details regarding valid formats.
- protocol, of type DOMString, readonly, nullable
- -
+
protocol, of type DOMString, readonly, nullable
+ -
The credential’s federated identity provider’s protocol (e.g. "openidconnect"). If the
value is null, then the protocol can be inferred from the provider.
- [[type]]
- -
+
[[type]]
+ -
The FederatedCredential interface object has an internal slot named [[type]] whose
- value is "federated".
- [[discovery]]
- -
+ value is "
federated".
+ [[discovery]]
+ -
The FederatedCredential interface object has an internal slot named [[discovery]] whose value is "credential store".
- FederatedCredential(data)
- -
+
FederatedCredential(data)
+ -
This constructor accepts a FederatedCredentialInit (data), and runs the following steps:
- -
+
-
Let r be the result of executing Create a FederatedCredential from FederatedCredentialInit on data.
- -
+
-
If r is an exception, throw r.
Otherwise, return r.
@@ -2868,15 +2897,15 @@
FederatedCredential objects can be created by passing a FederatedCredentialInit dictionary
into navigator.credentials.create().
-dictionary FederatedCredentialInit : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString provider;
- DOMString protocol;
+dictionary FederatedCredentialInit CredentialData {
+ USVString name USVString iconURL required USVString provider DOMString protocol federated;
+partial dictionary CredentialCreationOptions {
+ FederatedCredentialInit federated
FederatedCredential objects are origin bound.
@@ -2896,116 +2925,116 @@ https://accounts.google.com.
4.2. Algorithms
4.2.1. FederatedCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors)
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
+
[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
with a CredentialRequestOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns
a set of Credential objects from the credential store. If no matching Credential objects are available, the returned set will be empty.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
-
-
+
-
If |sameOriginWithAncestors is false, return a "NotAllowedError" DOMException.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
Return the empty set if options["federated"] is not true.
- -
+
-
Return the result of retrieving credentials from the credential store that match the following filter:
- -
+
-
The credential is a FederatedCredential
- -
+
-
The credential’s [[origin]] is the same origin as the current settings object's origin.
- -
+
-
If options["federated"]["providers"] exists, its value contains the credentials’s provider.
- -
+
-
If options["federated"]["protocols"] exists, its value contains the credentials’s protocol.
4.2.2. FederatedCredential's [[Create]](options, sameOriginWithAncestors)
- [[Create]](options, sameOriginWithAncestors) is
+
[[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a FederatedCredential if one can be created, null otherwise, or an exception in
exceptional circumstances:
- -
+
-
Assert: options["federated"] exists, and sameOriginWithAncestors is unused.
- -
+
-
Return the result of executing Create a FederatedCredential from FederatedCredentialInit on options["federated"].
4.2.3. FederatedCredential's [[Store]](credential, sameOriginWithAncestors)
- [[Store]](credential, sameOriginWithAncestors) is
+
[[Store]](credential, sameOriginWithAncestors) is
called with a FederatedCredential (credential), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns undefined once credential is persisted to the credential store.
The algorithm will return a NotAllowedError if sameOriginWithAncestors is not true.
- -
+
-
Return a "NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.
Note: This restriction aims to address the concern raised in §6.4 Origin Confusion.
- -
+
-
If the user agent’s credential store contains a FederatedCredential whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]], and
whose provider is credential’s provider, then return.
- -
+
-
If the user grants permission to store credentials (as discussed when defining user mediation), then store a FederatedCredential in the credential store with
the following properties:
- -
+
-
Return undefined.
4.2.4. Create a FederatedCredential from FederatedCredentialInit
- To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
+ To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
- -
+
-
Let c be a new FederatedCredential object.
- -
+
-
If any of the following are the empty string, return a TypeError exception:
- -
+
-
Set c’s properties as follows:
- -
+
-
Return c.
@@ -3014,7 +3043,7 @@ user mediated if
+ We call a particular action user mediated if
it takes place after gaining a user’s explicit consent. Consent might be expressed through a
user’s direct interaction with a credential chooser interface, for example. In general, user
mediated actions will involve presenting the user some sort of UI, and asking them to make a
@@ -3031,7 +3060,7 @@
- -
+
-
Credential information SHOULD NOT be stored or updated without user mediation. For
example, the user agent could display a "Save this credential?" dialog box to the user in
response to each call to store().
@@ -3039,10 +3068,10 @@
- -
+
-
User agents SHOULD notify users when credentials are stored. This might take the form of an
icon in the address bar, or some similar location.
- -
+
-
User agents MUST allow users to manually remove stored credentials. This functionality might
be implemented as a settings page, or via interaction with a notification as described above.
@@ -3056,25 +3085,25 @@
To mitigate the risk of surprise:
- -
+
-
User agents MUST allow users to require user mediation for a given origin or for all
origins. This functionality might be implemented as a global toggle that overrides each
origin’s prevent silent access flag to return false, or via more granular
settings for specific origins (or specific credentials on specific origins).
- -
+
-
User agents MUST NOT set an origin's prevent silent access flag to false without user mediation. For example, the credential chooser described in §5.3 Credential Selection could have a checkbox which the user could toggle to mark a
credential as available without mediation for the origin, or the user agent could have an
onboarding process for its credential manager which asked a user for a default setting.
- -
+
-
User agents MUST notify users when credentials are provided to an origin. This could take the
form of an icon in the address bar, or some similar location.
- -
+
-
If a user clears her browsing data for an origin (cookies, localStorage, and so on), the user
agent MUST set the prevent silent access flag to true for that origin.
5.3. Credential Selection
When responding to a call to get() on an origin which requires user mediation, user agents MUST ask the user for permission to share credential information.
- This SHOULD take the form of a credential chooser which presents the user with a
+ This SHOULD take the form of a credential chooser which presents the user with a
list of credentials that are available for use on a site, allowing them to select one which should
be provided to the website, or to reject the request entirely.
The chooser interface SHOULD be implemented in such a way as to be distinguishable from UI which a
@@ -3092,7 +3121,7 @@
- The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
+ The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
This algorithm returns either null if the user chose not to share a credential with the site,
a Credential object if the user chose a specific credential, or a Credential interface
object if the user chose a type of credential.
@@ -3123,16 +3152,16 @@ example.com vs admin.example.com.
As a compromise between annoying users, and securing their credentials, user agents:
- -
+
-
MUST NOT share credentials between origins whose scheme components represent a downgrade in
security. That is, it may make sense to allow credentials saved on http://example.com/ to
be made available to https://example.com/ (in order to encourage developers to migrate to
secure transport), but the inverse would be dangerous.
- -
+
-
MAY use the Public Suffix List [PSL] to determine the effective scope of a credential by
comparing the registerable domain of the credential’s [[origin]] with the
origin in which get() is called. That is: credentials saved on https://admin.example.com/ and https://example.com/ MAY be offered to users when get() is called from https://www.example.com/, and vice versa.
- -
+
-
MUST NOT offer credentials to an origin in response to get() without user mediation if the credential’s origin is not an exact match for the calling origin.
That is, Credential objects for https://example.com would not be returned directly to https://www.example.com, but could be offered to the user via the chooser.
@@ -3142,14 +3171,14 @@ [CSP] which restricts the endpoints to which data can be sent. In particular, developers should ensure
that the following directives are set, explicitly or implicitly, in their pages' policies:
- -
+
-
script-src and object-src both restrict script execution on a page, making
it less likely that a cross-site scripting attack will succeed in the first place. If sites
are populating form elements, also form-action directives should be set.
- -
+
-
connect-src restricts the origins to which fetch() may submit data (which
mitigates the risk that credentials could be exfiltrated to evil.com.
- -
+
-
child-src restricts the nested browsing contexts which may be embedded in a page,
making it more difficult to inject a malicious postMessage() target. [WEBMESSAGING]
@@ -3221,7 +3250,7 @@ Add some thoughts here about when and how the API
should be used, especially with regard to mediation. <https://github.com/w3c/webappsec/issues/290>
Describe encoding restrictions of submitting credentials by fetch() with
- a FormData body.
+ a FormData body.
When performing feature detection for a given credential type, developers are encouraged to verify
that the relevant Credential specialization is present, rather than relying on the presence of navigator.credentals. The latter verifies the existence of the API itself, but does not ensure
that the specific kind of credential necessary for a given site is supported. For example, if a
@@ -3232,7 +3261,7 @@
credentials that serve specific authentication needs. Doing so is, hopefully,
straightforward:
- -
+
-
Define a new interface that inherits from Credential:
- -
+
-
Define appropriate [[Create]](options, sameOriginWithAncestors), [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors) methods on ExampleCredential's interface object. [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is appropriate for credentials that remain effective forever and
can therefore simply be copied out of the credential store, while [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is
appropriate for credentials that need to be re-generated from a credential source.
@@ -3254,27 +3283,27 @@ true iff the calling context is same-origin with its ancestors. The algorithm
returns a set of Credential objects that match the options provided. If no matching Credential objects are available, the returned set will be empty.
- -
+
-
Assert: options[example] exists.
- -
+
-
If options[example] is not truthy, return the empty set.
- -
+
-
For each credential in the credential store:
- -
+
-
...
-
-
+
-
Define the value of the ExampleCredential interface object's [[type]] slot:
The ExampleCredential interface object has an internal slot named [[type]] whose
value is the string "example".
- -
+
-
Define the value of the ExampleCredential interface object's [[discovery]] slot:
The ExampleCredential interface object has an internal slot named [[type]] whose
value is "credential store".
- -
+
-
Extend CredentialRequestOptions with the options the new credential type needs to respond
reasonably to get():
@@ -3288,7 +3317,7 @@
- -
+
-
Extend CredentialCreationOptions with the data the new credential type needs to create Credential objects in response to create():
@@ -3384,6 +3413,7 @@ collect local, in §2.5.2
- create(), in §2.3
+
- create a copy of any buffer sources' data, in §2.3.1
- Create a Credential, in §2.5.4
- Create a FederatedCredential from FederatedCredentialInit, in §4.2.4
- Create a PasswordCredential from an HTMLFormElement, in §3.3.4
@@ -3398,7 +3428,6 @@
Credential, in §2.2
- credential, in §2
-
- CredentialBodyType, in §3.2
- credential chooser, in §5.3
- CredentialCreationOptions, in §2.4
- CredentialData, in §2.3
@@ -3547,6 +3576,12 @@
6.2. Credential Leakage
+
-
+
+
+
+
+ do we need to explicitly free the bytes we just orphaned? ↵
This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in. ↵
@@ -4895,6 +4950,13 @@ 5.3. Credential Selection
+
+
+ To create a copy of any buffer sources' data referenced by a value |V| of
+ [=dictionary=] type, run the following steps given |V|:
+
+
+ 1. Let |dictionaries| be a list consisting of |V| and all of |V|'s
+ [=inherited dictionaries=], in order from least to most derived.
+
+ 2. For each dictionary |dictionary| in |dictionaries|, in order:
+
+ 1. For each dictionary member |member| declared on
+ |dictionary|, in lexicographical order:
+
+ 1. Let |key| be the [=identifier=] of |member|.
+
+ 2. If the dictionary member named |key| is [=present=] in |V|, then:
+
+ 1. Let |value| be the value of |member| on |V|.
+
+ 2. If |value|'s type is a [=buffer source type=] then
+ [=get a copy of the bytes held by the buffer source=] and
+ set |values|'s value to be a reference to the copy of the bytes.
+
+ issue: do we need to explicitly free the bytes we just orphaned?
+
+
+
+
### Mediation Requirements ### {#mediation-requirements}
When making a request via {{get(options)}}, developers can set a case-by-case requirement for
@@ -729,8 +757,10 @@ Request a `Credential`
5. Let |sameOriginWithAncestors| be `true` if |settings| is [=same-origin with its
ancestors=], and `false` otherwise.
+
+ 6. [=Create a copy of any buffer sources' data=] referenced by |options|.
- 6. Run the following steps [=in parallel=]:
+ 7. Run the following steps [=in parallel=]:
1. Let |credentials| be the result of collecting
`Credential`s from the credential store, given |options| and
@@ -775,7 +805,7 @@ Request a `Credential`
Otherwise, [=reject=] |p| with |result|.
- 7. Return |p|.
+ 8. Return |p|.
Collect `Credential`s from the credential store
@@ -868,9 +898,11 @@ Create a `Credential`
6. If |options|.{{CredentialCreationOptions/signal}}'s [=AbortSignal/aborted
flag=] is set, then return [=a promise rejected with=] an "{{AbortError}}" {{DOMException}}.
- 7. Let |p| be [=a new promise=].
+ 7. [=Create a copy of any buffer sources' data=] referenced by |options|.
+
+ 8. Let |p| be [=a new promise=].
- 8. Run the following steps [=in parallel=]:
+ 9. Run the following steps [=in parallel=]:
1. Let |r| be the result of executing |interfaces|[0]
{{Credential/[[Create]](options, sameOriginWithAncestors)}} internal method on |options|
@@ -880,7 +912,7 @@ Create a `Credential`
Otherwise, [=resolve=] |p| with |r|.
- 9. Return |p|.
+ 10. Return |p|.
Prevent Silent Access
Credential interface. This
document defines two such interfaces, PasswordCredential and FederatedCredential.A password credential may stop being effective if the account holder changes their password.
-A credential made from a token received over SMS is likely to only be effective for a single use.
2.1. Infrastructure
-User agents MUST internally provide a credential
+ User agents MUST internally provide a credential
store, which is a vendor-specific, opaque storage mechanism to record which credentials have been effective. It offers the following capabilities for credential access and
persistence: Store a credential for later retrieval.
This accepts a credential, and inserts it into the credential store. Retrieve a list of credentials. This
+ Retrieve a list of credentials. This
accepts an arbitrary filter, and returns a set of credentials that match the filter. Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store. Modify a credential. This accepts a credential, and overwrites the state of an existing credential in the credential store. Additionally, the credential store should maintain a Additionally, the credential store should maintain a Note: The importance of user mediation is discussed in more detail in §5 User Mediation. Note: The credential store is an internal implementation detail of a user agent’s
implementation of the API specified in this document, and is not exposed to the web directly.
More capabilities may be specified by other documents in support of specific credential types. This document depends on the Infra Standard for a number of foundational concepts used in its
algorithms and prose [INFRA]. An environment settings object (settings) is same-origin with its
+ An environment settings object (settings) is same-origin with its
ancestors if the following algorithm returns If settings has no responsible browsing context,
return Let origin be settings’ origin. Let current be settings’ responsible browsing context. While current has a parent browsing context: Set current to current’s parent browsing context. If current’s active document's origin is not same origin with origin,
return Return The credential’s identifier. The requirements for the identifier are distinct for each type
of credential. It might represent a username for username/password tuples, for example. This attribute’s getter returns the value of the object’s interface object's The Note: The The Talk to Tobie/Dominic about the interface object bits, here and in §2.5.1 Request a Credential, etc. I’m not sure I’ve gotten the terminology right. interface prototype
object, maybe? Some Some Each interface object created for interfaces which inherit from Return an empty set. Return Return Return Some A name associated with the credential, intended as a human-understandable public name for
display in a credential chooser. A URL pointing to an image for the credential, intended for display in a credential chooser. This URL MUST be an a priori authenticated
URL. Developers retrieve The The Note: As discussed in §6.3 Insecure Sites, the credential management API is exposed only in Secure Contexts. When When When When This property specifies the mediation requirements for a given credential request. The
meaning of each enum value is described below in This property lets the developer abort an ongoing Let settings be the current settings object Let interface objects be the set of interface objects on settings’ global object. Let relevant interface objects be an empty set. For each object in interface objects: If object’s inherited interfaces do not contain Let key be object’s If options[key] exists, append object to relevant interface objects. For each interface in options’ relevant credential interface objects: If interface’s Return Note: When executing Let dictionaries be a list consisting of V and all of V’s inherited dictionaries, in order from least to most derived. For each dictionary dictionary in dictionaries, in order: For each dictionary member member declared on dictionary, in lexicographical order: Let key be the identifier of member. If the dictionary member named key is present in V, then: Let value be the value of member on V. If value’s type is a buffer source type then get a copy of the bytes held by the buffer source and
+set values’s value to be a reference to the copy of the bytes. When making a request via Note: The §5 User Mediation section gives more detail on the concept in general, and its
implications on how the user agent deals with individual requests for a given origin). User mediation is suppressed for the given operation. If the operation can be performed
without user involvement, wonderful. If user involvement is necessary, then the operation
will return If credentials can be handed over for a given operation without user mediation, they will
be. If user mediation is required, then the user agent will
involve the user in the decision. The user agent will not hand over credentials without user mediation, even if the prevent silent access flag is unset for an origin. Note: This requirement is intended to support reauthentication or user-switching scenarios. Further, the requirement is tied
to a specific operation, and does not affect the prevent silent access flag for the
@@ -2118,7 +2145,7 @@ This property lets the developer abort an ongoing The Request a The Request a Let settings be the current settings object Assert: settings is a secure context. If Let p be a new promise. Let sameOriginWithAncestors be Create a copy of any buffer sources' data referenced by options. Run the following steps in parallel: Let credentials be the result of collecting If all of the following statements are true, resolve p with credentials[0] and
skip the remaining steps: credentials’ size is 1 settings’ origin does not require user mediation options is matchable a priori. This might be the wrong model. It would be nice to support a site that wished
to accept either username/passwords or webauthn-style credentials without forcing
a chooser for those users who use the former, and who wish to remain signed in. If options’ Let choice be the result of asking the user to
choose a If choice is Assert: choice is an interface object. Let result be the result of executing choice’s If result is a Otherwise, reject p with result. Return p. Given a Let possible matches be an empty set. For each interface in options’ relevant credential interface objects: Let r be the result of executing interface’s If r is an exception, return r. Assert: r is a list of interface objects. For each c in r: Append c to possible matches. Return possible matches. The Store a The Store a Let settings be the current settings object Assert: settings is a secure context. Let sameOriginWithAncestors be Let p be a new promise. Run the following steps in parallel: Let r be the result of executing credential’s interface object's If r is an exception, reject p with r. Otherwise, resolve p with r. Return p. The Create a The Create a Let settings be the current settings object Assert: settings is a secure context. Let sameOriginWithAncestors be Let interfaces be the set of options’ relevant credential interface objects. Return a promise rejected with settings does not have a responsible document. interfaces’ size is greater than 1. Note: It may be reasonable at some point in the future to loosen this restriction, and
allow the user agent to help the user choose among one of many potential credential
types in order to support a "sign-up" use case. For the moment, though, we’re punting
on that by restricting the dictionary to a single entry. If Create a copy of any buffer sources' data referenced by options. Let p be a new promise. Run the following steps in parallel: Let r be the result of executing interfaces[0] If r is an exception, reject p with r. Otherwise, resolve p with r. Return p. The Prevent Silent Access algorithm accepts an environment settings
+ The Prevent Silent Access algorithm accepts an environment settings
object (settings), and returns a Let origin be settings’ origin. Let p be a new promise Run the following seps in parallel: Set origin’s Resolve p with Retun p. This attribute represents the password of the credential. The The This constructor accepts an Let r be the result of executing Create a If r is an exception, throw r. Otherwise, return r. This constructor accepts a Let r be the result of executing Create a If r is an exception, throw r. Otherwise, return r. The algorithm will return a If |sameOriginWithAncestors is Note: This restriction aims to address the concern raised in §6.4 Origin Confusion. Return the empty set if options[" Return the result of retrieving credentials from the credential store that match the following filter: The credential is a The credential’s Assert: options[" If options[" If options[" The algorithm will return a Return a " Note: This restriction aims to address the concern raised in §6.4 Origin Confusion. If the user agent’s credential store contains a If the user grants permission to update credentials (as discussed when defining user mediation), then: Otherwise, if the user grants permission to store credentials (as discussed when
defining user mediation, then: Store a credential’s credential’s credential’s credential’s credential’s Return To Create a To Create a Note: §3.1.2 Post-sign-in Confirmation and §3.1.3 Change Password provide examples of the intended
usage. Let data be a new Let formData be the result of executing the Let formData be the result of executing the Let elements be a list of all the submittable elements whose form owner is form, in tree order. Let newPasswordObserved be For each field in elements, run the following steps: If field does not have an Let name be the value of field’s If formData’s If field’s For each token in tokens: If token is an ASCII case-insensitive match for one
of the following strings, run the associated steps: Set data’s If newPasswordObserved is Note: By checking that newPasswordObserved is Set data’s Set data’s Set data’s Let c be the result of executing Create a If c is an exception, return c. Assert: c is a Return c. To Create a To Create a Let c be a new If any of the following are the empty string, return a Set c’s properties as follows: Return c. Given a If options has a Return " The credential’s federated identity provider. See §4.1.1 Identifying Providers for
details regarding valid formats. The credential’s federated identity provider’s protocol (e.g. " The The This constructor accepts a Let r be the result of executing Create a If r is an exception, throw r. Otherwise, return r. The algorithm will return a If |sameOriginWithAncestors is Note: This restriction aims to address the concern raised in §6.4 Origin Confusion. Return the empty set if options[" Return the result of retrieving credentials from the credential store that match the following filter: The credential is a The credential’s If options[" If options[" Assert: options[" Return the result of executing Create a The algorithm will return a Return a " Note: This restriction aims to address the concern raised in §6.4 Origin Confusion. If the user agent’s credential store contains a If the user grants permission to store credentials (as discussed when defining user mediation), then store a Return To Create a To Create a Let c be a new If any of the following are the empty string, return a Set c’s properties as follows: Return c. We call a particular action user mediated if
it takes place after gaining a user’s explicit consent. Consent might be expressed through a
user’s direct interaction with a credential chooser interface, for example. In general, user
mediated actions will involve presenting the user some sort of UI, and asking them to make a
@@ -3031,7 +3060,7 @@ Credential information SHOULD NOT be stored or updated without user mediation. For
example, the user agent could display a "Save this credential?" dialog box to the user in
response to each call to User agents SHOULD notify users when credentials are stored. This might take the form of an
icon in the address bar, or some similar location. User agents MUST allow users to manually remove stored credentials. This functionality might
be implemented as a settings page, or via interaction with a notification as described above. To mitigate the risk of surprise: User agents MUST allow users to require user mediation for a given origin or for all
origins. This functionality might be implemented as a global toggle that overrides each
origin’s User agents MUST NOT set an origin's User agents MUST notify users when credentials are provided to an origin. This could take the
form of an icon in the address bar, or some similar location. If a user clears her browsing data for an origin (cookies, localStorage, and so on), the user
agent MUST set the When responding to a call to The chooser interface SHOULD be implemented in such a way as to be distinguishable from UI which a
@@ -3092,7 +3121,7 @@ This algorithm returns either As a compromise between annoying users, and securing their credentials, user agents: MUST NOT share credentials between origins whose scheme components represent a downgrade in
security. That is, it may make sense to allow credentials saved on MAY use the Public Suffix List [PSL] to determine the effective scope of a credential by
comparing the registerable domain of the credential’s MUST NOT offer credentials to an origin in response to Describe encoding restrictions of submitting credentials by When performing feature detection for a given credential type, developers are encouraged to verify
that the relevant Define a new interface that inherits from Define appropriate Assert: If For each credential in the credential store: ... Define the value of the Define the value of the Extend Extend
-
- prevent silent access flag for origins (which is set to true unless otherwise specified).
- An origin requires user mediation if its flag is set to true.prevent silent access flag for origins (which is set to true unless otherwise specified).
+ An origin requires user mediation if its flag is set to true.true:
-
false.
-
- false.true.2.2. The
-Credential Interface[Exposed=Window, SecureContext]
-interface
Credential {
- readonly attribute USVString id;
- readonly attribute DOMString type;
+[
-
id, of type USVString, readonly
- id, of type USVString, readonly
+ type, of type DOMString, readonly
- type, of type DOMString, readonly
+ [[type]] slot, which specifies the kind of credential represented by this object.[[type]]
- [[type]]
+ Credential interface object has an internal slot named [[type]], which
unsurprisingly contains a string representing the type of the credential. The slot’s value
is the empty string unless otherwise specified.[[type]] slot’s value will be the same for all credentials implementing a
particular interface, which means that developers can rely on obj.type returning a string
that unambigiously represents the specific kind of Credential they’re dealing with.[[discovery]]
- [[discovery]]
+ Credential interface object has an internal slot named [[discovery]],
representing the mechanism by which the user agent can collect credentials of
a given type. Its value is either
- "credential store" or
- "remote". The former value means that
+ "credential store" or
+ "remote". The former value means that
all available credential information is stored in the user agent’s credential store,
while the latter means that the user agent can discover credentials outside of those
explicitly represented in the credential store via interaction with some external device
@@ -1828,46 +1828,46 @@
Credential objects are origin bound: these contain an
- internal slot named [[origin]], which stores the origin for which the Credential may be effective.Credential objects are origin bound: these contain an
+ internal slot named [[origin]], which stores the origin for which the Credential may be effective.2.2.1.
Credential Internal MethodsCredential defines several internal methods that allow retrieval and storage of Credential objects:[[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
+ [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns a
set of Credential objects from the user agent’s credential store that match the options
provided. If no matching Credential objects are available, the returned set will be empty.
-
[[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
+ [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions object, and a boolean which is true iff the
caller’s environment settings object is same-origin with its ancestors. It returns a Credential if one can be returned given the options provided, null if no credential is
available, or an error if discovery fails (for example, incorrect options could produce a TypeError). If this kind of Credential is only effective for a single use or a
limited time, this method is responsible for generating new credentials using a credential source.
-
null.[[Store]](credential, sameOriginWithAncestors) is
+ [[Store]](credential, sameOriginWithAncestors) is
called with a Credential, and a boolean which is true iff the caller’s environment
settings object is same-origin with its ancestors. The algorithm returns once Credential is persisted to the credential store:
-
undefined.[[Create]](options, sameOriginWithAncestors) is
+ [[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions, and a boolean which is true iff the caller’s environment settings object is same-origin with its ancestors. The algorithm returns
either a Credential, if one can be created, null if no credential was created, or an
error if creation fails due to exceptional situations (for example, incorrect options could
produce a TypeError):
-
null.
2.2.2.
CredentialUserData MixinCredential objects contain data which aims to give users a human-readable disambiguation
mechanism in the credential chooser by providing a friendly name and icon:[SecureContext]
-interface mixin
CredentialUserData {
- readonly attribute USVString name;
- readonly attribute USVString iconURL;
+[
-
@@ -1897,28 +1897,28 @@ name, of type USVString, readonly
- name, of type USVString, readonly
+ iconURL, of type USVString, readonly
- iconURL, of type USVString, readonly
+ navigator.credentials
Credentials and interact with the user agent’s credential store via
methods exposed on the CredentialsContainer interface, which hangs off the Navigator object as navigator.credentials.partial interface Navigator {
- [SecureContext, SameObject] readonly attribute CredentialsContainer credentials;
+
- credentials attribute MUST return the CredentialsContainer associated with the context object.credentials attribute MUST return the CredentialsContainer associated with the context object.[Exposed=Window, SecureContext]
-interface
CredentialsContainer {
- Promise<Credential?> get(optional CredentialRequestOptions options);
- Promise<Credential> store(Credential credential);
- Promise<Credential?> create(optional CredentialCreationOptions options);
- Promise<void> preventSilentAccess();
+[
CredentialData {
- required USVString id;
+
-
get(options)
- get(options)
+ get() is called, the user agent MUST return the result of
executing Request a Credential on options.
@@ -1932,14 +1932,14 @@
- options
+ options
CredentialRequestOptions
✘
✔
The set of properties governing the scope of the request.
store(credential)
- store(credential)
+ store() is called, the user agent MUST return the result of
executing Store a Credential on credential.
@@ -1953,14 +1953,14 @@
- credential
+ credential
Credential
✘
✘
The credential to be stored.
create(options)
- create(options)
+ create() is called, the user agent MUST return the result of
executing Create a Credential on options.
@@ -1974,14 +1974,14 @@
- options
+ options
CredentialCreationOptions
✘
✔
The options used to create a Credential.
preventSilentAccess()
- preventSilentAccess()
+ preventSilentAccess() is called, the user agent MUST return
the result of executing Prevent Silent Access on the current settings
object.Note: The
CredentialRequestOptions dictionary is an extension point. If and when new types of
credentials are introduced that require options, their dictionary types will be added to the
dictionary so they can be passed into the request. See §7.2 Extension Points.
-dictionary
CredentialRequestOptions {
- CredentialMediationRequirement mediation = "optional";
- AbortSignal signal;
+
-
mediation, of type CredentialMediationRequirement, defaulting to "optional"
- mediation, of type CredentialMediationRequirement, defaulting to "optional"
+ CredentialMediationRequirement.
Processing details are defined in §2.5.1 Request a Credential.signal, of type AbortSignal
- signal, of type AbortSignal
+ get() operation.
An aborted operation may complete normally (generally if the abort was received after the
operation finished) or reject with an "AbortError" DOMException."mediation.
CredentialRequestOptions (options) is a set of interface objects, collected as follows:
+ The relevant credential interface objects for a given CredentialRequestOptions (options) is a set of interface objects, collected as follows:
-
@@ -2053,17 +2053,17 @@
-
Credential, continue.[[type]] slot’s value.
- A given
CredentialRequestOptions options is matchable a priori if the following
+ A given CredentialRequestOptions options is matchable a priori if the following
steps return true:
-
-
- [[discovery]] slot’s value is not
"credential store", return false.true.get(options), we only return credentials without user mediation if
@@ -2072,20 +2072,47 @@ user mediation will be required in order
to guide the discovery process (by choosing a federated identity provider, BTLE device, etc).
+
+
+
+
+
+
+
+ 2.3.2. Mediation Requirements
get(options), developers can set a case-by-case requirement for user mediation by choosing the appropriate CredentialMediationRequirement enum value.enum
CredentialMediationRequirement {
- "silent",
- "optional",
- "required"
+
-
silent
- silent
+ null rather than involving the user., where a developer may wish to silently obtain
credentials if a user should be automatically signed in, but to delay bothering the user
with a sign-in prompt until they actively choose to sign-in.
-
optional
- optional
+ credential chooser if necessary.
-
required
- required
+ §5.2 Requiring User Mediation)
are signed in, and users who haven’t opted-into such behavior won’t be bothered with a confusing credential chooser popping up without context:
window.addEventListener('load', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'silent'
});
@@ -2133,7 +2160,7 @@ opted-into signing in without user mediation, and the user agent can unambigiously choose a credential, great! If
not, a credential chooser will be presented.
document.querySelector('#sign-in').addEventListener('click', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'optional'
});
@@ -2154,7 +2181,7 @@
document.querySelector('#important-form').addEventListener('submit', async () => {
- const credentials = await navigatior.credentials.get({
+ const credentials = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2173,7 +2200,7 @@ required" in order to ensure that that credentials aren’t
returned automatically in response to clicking on an "Add account" button:
document.querySelector('#switch-button').addEventListener('click', e => {
- var c = await navigatior.credentials.get({
+ var c = await navigator.credentials.get({
...,
mediation: 'required'
});
@@ -2189,192 +2216,196 @@ Note: The
CredentialCreationOptions dictionary is an extension point. If and when new types of
credentials are introduced, they will add to the dictionary so they can be passed into the
creation method. See §7.2 Extension Points, and the extensions introduced in this document: §3.2 The PasswordCredential Interface and §4.1 The FederatedCredential Interface.
-dictionary
CredentialCreationOptions {
- AbortSignal signal;
+
-
signal, of type AbortSignal
- signal, of type AbortSignal
+ create() operation. An aborted operation may complete normally (generally if the abort was received
after the operation finished) or reject with an "AbortError" DOMException."2.5. Algorithms
2.5.1. Request a
- CredentialCredential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
+ Credential algorithm accepts a CredentialRequestOptions (options), and returns a Promise that resolves with a Credential if one can be
unambigiously obtained, or with null if not.
-
options.’s aborted flag is set, then return a promise rejected with an "signalAbortError" DOMException.true if settings is same-origin with its
ancestors, and false otherwise.
-
- Credentials from the credential store, given options and sameOriginWithAncestors.
-
mediation is
"silent", resolve p with null, and skip
the remaining steps.Credential, given options and credentials.null or a Credential, resolve p with choice and skip the
remaining steps.[[DiscoverFromExternalSource]](options, sameOriginWithAncestors), given options and sameOriginWithAncestors.Credential or null, resolve p with result.2.5.2. Collect
Credentials from the credential storeCredentialRequestOptions (options) and a boolean which is true iff the calling
- context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
+ context is same-origin with its ancestors (sameOriginWithAncestors), the user agent may collect Credentials from the credential store,
returning a set of Credential objects stored by the user agent locally that match options’
filter. If no such Credential objects are known, the returned set will be empty:
-
-
- [[CollectFromCredentialStore]](options, sameOriginWithAncestors) internal
method on options and sameOriginWithAncestors.
-
2.5.3. Store a
- CredentialCredential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.Credential algorithm accepts a Credential (credential), and returns a Promise which resolves once the object is persisted to the credential store.
-
true if the current settings object is same-origin
with its ancestors, and false otherwise.
-
- [[Store]](credential, sameOriginWithAncestors) internal method on credential and sameOriginWithAncestors.2.5.4. Create a
- CredentialCredential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
+ Credential algorithm accepts a CredentialCreationOptions (options), and returns a Promise which resolves with a Credential if one can be created
using the options provided, or null if no Credential can be created. In exceptional
circumstances, the Promise may reject with an appropriate exception:
-
true if the current settings object is same-origin
with its ancestors, and false otherwise.NotSupportedError if any of the following statements
are true:
-
- options.’s aborted
flag is set, then return a promise rejected with an "signalAbortError" DOMException.
-
- [[Create]](options, sameOriginWithAncestors) internal method on options and sameOriginWithAncestors.2.5.5. Prevent Silent Access
- Promise which resolves once the prevent silent access flag is persisted to the credential store.
-
@@ -2386,8 +2417,8 @@
-
- prevent silent access flag in the credential store.undefined.3.
from within a credential chooser.
3.1. Examples
3.1.1. Password-based Sign-in
- navigator.credentials.get() to obtain
+ navigator.credentials.get() to obtain
username/password pairs from a user’s credential store:
navigator.credentials
.get({ 'password': true })
@@ -2429,12 +2460,12 @@
@@ -2538,51 +2569,49 @@ 3.2. The
-PasswordCredential Interfacetypedef (FormData or URLSearchParams)
CredentialBodyType;
-
-[Constructor(HTMLFormElement form),
- Constructor(PasswordCredentialData data),
- Exposed=Window,
- SecureContext]
-interface PasswordCredential : Credential {
- readonly attribute USVString password;
+[
password = false;
+
-
password, of type USVString, readonly
- password, of type USVString, readonly
+ [[type]]
- [[type]]
+ PasswordCredential interface object has an internal slot named [[type]] whose
- value is "password".[[discovery]]
- password".
+ [[discovery]]
+ PasswordCredential interface object has an internal slot named [[discovery]] whose value is "credential store".PasswordCredential(form)
- PasswordCredential(form)
+ HTMLFormElement (form), and runs the following steps:
-
- PasswordCredential from
an HTMLFormElement on form.PasswordCredential(data)
- PasswordCredential(data)
+ PasswordCredentialData (data), and runs the following steps:
-
@@ -2590,16 +2619,16 @@ PasswordCredential from PasswordCredentialData on data.<
PasswordCredential objects can be created via navigator.credentials.create() either explicitly by passing in a PasswordCredentialData dictionary, or based on the contents
of an HTMLFormElement's submittable elements.dictionary
PasswordCredentialData : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString password;
+PasswordCredentialInit;
+password;
+PasswordCredential objects are origin bound.<
own implementation of
[[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[Create]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors).
3.3. Algorithms
3.3.1.
- PasswordCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors) [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
+ [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called with a CredentialRequestOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a set of Credential objects from the credential store. If no matching Credential objects are available, or sameOriginWithAncestors is false, the returned set
will be empty.NotAllowedError if sameOriginWithAncestors is not true.
-
false, return a "NotAllowedError" DOMException.password"] is not true.
-
PasswordCredential[[origin]] is the same origin as the current settings object's origin.3.3.2.
- PasswordCredential's [[Create]](options, sameOriginWithAncestors) [[Create]](options, sameOriginWithAncestors) is called
+ [[Create]](options, sameOriginWithAncestors) is called
with a CredentialCreationOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns a PasswordCredential if one can be created, and null otherwise. The CredentialCreationOptions dictionary must have a password member which holds either an HTMLFormElement or a PasswordCredentialData. If that member’s value cannot be
used to create a PasswordCredential, this algorithm will return a TypeError exception.
-
password"] exists, and sameOriginWithAncestors is unused.password"] is an HTMLFormElement, return the
result of executing Create a PasswordCredential from an HTMLFormElement on options["password"].password"] is a PasswordCredentialData, return
the result of executing Create a PasswordCredential from PasswordCredentialData on options["password"].3.3.3.
- PasswordCredential's [[Store]](credential, sameOriginWithAncestors) [[Store]](credential, sameOriginWithAncestors) is
+ [[Store]](credential, sameOriginWithAncestors) is
called with a PasswordCredential (credential), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns undefined once credential is persisted to the credential store.NotAllowedError if sameOriginWithAncestors is not true.
-
NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.PasswordCredential (stored)
whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]],
then:
-
-
- PasswordCredential in the credential store with the following
properties:
-
id
- id
+ idname,
- name,
+ nameiconURL
- iconURL
+ iconURL[[origin]]
- [[origin]]
+ [[origin]]password
- password
+ passwordundefined.3.3.4. Create a
- PasswordCredential from an HTMLFormElement PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.PasswordCredential from an HTMLFormElement, given an HTMLFormElement (form), run these steps.
-
PasswordCredentialData dictionary.FormData constructor
+ FormData constructor
on form.false.
-
autocomplete attribute, then skip to the next field.name attribute.has() method returns false when executed on name, then
skip to the next field.autocomplete attribute’s value contains one or more autofill
detail tokens (tokens), then:
-
-
-
new-password"
- new-password"
+ password member’s
value to the result of executing formData’s get() method on name, and newPasswordObserved to true.current-password"
- current-password"
+ false,
set data’s password member’s
value to the result of executing formData’s get() method on name.false, new-password fields take precedence over current-password fields.photo"
- photo"
+ iconURL member’s
value to the result of executing formData’s get() method on name.name"
- nickname"
- name"
+ nickname"
+ name member’s
value to the result of executing formData’s get() method on name.username"
- username"
+ id member’s value to the
result of executing formData’s get() method
on name.
+
PasswordCredential from PasswordCredentialData on data.PasswordCredential.3.3.5. Create a
- PasswordCredential from PasswordCredentialData PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.PasswordCredential from PasswordCredentialData, given an PasswordCredentialData (data), run these steps.
-
PasswordCredential object.TypeError exception:3.3.6.
CredentialRequestOptions Matching for PasswordCredential CredentialRequestOptions (options), the following algorithm returns "Matches" if
the PasswordCredential should be available as a response to a get() request, and "Does Not Match" otherwise.
-
password member whose value is true, then
return "Matches".Does Not Match".4. Federated Credentials
4.1. The
-FederatedCredential Interface[Constructor(FederatedCredentialInit
data),
- Exposed=Window,
- SecureContext]
-interface FederatedCredential : Credential {
- readonly attribute USVString provider;
- readonly attribute DOMString? protocol;
+[
FederatedCredentialRequestOptions {
- sequence<USVString> providers;
- sequence<DOMString> protocols;
+federated;
+
-
provider, of type USVString, readonly
- provider, of type USVString, readonly
+ protocol, of type DOMString, readonly, nullable
- protocol, of type DOMString, readonly, nullable
+ openidconnect"). If the
value is null, then the protocol can be inferred from the provider.[[type]]
- [[type]]
+ FederatedCredential interface object has an internal slot named [[type]] whose
- value is "federated".[[discovery]]
- federated".
+ [[discovery]]
+ FederatedCredential interface object has an internal slot named [[discovery]] whose value is "credential store".FederatedCredential(data)
- FederatedCredential(data)
+ FederatedCredentialInit (data), and runs the following steps:
-
@@ -2868,15 +2897,15 @@ FederatedCredential from FederatedCredentialInit on data.
FederatedCredential objects can be created by passing a FederatedCredentialInit dictionary
into navigator.credentials.create().dictionary
FederatedCredentialInit : CredentialData {
- USVString name;
- USVString iconURL;
- required USVString provider;
- DOMString protocol;
+federated;
+FederatedCredential objects are origin bound.4.2. Algorithms
4.2.1.
- FederatedCredential's [[CollectFromCredentialStore]](options, sameOriginWithAncestors) [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
+ [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is called
with a CredentialRequestOptions (options), and a boolean which is true iff the calling
context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns
a set of Credential objects from the credential store. If no matching Credential objects are available, the returned set will be empty.NotAllowedError if sameOriginWithAncestors is not true.
-
false, return a "NotAllowedError" DOMException.federated"] is not true.
-
FederatedCredential[[origin]] is the same origin as the current settings object's origin.federated"]["providers"] exists, its value contains the credentials’s provider.federated"]["protocols"] exists, its value contains the credentials’s protocol.4.2.2.
- FederatedCredential's [[Create]](options, sameOriginWithAncestors) [[Create]](options, sameOriginWithAncestors) is
+ [[Create]](options, sameOriginWithAncestors) is
called with a CredentialCreationOptions (options), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns a FederatedCredential if one can be created, null otherwise, or an exception in
exceptional circumstances:
-
federated"] exists, and sameOriginWithAncestors is unused.FederatedCredential from FederatedCredentialInit on options["federated"].4.2.3.
- FederatedCredential's [[Store]](credential, sameOriginWithAncestors) [[Store]](credential, sameOriginWithAncestors) is
+ [[Store]](credential, sameOriginWithAncestors) is
called with a FederatedCredential (credential), and a boolean which is true iff the
calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm
returns undefined once credential is persisted to the credential store.NotAllowedError if sameOriginWithAncestors is not true.
-
NotAllowedError" DOMException without altering the user agent’s credential store if sameOriginWithAncestors is false.FederatedCredential whose id attribute is credential’s id and whose [[origin]] slot is the same origin as credential’s [[origin]], and
whose provider is credential’s provider, then return.FederatedCredential in the credential store with
the following properties:undefined.4.2.4. Create a
- FederatedCredential from FederatedCredentialInit FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.
-
FederatedCredential object.TypeError exception:user mediated if
+
-
@@ -3056,25 +3085,25 @@ store().
-
-
prevent silent access flag to return false, or via more granular
settings for specific origins (or specific credentials on specific origins).prevent silent access flag to false without user mediation. For example, the credential chooser described in §5.3 Credential Selection could have a checkbox which the user could toggle to mark a
credential as available without mediation for the origin, or the user agent could have an
onboarding process for its credential manager which asked a user for a default setting.prevent silent access flag to true for that origin.5.3. Credential Selection
get() on an origin which requires user mediation, user agents MUST ask the user for permission to share credential information.
- This SHOULD take the form of a credential chooser which presents the user with a
+ This SHOULD take the form of a credential chooser which presents the user with a
list of credentials that are available for use on a site, allowing them to select one which should
be provided to the website, or to reject the request entirely.
Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
+ The user agent can ask the user to choose a Credential, given a CredentialRequestOptions (options), and a set of Credential objects from the credential store (locally discovered credentials).
null if the user chose not to share a credential with the site,
a Credential object if the user chose a specific credential, or a Credential interface
object if the user chose a type of credential.admin.example.com.
-
@@ -3142,14 +3171,14 @@ http://example.com/ to
be made available to https://example.com/ (in order to encourage developers to migrate to
secure transport), but the inverse would be dangerous.[[origin]] with the
origin in which get() is called. That is: credentials saved on https://admin.example.com/ and https://example.com/ MAY be offered to users when get() is called from https://www.example.com/, and vice versa.get() without user mediation if the credential’s origin is not an exact match for the calling origin.
That is, Credential objects for https://example.com would not be returned directly to https://www.example.com, but could be offered to the user via the chooser.[CSP] which restricts the endpoints to which data can be sent. In particular, developers should ensure
that the following directives are set, explicitly or implicitly, in their pages' policies:
-
@@ -3221,7 +3250,7 @@ script-src and object-src both restrict script execution on a page, making
it less likely that a cross-site scripting attack will succeed in the first place. If sites
are populating form elements, also form-action directives should be set.connect-src restricts the origins to which fetch() may submit data (which
mitigates the risk that credentials could be exfiltrated to evil.com.child-src restricts the nested browsing contexts which may be embedded in a page,
making it more difficult to inject a malicious postMessage() target. [WEBMESSAGING] Add some thoughts here about when and how the API
should be used, especially with regard to
mediation. <https://github.com/w3c/webappsec/issues/290>
fetch() with
- a FormData body.FormData body.
Credential specialization is present, rather than relying on the presence of navigator.credentals. The latter verifies the existence of the API itself, but does not ensure
that the specific kind of credential necessary for a given site is supported. For example, if a
@@ -3232,7 +3261,7 @@ credentials that serve specific authentication needs. Doing so is, hopefully,
straightforward:
-
Credential:[[Create]](options, sameOriginWithAncestors), [[CollectFromCredentialStore]](options, sameOriginWithAncestors), [[DiscoverFromExternalSource]](options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors) methods on ExampleCredential's interface object. [[CollectFromCredentialStore]](options, sameOriginWithAncestors) is appropriate for credentials that remain effective forever and
can therefore simply be copied out of the credential store, while [[DiscoverFromExternalSource]](options, sameOriginWithAncestors) is
appropriate for credentials that need to be re-generated from a credential source.true iff the calling context is same-origin with its ancestors. The algorithm
returns a set of
Credential objects that match the options provided. If no matching Credential objects are available, the returned set will be empty.
-
options[example] exists.options[example] is not truthy, return the empty set.
-
ExampleCredential interface object's [[type]] slot:ExampleCredential interface object has an internal slot named [[type]] whose
value is the string "example". ExampleCredential interface object's [[discovery]] slot:ExampleCredential interface object has an internal slot named [[type]] whose
value is "credential store". CredentialRequestOptions with the options the new credential type needs to respond
reasonably to get():
CredentialCreationOptions with the data the new credential type needs to create Credential objects in response to create():collect local, in §2.5.2
Credential, in §2.2
6.2. Credential Leakage
+
-
+
+
+
+
5.3. Credential Selection
+
+ 1. Let |dictionaries| be a list consisting of |V| and all of |V|'s
+ [=inherited dictionaries=], in order from least to most derived.
+
+ 2. For each dictionary |dictionary| in |dictionaries|, in order:
+
+ 1. For each dictionary member |member| declared on
+ |dictionary|, in lexicographical order:
+
+ 1. Let |key| be the [=identifier=] of |member|.
+
+ 2. If the dictionary member named |key| is [=present=] in |V|, then:
+
+ 1. Let |value| be the value of |member| on |V|.
+
+ 2. If |value|'s type is a [=buffer source type=] then
+ [=get a copy of the bytes held by the buffer source=] and
+ set |values|'s value to be a reference to the copy of the bytes.
+
+ issue: do we need to explicitly free the bytes we just orphaned?
+
+ Request a `Credential`
5. Let |sameOriginWithAncestors| be `true` if |settings| is [=same-origin with its
ancestors=], and `false` otherwise.
+
+ 6. [=Create a copy of any buffer sources' data=] referenced by |options|.
- 6. Run the following steps [=in parallel=]:
+ 7. Run the following steps [=in parallel=]:
1. Let |credentials| be the result of collecting
`Credential`s from the credential store, given |options| and
@@ -775,7 +805,7 @@ Request a `Credential`
Otherwise, [=reject=] |p| with |result|.
- 7. Return |p|.
+ 8. Return |p|.
Collect `Credential`s from the credential store
@@ -868,9 +898,11 @@ Create a `Credential`
6. If |options|.{{CredentialCreationOptions/signal}}'s [=AbortSignal/aborted
flag=] is set, then return [=a promise rejected with=] an "{{AbortError}}" {{DOMException}}.
- 7. Let |p| be [=a new promise=].
+ 7. [=Create a copy of any buffer sources' data=] referenced by |options|.
+
+ 8. Let |p| be [=a new promise=].
- 8. Run the following steps [=in parallel=]:
+ 9. Run the following steps [=in parallel=]:
1. Let |r| be the result of executing |interfaces|[0]
{{Credential/[[Create]](options, sameOriginWithAncestors)}} internal method on |options|
@@ -880,7 +912,7 @@ Create a `Credential`
Otherwise, [=resolve=] |p| with |r|.
- 9. Return |p|.
+ 10. Return |p|.
Prevent Silent Access