IdP Registration API

1. Introduction

This section is non-normative.

Today, websites that support federated sign-in pick a small number of large IDPs to show in their sign-in flows, because each one takes space and needs a separate integration. Users whose identity lives elsewhere (on a smaller provider, a custom domain, or a server they run themselves) are left out. By contrast, email verification lets any mail server take part without the website allow-listing it.

This specification lets the user agent act as an intermediary that removes the need for allow-listing:

1. After the user signs in, an IDP pushes the user’s account to the user agent (see § 4 The Account Registry) and then registers the user’s handle by calling register(), with the user’s permission.

2. An RP requests any registered IDP that supports a federation it accepts, by passing a federation instead of a configURL:

   const credential = await navigator.credentials.get({
     identity: {
       providers: [{
         federation: "https://www.w3.org/TR/indieauth/",
         params: { nonce: "..." }
       }, {
         configURL: "https://idp.example/fedcm.json",
         clientId: "123"
       }]
     }
   });
   

3. A user whose handle isn’t registered yet can type it, for example @alice.example, alice@social.example or https://alice.example. The user agent resolves it to its issuer and registers it (find your account).

Both ways of registering a handle run the same resolution and add the same handle to the handle registry.

await navigator.login.setStatus("logged-in", {
  accounts: [{
    id: "1234",
    name: "Alice",
    handle: "@alice.idp.example",
    picture: "https://idp.example/alice.jpg"
  }]
});

await IdentityProvider.register("@alice.idp.example");

{
  "id_assertion_endpoint": "/assertion",
  "login_url": "/login",
  "federations": ["https://www.w3.org/TR/indieauth/", "https://atproto.com"]
}

This specification is written as a set of monkey patches to Federated Credential Management API and Login Status API, shown like this:

2. Infrastructure

This specification depends on the Infra Standard. Infra Standard

The site of a host host is host’s registrable domain. A host host is a site host if host is a domain, its registrable domain is non-null, and host equals its registrable domain.

3. Handles

A handle is a globally-unique and human-readable string that identifies the user, that is produced by parse a handle, and that is resolvable by Resolution. A handle isn’t necessarily permanent: a user can change it, or move it to another IDP.

An issuer is an IDP that is the authority for a handle. The user agent identifies an issuer by its site, where it serves its well-known file. Each handle has exactly one issuer at a time, which Resolution finds.

This section defines how the user agent parses a handle, resolves it to its issuer, and stores the handles the user uses. None of this requires the user agent to understand any identity protocol. It only needs a small set of handle notations (§ 3.1 Parsing) and a single, protocol-agnostic resolution procedure (§ 3.2 Resolution).

3.1. Parsing

Parse a handle accepts the following notations:

Note: Because a handle is always in the canonical form that parse a handle produces, its domain can be read off directly, without validating it again.

Note: This is the only comparison used on handles. It is applied to an account’s handle, and never to its username or email, so that this mechanism stays separate from how an IDP displays accounts and from email verification.

URL handles need more normalization (fragments such as #me, trailing slashes).

3.2. Resolution

Resolution turns a handle into the config URL of its issuer.

Resolution takes a handle, not arbitrary input. Callers that start from user or script input first run parse a handle, which also normalizes it (for example, Alice.Example becomes @alice.example), and then resolve the result. Resolution stops at the config URL: it doesn’t fetch the config file or check its federations, because each caller needs a different check.

3.2.1. Resolve the issuer

The first step of resolution finds a handle’s issuer. It is based on one rule: **a handle’s issuer is on the handle’s own site, unless the handle’s domain delegates to another site in DNS.** There are three cases:

The handle’s own site hosts it

The issuer of @alice.example is on alice.example. Alice runs her own IDP, or has a provider serve the well-known file on her site for her. No DNS record is needed.

The handle’s domain delegates to another issuer site

The issuer of @alice.example is on social.example. Alice keeps her domain as her handle but uses a provider as its issuer, so she publishes a delegation record on alice.example naming social.example.

The provider assigned the handle under its own domain

The issuer of @alice.social.example and of alice@social.example is on social.example. This is really the first case: the handle’s own site is social.example, because a site is a registrable domain. No DNS record is needed.

In every case, the user agent first looks for a delegation record on the handle’s domain. If there is one, its iss= value names the issuer’s site. If there isn’t, the issuer is on the handle’s own site.

Note: When the provider’s domain is a public suffix (for example, hosting.example, where each user gets their own subdomain), each subdomain is its own site. @alice.hosting.example falls under the first case, and its issuer is on alice.hosting.example, not on hosting.example.

Should a failed DNS query (e.g. SERVFAIL) fail closed instead of falling back to the handle’s own site?

3.2.2. DNS delegation record

The owner of a handle’s domain can delegate to an issuer on another site by publishing a DNS TXT record Domain names - implementation and specification at the name _web-identity. followed by the handle’s host:

_web-identity.alice.example.   TXT   "iss=social.example"

The record’s value MUST be the string "iss=" followed by a site host. There MUST be at most one such record at a name. A record naming the handle’s own site has the same effect as having no record.

Note: This is modeled on the DNS delegation in the Email Verification Protocol. Unlike that record, the value here names a site rather than a host, so that resolution always ends at a site’s well-known file.

Should the record name be _web-identity or something more specific (e.g. _web-handle)? Should it carry a federation, so that one domain can delegate different protocols to different IDPs?

3.3. The Handle Registry

Each user agent has a global, persistent handle registry, an initially empty ordered set of handles that the user uses to sign in. No two handles in the handle registry match.

A handle is added to the handle registry in the same way whether the IDP registered it with register() or the user typed it (find your account). The user agent doesn’t record which one did.

The handle registry stores only handles. It doesn’t store which IDP a handle resolves to, that IDP’s config file, or any accounts. The user agent computes the IDP from the handle by resolving it whenever it needs it, and accounts come from the account registry.

Note: A user agent can cache the results of resolution and fetch the config file, for example to avoid DNS lookups and fetches on every federation request. That’s an implementation choice, as long as the cache respects DNS TTLs and HTTP caching, and is cleared along with the handle registry. See also § 8 Privacy considerations and § 9 Security considerations.

When the user clears browsing data or site settings for an origin origin, the user agent MUST remove from the handle registry every handle whose issuer, as determined by resolve the issuer (or by the user agent’s cached result of it), is on the same site as origin.

The user agent SHOULD let the user see the handle registry and remove handles from it (by running remove from the handle registry), for example to remove a mistyped handle.

Note: The handle registry is deliberately separate from the account registry and the login status. Those record whether the user is signed in right now, which changes silently, while the handle registry records which handles the user uses, which the user approved and which outlives their session. After the user signs out, a registered handle is still offered as a handle chip that signs the user back in. So an IDP calls setStatus("logged-out") when the user signs out, and unregister() only when the handle should no longer be offered, for example when the account is deleted.

4. The Account Registry

Accounts push is described in Lightweight FedCM but isn’t specified yet. This section defines the minimum this specification needs, and should move to Login Status API or Federated Credential Management API once accounts push is specified there.

Each user agent has a global, persistent account registry, which stores the accounts that IDPs push with setStatus(). It is an initially empty map. Its keys are origins of IDPs, and its values are account registry entries. An account registry entry is a struct with the following items:

accounts

A list of IdentityProviderAccounts.

expiration

A moment in time, or null for no expiration.

dictionary LoginStatusOptions {
  sequence<IdentityProviderAccount> accounts;
  [EnforceRange] unsigned long long expiration;
};

The user agent MUST clear account registry entries whenever it clears the corresponding Login Status map entries.

5. Registration

This section defines how an IDP registers and unregisters a user’s handle, and what it declares so that the user agent can present it to RPs later (§ 6 Presentation).

5.1. Registering a handle

partial interface IdentityProvider {
  static Promise<undefined> register(USVString handle);
  static Promise<undefined> unregister(USVString handle);
};

An IDP registering a handle and the user typing it follow the same path: both resolve it, and both add the same handle to the handle registry.

Note: An IDP can only register and unregister handles that it is the issuer of. An IDP on another site is a handle’s issuer only if the handle’s domain delegates to it with a delegation record.

Note: An IDP pushes the user’s account with setStatus() before calling register(), as in the introduction’s example. This way, an IDP can only register a handle for an account the user is signed in to, and the prompt can show that account’s name and picture.

Note: register() is separate from setStatus() because a registered handle needs to outlive the user’s session. See § 3.3 The Handle Registry.

unregister() removes the handle whether the IDP registered it or the user typed it: either way, the handle’s issuer has said it should no longer be offered. It resolves the same way whether or not the handle was in the handle registry, so that it doesn’t reveal whether the user had registered it.

Note: If a handle no longer resolves to the caller, for example because its delegation record was removed, the caller can’t unregister it. It doesn’t need to, because the handle is no longer offered with the caller as its issuer either (gather registered providers resolves it again).

5.2. Account handles

partial dictionary IdentityProviderAccount {
  USVString handle;
};

handle, of type USVString

The account’s handle, in the canonical form that parse a handle produces. The user agent uses it to match the account with registered and typed handles (find matching accounts).

Note: This is separate from username, which an IDP can use for any display name it likes. An account can have both.

5.3. Declaring supported federations

partial dictionary IdentityProviderAPIConfig {
  sequence<USVString> federations;
};

federations, of type sequence<USVString>

The federation URLs that the IDP supports. An IDP that doesn’t list a federation is never returned for a federation request for that federation.

6. Presentation

This section defines how the user agent presents registered IDPs to the user when an RP calls navigator.credentials.get() with a federation. It changes Federated Credential Management API as follows, using the algorithms defined in the subsections below.

Because resolution requires exactly one provider_urls entry, a site can register handles for only one config file. Is that acceptable for IDPs that have several configurations (e.g. one per product)?

Is the RP’s origin the right default client_id for registered IDPs? It matches how IndieAuth identifies clients by URL, but other protocols may expect something else.

Note: configURL tells the RP which IDP issued the token, so it can verify the token using the protocol named by federation.

6.1. Requesting by federation

partial dictionary IdentityProviderConfig {
  USVString federation;
};

federation, of type USVString

A URL that points to the definition of a federation the RP accepts: the protocol or profile that its IDPs and RPs follow, for example "https://www.w3.org/TR/indieauth/" or "https://atproto.com". The authority behind the URL defines the federation. When present, configURL is ignored, and the entry stands for every registered IDP whose config file lists this federation.

An IdentityProviderRequestOptions whose federation exists is a federation request.

6.2. Registered providers

A registered provider is an IdentityProviderRequestOptions that the user agent creates for the IDP of one or more handles, rather than one the RP passed. The user agent keeps the following associated with it:

config

The IdentityProviderAPIConfig from fetch the config file.

handles

A list of handles that resolve to this IDP: the ones in the handle registry, or the single handle the user typed.

accounts

A list of IdentityProviderAccounts: the pushed accounts that match one of its handles.

associated handle

The handle the user chose to sign in with, or null. Show an IDP login dialog sends it as login_hint.

Note: Only accounts whose handle is a registered handle are shown to other RPs, because those are the accounts the user agreed to (with register(), or by typing the handle). An IDP can push other accounts, but they aren’t shown on a federation request until their handles are registered.

Should other pushed accounts from a registered IDP also be shown, once the user has registered at least one handle with it?

Note: Several handles can resolve to the same IDP, for example when two users of the same IDP share a user agent. Grouping them means the user agent fetches that IDP’s config file once.

6.3. Account selection

A handle chip for a handle handle and a registered provider provider is a user agent UI element that represents an account the user hasn’t signed in to yet:

• Its primary label is handle.

• It SHOULD show the federation branding for the federation requested. If there isn’t any, it uses a generic icon.

• It MAY show the host of provider’s configURL as secondary text, so that the user knows where they’ll sign in.

An account from find matching accounts is shown the same way FedCM shows accounts. The user agent MAY add the federation branding as a badge.

Define where the federation authority publishes its branding, and in which format. [Issue #29]

7. Requirements on other parties

This section is non-normative.

8. Privacy considerations

• Registered IDPs never get a credentialed request before the user picks an account or chooses to sign in. This removes the timing attack that affects the accounts_endpoint, and the need for mismatch UI.

• Typing a handle reveals it to the DNS resolver and the resolved IDP’s servers, but not to the RP until the user finishes signing in.

• Because the handle registry stores only handles, a federation request can cause DNS lookups for the domains of the user’s registered handles, which the DNS resolver can observe. The requests don’t carry credentials or reveal the RP. User agents can reduce this by caching resolution results (see § 3.3 The Handle Registry).

• The handle registry and account registry are global. They are used only in user agent UI, and are never exposed to the RP until the user selects an account.

• The delay before rejection defined in Federated Credential Management API still applies, so an RP can’t tell whether the user has any registered IDPs.

9. Security considerations

• Resolution isn’t proof. An attacker who spoofs DNS, or controls a site’s well-known file, can make resolution end at an IDP of their choosing. That gets them the typed handle. They don’t get the user’s credentials for the real IDP, and they can’t make the RP accept a token for someone else’s handle, as long as the RP verifies the token using its protocol (for example, atproto’s two-way check between handle and DID). This is the same reasoning as the Email Verification Protocol’s analysis of DNS delegation.

• A site speaks for its subdomains. Resolve the issuer falls back to the registrable domain, just as cookies and the FedCM well-known file do. Hosts that give independent users their own subdomains need to be on the Public Suffix List to keep them separate.

• Handles that are mistyped or don’t exist still resolve to the provider. However, find matching accounts returns nothing, and the handle chip shows the handle exactly as typed.

• An account that doesn’t match isn’t used: sign in with a handle fails if the account the user signs in with doesn’t match the handle.

• Registration prompts can be abused for spam. User agents can rate-limit register(), require transient activation, and remember when the user declines.

• **A handle’s issuer can change.** Because the handle registry stores only handles, a registered handle follows its domain: if the domain’s delegation record or well-known file changes, the handle is offered with the new issuer. That is how a user moves a handle to another IDP, but it also means that whoever controls the domain later (for example, after it expires) controls the handle’s issuer. A user agent that caches resolution results MAY notice such a change and ask the user to confirm it.

• **An IDP can only register handles it is the issuer of.** register() requires the resolved config file to be same site with the caller, so a site can’t register handles whose issuer is another IDP. Similarly, unregister() only removes handles that resolve to the caller’s site.

10. Examples

This section is non-normative.

11. Acknowledgements

Many thanks to Aaron Parecki, Anders Pitman, Emelia Smith, Nicolás Peña Moreno, Dick Hardt, and the IndieWeb, Solid, atproto and Fediverse communities for their feedback on this proposal.