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 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 (type your handle).

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");
await IdentityProvider.register("@alice.idp.example");

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

{
  "accounts": [{
    "id": "1234",
    "name": "Alice",
    "handle": "@alice.idp.example",
    "picture": "https://idp.example/alice.jpg"
  }]
}

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

2. Federations

A federation, such as IndieAuth or atproto, is identified by an https: URL: the URL that RPs pass as federation and that IDPs list in federations. The federation operator is the party that controls the origin of that URL. It is responsible for:

• Defining the federation: the protocol or profile that its IDPs and RPs follow, including how RPs verify the tokens that IDPs issue.

• Publishing operator metadata about the federation, such as its branding, which the user agent uses in its UI (§ 6 Presentation).

The user agent doesn’t need to understand the federation’s protocol. It only reads the operator metadata.

2.1. Operator metadata

A federation operator serves its operator metadata at the path /.well-known/web-identity-federation on the origin of its federation’s URL. For the federation https://atproto.com, this is https://atproto.com/.well-known/web-identity-federation.

dictionary IdentityFederationOperatorMetadata {
  IdentityProviderBranding branding;
};

branding, of type IdentityProviderBranding

The federation’s branding, in the same format as an IDP’s branding: its name, icons, background_color, and color.

{
  "branding": {
    "name": "Atmosphere",
    "icons": [{"url": "https://atproto.com/icon.png", "size": 64}],
    "background_color": "#1185fe",
    "color": "#ffffff"
  }
}

Note: Like the config file, the operator metadata is fetched without credentials, without a referrer, and from an opaque origin, so the federation operator doesn’t learn who is asking or which RP they are visiting. User agents MAY cache it according to HTTP caching rules.

Because the operator metadata lives at a well-known path on the federation URL’s origin, one origin can operate only one federation. Should the federation URL point at the operator metadata directly instead?

2.2. Branding

A federation’s federation branding is the branding in its operator metadata, which the user agent obtains with get the federation branding. The user agent uses it to show the user which federation an RP is asking for (§ 6.3 Account selection), the same way Federated Credential Management API uses an IDP’s branding: it uses the name as the federation’s name, picks an icon from icons, and MAY use background_color and color, subject to the same contrast requirements.

Note: This addresses issue 29.

3. Handles

This specification depends on the Infra Standard. Infra Standard

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.

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.

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 site is always a site host.

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 its issuer’s metadata. It has two steps: resolve the issuer from the handle’s delegation record, and then fetch the issuer’s metadata.

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 issuer metadata: 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 by looking up a delegation record on the handle’s site. Its iss= value names the issuer’s site, whether the site hosts its own IDP or delegates to another site.

Note: When a provider’s domain is a public suffix (for example, hosting.example, where each user gets their own subdomain), each subdomain is its own site. The site of @alice.hosting.example is alice.hosting.example, not hosting.example.

3.2.2. DNS delegation record

A handle’s site names its issuer by publishing a DNS TXT record Domain names - implementation and specification at the name _web-identity. followed by the site:

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

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

The record’s value MUST be the string "iss=" followed by a site host. There MUST be exactly one such record at a name.

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.2.3. Issuer metadata

Once the issuer is known, the user agent fetches its issuer metadata: the well-known file that Federated Credential Management API already defines, an IdentityProviderWellKnown, served at https:// followed by the issuer’s site and /.well-known/web-identity. For the issuer social.example, this is https://social.example/.well-known/web-identity.

Each issuer metadata has an associated issuer, the site host it was fetched from.

{
  "provider_urls": ["https://idp.social.example/fedcm.json"]
}

The members of the issuer metadata are defined by Federated Credential Management API. This specification requires its provider_urls to contain exactly one entry: an https: URL, on the issuer’s site, of the issuer’s config file. § 6 Presentation derives the config file from it (create a registered provider).

Should the issuer metadata include an issuer member that MUST equal the site it was fetched from, as in the Email Verification Protocol (following OAuth 2.0 Authorization Server Metadata)?

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 (type your handle). 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 obtains accounts from the IDP when needed.

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 login status (and from the account registry, when supported). The login status records 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, the IDP of a registered handle is still offered, the same way Federated Credential Management API offers an IDP that the user is logged-out of, so the user can sign 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. IdP-initiated 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).

4.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 (§ 5 User-initiated Registration) 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, as named by the delegation record on the handle’s site.

Note: An IDP sets its login status to logged-in 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).

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

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

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

5. User-initiated Registration

A user whose handle isn’t in the handle registry yet can register it by typing it. The user agent decides when to allow users to type your handle, for example when an RP makes a federation request (§ 6.3 Account selection). The user agent checks that the typed handle resolves to an issuer that supports one of the federations the caller accepts, and adds it to the handle registry.

Note: Type your handle doesn’t deal with accounts or with the RP’s request. It only registers a handle. Showing the handle’s accounts and signing in with it is up to the caller (§ 6.3 Account selection).

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.

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.

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.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 or the IDP is registering.

accounts

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

offered as a choice

A flag, initially unset. It is set when the request has more than one IDP, so that the user chooses which IDP to sign in to, rather than the user agent opening the login dialog of each IDP the user is logged-out of.

Note: This is the only place where the user agent derives the issuer’s config file from its issuer metadata.

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

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’s accounts_endpoint can return other accounts (or push them via Account Registry API), but they aren’t shown on a federation request until their handles are registered.

Should other 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 and accounts once.

Note: Gather registered providers doesn’t fetch anything from the IDPs. Create an IdentityCredential fetches each registered provider’s config file and accounts like any other IDP’s.

Note: Fetch the config file checks a registered provider’s config file against the well-known file, as it does for any other IDP. The check passes as long as the well-known file hasn’t changed since resolution, because the user agent obtained the config URL from that same well-known file. The user agent can reuse the well-known file it fetched during resolution, subject to HTTP caching.

6.3. Account selection

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

• Its primary label is handle.

• If federationBranding is not null, it SHOULD show it, as described in § 2.2 Branding: for example, the federation’s icon, and its name as secondary text. Otherwise, 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. If federationBranding is not null, the user agent MAY add its icon as a badge.

The user agent MAY also use federationBranding elsewhere in the dialog, for example to title it with the federation’s name ("Sign in with your Atmosphere account"), and in the UI that allows users to type your handle.

7. Requirements on other parties

This section is non-normative.

8. Privacy considerations

• A registered IDP whose login status is logged-out receives no credentialed request before the user chooses to sign in to it. When the IDP’s login status is logged-in, the user agent fetches its accounts_endpoint as in Federated Credential Management API (unless the IDP and user agent use Account Registry API, which avoids the credentialed fetch).

• Typing a handle reveals its site to the DNS resolver and to the resolved IDP’s servers, and signing in with a handle chip sends the handle to the IDP, but nothing is revealed 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 sites 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 is global. It is used only in user agent UI, and is 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. A handle’s site is its registrable domain, just as for cookies and the FedCM well-known file. 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 site: if the site’s delegation record or the issuer’s 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 site later (for example, after the domain 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.