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 belongs to a federation it accepts, by passing a federation instead of a configURL:

   const credential = await navigator.credentials.get({
     identity: {
       providers: [{
         federation: "https://atproto.com",
         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. 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.

This specification builds on the Handle Verification Protocol Handle Verification Protocol, which defines what a handle is, how it is resolved to the issuer that the user has authorized to vouch for it, and how the user agent obtains from that issuer a proof that the user controls the handle, an HVT+KB, which the RP verifies. The issuer doesn’t learn which RP the user signs in to.

await navigator.login.setStatus("logged-in");
await IdentityProvider.register("@alice.example");

{
  "issuer": "https://social.example",
  "issuance_endpoint": "https://social.example/hvp/issuance",
  "jwks_uri": "https://social.example/hvp/jwks",
  "federations": ["https://atproto.com"]
}

{
  "accounts_endpoint": "/accounts",
  "login_url": "/login"
}

{
  "accounts": [{
    "id": "1234",
    "name": "Alice",
    "handle": "@alice.example",
    "picture": "https://social.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 atproto, is identified by an https: URL: the URL that RPs pass as federation and that issuers list in the federations member of their issuer metadata. The federation operator is the party that controls the origin of that URL. It is responsible for:

• Defining the federation: which accounts belong to it, and what RPs can do with them beyond verifying that the user controls their handle. How RPs verify that is defined by Handle Verification Protocol, and is the same for every federation.

• 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. It only reads the operator metadata, and matches the federation URL with the federations of issuers.

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. The Handle Registry

This specification depends on the Infra Standard. Infra Standard

Handle Verification Protocol defines the handles that the user agent remembers, how they are parsed and resolved, and the issuer metadata of the IDPs that issue them. This specification uses the following terms for them:

• A handle is an HVP handle: a domain handle, such as @alice.example, in its HVP normalized form. The user agent displays it with a leading @. A handle isn’t necessarily permanent: a user can change it, or move it to another IDP.

• An issuer is the IDP that is the authorized issuer of a handle, identified by its HVP issuer identifier, an https: origin.

• To parse a handle given a string input, run the steps of HVP parsing on input, and return the resulting handle, or failure if they fail.

• Two strings match as handles if parsing each of them succeeds and produces the same handle. This is the only comparison used on handles. It is applied to an account’s handle, and never to its username or email.

• The issuer metadata of an issuer is its HVP issuer metadata, served at its HVP issuer identifier followed by /.well-known/handle-verification. It lists the federations that the issuer’s accounts belong to in its federations member, and the endpoint that issues HVTs in its issuance_endpoint member. To fetch the issuer metadata of an issuer, the user agent fetches and checks it as defined by Handle Verification Protocol, without credentials, without a referrer, and from an opaque origin.

• Resolution runs HVP resolution on a handle, and produces a resolution result or failure. A resolution result has the following items:

  issuer

  The HVP issuer identifier of the handle’s issuer.

  unique user identifier

  The unique user identifier that the handle resolves to: a DID.

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 issuer metadata, 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 the documents that create a registered provider fetches, for example to avoid lookups and fetches on every federation request. That’s an implementation choice, as long as the cache respects DNS TTLs and HTTP caching, follows the caching rules of Handle Verification Protocol, 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 a handle (or by the user agent’s cached result of it), is same site with 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 records that HVP resolution reads: the HandleVerification service of the handle’s DID document.

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 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 DID document no longer names the caller as its issuer, 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, for example "@alice.example". The user agent uses it to match the account with registered and typed handles (find matching accounts), and uses it in the HVT request (§ 6.4 Issuing the HVT+KB).

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

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 belongs to 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, and what the RP receives.

6.1. Requesting by federation

partial dictionary IdentityProviderConfig {
  USVString federation;
};

federation, of type USVString

A URL that identifies a federation the RP accepts, for example "https://atproto.com". When present, configURL is ignored, and the entry stands for every registered issuer whose issuer metadata lists this federation in its federations.

An IdentityProviderRequestOptions whose federation exists is a federation request. The RP passes the nonce that the HVT+KB is bound to as its nonce.

6.2. Registered providers

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

issuer

The HVP issuer identifier of its issuer.

issuer metadata

The issuer’s issuer metadata, from fetch the issuer metadata.

config

The issuer’s IdentityProviderAPIConfig, from fetch the issuer config. It has only an accounts_endpoint and a login_url.

handles

A list of handles that resolve to this issuer: 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.

To show the user’s accounts and to let the user sign in, the user agent needs the issuer’s accounts_endpoint and login_url. It reads them from the well-known file of Federated Credential Management API on the issuer’s site, rather than from a config file: a registered provider has no config URL.

{
  "accounts_endpoint": "/accounts",
  "login_url": "/login"
}

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 issuer, for example when two users of the same IDP share a user agent. Grouping them means the user agent fetches that issuer’s issuer metadata and accounts once.

Note: Gather registered providers fetches each issuer’s issuer metadata and well-known file, without credentials, but not its accounts. Create an IdentityCredential then fetches each registered provider’s accounts like any other IDP’s: the user agent checks its login status, fetches its accounts (keeping only the accounts that match its handles), and shows the same UI as Federated Credential Management API does when the user is logged-out or when no account matches.

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, displayed with a leading @.

• 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 issuer 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.

6.4. Issuing the HVT+KB

When the user selects an account of a registered provider, the RP receives an HVT+KB Handle Verification Protocol, rather than the token of Federated Credential Management API’s id_assertion_endpoint. The user agent obtains an HVT from the issuer with an HVT request, which doesn’t reveal the RP to the issuer, and binds it to the RP itself.

Note: The RP verifies the HVT+KB as described in HVT+KB verification, including resolving the handle itself. The verification is the same whichever federation the RP asked for. The sub claim of the HVT carries the user’s unique user identifier, which the RP uses to identify the account.

7. Requirements on other parties

This section is non-normative.

8. Privacy considerations

• Unlike Federated Credential Management API’s id_assertion_endpoint, the HVT request doesn’t reveal the RP to the issuer: the user agent binds the HVT to the RP’s origin and nonce itself, in the KB-JWT, as described in Handle Verification Protocol.

• 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 it to the DNS resolver and to the servers involved in its HVP resolution, 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 HVP resolution of the user’s registered handles, which the DNS resolver and the servers involved can observe. The requests don’t carry credentials or reveal the RP. User agents can reduce this by caching resolution results (see § 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.

See also the privacy considerations of Handle Verification Protocol.

9. Security considerations

• Resolution isn’t proof, verification is. An attacker who manipulates the user agent’s resolution can make it 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 an HVT+KB for someone else’s handle, because the RP resolves the handle itself during HVT+KB verification. See the security considerations of Handle Verification Protocol.

• Handles that are mistyped or don’t exist either fail to resolve, or resolve to a provider that has no matching account: 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, and the issuer doesn’t issue an HVT for a handle that the signed-in user doesn’t control.

• 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 the records that HVP resolution reads: if they change, 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 handle’s domain 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 caller to be on the issuer’s site of the handle’s resolution result, 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.