Federated Credentials

1. Federated Credentials

1.1. The FederatedCredential Interface

[Exposed=Window,
 SecureContext]
interface FederatedCredential : Credential {
  constructor(FederatedCredentialInit data);
  readonly attribute USVString provider;
  readonly attribute DOMString? protocol;
};
FederatedCredential includes CredentialUserData;

dictionary FederatedCredentialRequestOptions {
  sequence<USVString> providers;
  sequence<DOMString> protocols;
};

partial dictionary CredentialRequestOptions {
  FederatedCredentialRequestOptions federated;
};

FederatedCredential objects can be created by passing a FederatedCredentialInit dictionary into navigator.credentials.create().

dictionary FederatedCredentialInit : CredentialData {
  USVString name;
  USVString iconURL;
  required USVString origin;
  required USVString provider;
  DOMString protocol;
};

partial dictionary CredentialCreationOptions {
  FederatedCredentialInit federated;
};

FederatedCredential objects are origin bound.

FederatedCredential's interface object inherits Credential's implementation of [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors), and defines its own implementation of [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors), [[Create]](origin, options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors).

Note: If, in the future, we teach the user agent to obtain authentication tokens on a user’s behalf, we could do so by building an implementation of [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors).

1.1.1. Identifying Providers

Every site should use the same identifier when referring to a specific federated identity provider. For example, Facebook Login shouldn’t be referred to as "Facebook" and "Facebook Login" and "FB" and "FBL" and "Facebook.com" and so on. It should have a canonical identifier which everyone can make use of, as consistent identification makes it possible for user agents to be helpful.

For consistency, federations passed into the APIs defined in this document (e.g. FederatedCredentialRequestOptions's providers array, or FederatedCredential's provider property) MUST be identified by the ASCII serialization of the origin the provider uses for sign in. That is, Facebook would be represented by https://www.facebook.com and Google by https://accounts.google.com.

This serialization of an origin does _not_ include a trailing U+002F SOLIDUS ("/"), but user agents SHOULD accept them silently: https://accounts.google.com/ is clearly intended to be the same as https://accounts.google.com.

1.2. Algorithms

1.2.1. FederatedCredential’s [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors)

[[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) is called with an origin (origin), a CredentialRequestOptions (options), and a boolean which is true if and only if 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.

1. Assert: options["federated"] exists.

2. If sameOriginWithAncestors is false, throw a "NotAllowedError" DOMException.

   Note: This restriction aims to address the concern raised in Credential Management 1 § 6.4 Origin Confusion.

3. Return the empty set if options["federated"] is not true.

4. Return the result of retrieving credentials from the credential store that match the following filter:

   1. The credential is a FederatedCredential

   2. The credential’s [[origin]] is the same origin as origin.

   3. If options["federated"]["providers"] exists, its value contains the credentials’s provider.

   4. If options["federated"]["protocols"] exists, its value contains the credentials’s protocol.

1.2.2. FederatedCredential’s [[Create]](origin, options, sameOriginWithAncestors)

[[Create]](origin, options, sameOriginWithAncestors) is called with an origin (origin), a CredentialCreationOptions (options), and a boolean which is true if and only if the calling context is same-origin with its ancestors (sameOriginWithAncestors). The algorithm returns a FederatedCredential if one can be created, null otherwise, or throws an exception in exceptional circumstances:

1. Assert: options["federated"] exists, and sameOriginWithAncestors is unused.

2. Set options["federated"]'s origin member’s value to origin’s value.

3. Return the result of executing Create a FederatedCredential from FederatedCredentialInit given options["federated"]. If that threw an exception, then rethrow that exception.

1.2.3. FederatedCredential’s [[Store]](credential, sameOriginWithAncestors)

[[Store]](credential, sameOriginWithAncestors) is called with a FederatedCredential (credential), and a boolean which is true if and only if 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.

1. Throw 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 Credential Management 1 § 6.4 Origin Confusion.

2. 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.

3. 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:

   id

   credential’s id

   name,

   credential’s name

   iconURL

   credential’s iconURL

   [[origin]]

   credential’s [[origin]]

   provider

   credential’s provider

   protocol

   credential’s protocol

1.2.4. Create a FederatedCredential from FederatedCredentialInit

To Create a FederatedCredential from FederatedCredentialInit, given a FederatedCredentialInit (init), run these steps.

1. Let c be a new FederatedCredential object.

2. If any of the following are the empty string, throw a TypeError exception:

   • init.id's value

   • init.provider's value

3. Set c’s properties as follows:

   id

   init.id's value

   provider

   init.provider's value

   iconURL

   init.iconURL's value

   name

   init.name's value

   [[origin]]

   init.origin's value.

4. Return c.