docs: split the Internet Identity guide and add Enterprise SSO

[sea-snake]

Summary

The Authentication section becomes a set of focused pages, and gains a guide for SSO administrators.

• Getting started (guides/authentication/internet-identity.mdx, URL unchanged): what Internet Identity is, install, sign in and sign out, rendering on the sign-in status, calling the backend as the user, rejecting anonymous callers, and local development.
• App metadata (new): publishing /.well-known/ii-app-metadata and serving it with CORS. The validation rules link to the Internet Identity specification instead of being copied.
• Identity attributes (new): the available keys, openid: and sso: scoped keys, requesting attributes with the sign-in, and verifying them in Motoko (mo:identity-attributes) and Rust.
• One-click sign-in (new): openIdProvider and ssoDomain, and checking an organization domain the user typed with getSsoStatus(), subscribe(), and refreshSsoStatus().
• Enterprise SSO (new): the administrator's guide to registering an OIDC client, publishing /.well-known/ii-openid-configuration, gating access per app, the limits that reject the whole file, and when a change applies.
• Shared sessions across subdomains (new): one derivation origin with ii-alternative-origins, then sharing one sign-in across sibling subdomains, including /.well-known/ii-auth-callbacks.
• Verifiable credentials is hidden from the sidebar; the page stays published.

Structural decisions

• The section is flat and ordered by sidebar.order; sidebar.mjs is unchanged.
• These pages become the guides for Internet Identity integration. The @icp-sdk/auth docs on js.icp.build keep installation, a quick start, and the API reference, and link here for guides (the shared-sessions and one-click pages there move here).
• Links into moved sections (#alternative-origins, #frontend-integration, #create-an-authenticated-agent) point at their new pages.

Describes

This documents the behavior of these changes:

• refactor(be): keep only what verification reads in the SSO caches internet-identity#4413 (merged): the limits on the SSO discovery file.
• feat(be,fe): keep SSO discovery results for a week, fetch keys during sign-in internet-identity#4414 (merged): how long a discovery result is cached and refreshed.
• feat(be,fe): report a failed SSO discovery, and an app-facing domain status internet-identity#4421 and feat!: check an SSO domain with Internet Identity, as client state icp-js-auth#203: getSsoStatus() and refreshSsoStatus(), and Internet Identity resolving an organization domain without a browser fetch (so ii-openid-configuration needs no CORS header).

Verified

• npm run build passes (223 pages); the Authentication sidebar renders in the intended order and without Verifiable credentials.
• node scripts/validate.js passes on every changed file; every internal link and anchor resolves.
• The Rust attribute-verification snippet compiles for wasm32-unknown-unknown against ic-cdk 0.20.3 and ic-cdk-management-canister.
• Library behavior against @icp-sdk/auth sources, II limits and caching against the II sources, and mo:identity-attributes against its README.

[github-actions]

🤖 Here's your preview: https://z4vwg-raaaa-aaaam-aiiga-cai.icp0.io

[Copilot]

Pull request overview

Adds administrator-facing documentation for configuring Internet Identity single sign-on (SSO) via an organization’s OpenID Connect provider, and updates the existing Internet Identity guide with the corresponding application-side integration details. Also adjusts sidebar ordering so the new guide sits next to the existing authentication docs.

Changes:

• Added a new SSO guide covering OIDC client setup, the /.well-known/ii-openid-configuration discovery file, per-app access control, and troubleshooting.
• Updated the Internet Identity guide with ssoDomain usage, isValidSsoDomain, and SSO-scoped attribute key examples.
• Moved “Verifiable credentials” down one slot in the Authentication sidebar order.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/guides/authentication/verifiable-credentials.md	Updates sidebar ordering to make room for the new SSO guide.
docs/guides/authentication/single-sign-on.md	New administrator-focused SSO setup guide (OIDC client + discovery file + optional per-app access control).
docs/guides/authentication/internet-identity.mdx	Adds application-side “one-click SSO sign-in” and SSO-scoped attribute documentation, plus Next steps link.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (4)

docs/guides/authentication/internet-identity.mdx:161

• The docs assert a precise timing guarantee ("never resolves in under 750 ms"). That kind of implementation detail is brittle and can become incorrect across SDK versions. Consider describing the behavior without hard-coding a minimum duration.

Call `controller.abort()` when the input changes. An aborted check rejects instead of returning `false`, so a superseded check is never read as an invalid domain. The check also never resolves in under 750 ms, which keeps a partially typed domain from flashing an error on every keystroke.

docs/guides/authentication/single-sign-on.md:22

• The navigation path "Create App Integration → OIDC → Web Application" is Okta-specific UI wording, but the guide is written as if it applies to any IdP. Consider making the instruction generic and optionally calling out Okta as an example so Entra/other IdPs aren’t misled.

Create App Integration → **OIDC** → **Web Application**.

docs/guides/authentication/internet-identity.mdx:134

• This sentence says nothing has to be registered on either side, but the SSO flow still requires the organization to register an OIDC client in its IdP. Reword to avoid contradicting the new SSO admin guide and to clarify that it’s the application that does not need a client registration with the org’s IdP.

To send the user to their organization's own OpenID provider instead, pass `ssoDomain` with the organization's domain. Internet Identity resolves the provider from a configuration file the organization publishes on that domain, so nothing has to be registered on either side:

docs/guides/authentication/internet-identity.mdx:148

• This snippet creates a new AuthClient, but only imports isValidSsoDomain. Readers copying the snippet will hit a missing import for AuthClient; either include it here or remove the import line entirely.

import { isValidSsoDomain } from "@icp-sdk/auth/client";

[marc0olo]

Review: Enterprise SSO

Verified against .sources/internetidentity at release-2026-08-07 (c78d1b99), the pin main picked up in #341.

Must fix

• Sidebar order collision: the new page sets order: 2, and docs/guides/authentication/verifiable-credentials.md already uses order: 2. The PR description claims VC moves to order: 3, but the diff never touches it. Bump VC to 3.

• Config changes are not immediate, and the page never says so: discovery entries cache for one hour (FRESH_FOR_SECONDS, sso.rs:72), with another hour of stale-if-error fallback (STALE_FOR_SECONDS, sso.rs:75). On a page whose central promise is gating access app by app, an admin will assume that removing an app_clients entry revokes access at once. It can take up to an hour, or two if a refetch fails. This belongs in step 3.

• A gated app cannot be a user's first sign-in: resolve_gated_ii_client_sub returns None (surfacing as NoSuchAnchor) unless an identity was already established through the org's II client on that domain. sso_gating.rs:163 says it outright: "sign in normally first." A new employee sent straight to a gated app fails, with no explanation in this guide.

• Out-of-bounds values reject the whole file, not just the field: more than 100 app_clients entries (MAX_APP_CLIENTS, sso.rs:48, rejected rather than truncated, deliberately), a session_max_age_seconds of 0 or above 2592000, or a file over 64 KiB (DISCOVERY_MAX_RESPONSE_BYTES, sso.rs:94) all make validate_ii_config fail, which takes SSO down for the entire domain. The guide presents the 30-day figure as a ceiling, which reads as "it clamps." It does not. One sentence per limit, plus the 100-entry cap, which is not mentioned at all.

• PR description does not match the PR: it names the file single-sign-on.md (it is enterprise-sso.md), claims a Verifiable credentials reorder that is absent, and states that internet-identity is not among the .sources/ submodules when .sources/internetidentity exists and is pinned. It also carries an AI attribution line, which the repo rules ban.

Suggestions

• Say what a domain may look like: validate_discovery_domain (sso.rs:378) requires a bare authority that round-trips exactly through the URL parser (is_bare_authority, sso.rs:400), so https://acme.com, acme.com/, and Acme.com are all rejected. The guide says "enter acme.com" without signalling that this is a constraint rather than a formatting choice.

• app_clients keys are exact origins: matching is byte-equality against the app's origin, so a trailing slash, a path, or a scheme mismatch silently falls through to the org-wide client. The failure is invisible, so it deserves a line.

• Explain why the CORS header is needed: Access-Control-Allow-Origin: * matters only for the client-side pre-check. The canister fetches the file via HTTPS outcalls and is unaffected. As written, an admin may believe SSO breaks without it.

• Caution on changing stable_identifier_claim later: it changes how identities key onto anchors, so flipping it on a live domain is a migration, not a config tweak. Worth confirming the intended behaviour before wording it.

• Anchor the cross-link: Next steps points at internet-identity.md bare. internet-identity.md#one-click-sso-sign-in lands on the half that answers "how do applications send users into this flow."

• Numbering vs the intro: "Setup is two steps" followed by headings 1., 2., 3. reads slightly against itself. "Two required steps, plus an optional third" would remove the stumble.

Verified

• Neither file is on a sync path. sync-ii-spec.yml writes only docs/references/internet-identity-spec.md, docs/references/verifiable-credentials-spec.md, and public/references/internet-identity.did.
• Field names, defaults, and semantics against sso.rs and sso_gating.rs: client_id, openid_configuration, name (falls back to the domain), app_clients, gate_all_apps, stable_identifier_claim (default sub), session_max_age_seconds (default 8h via DEFAULT_SESSION_MAX_AGE_NS, ceiling delegation::MAX_EXPIRATION_PERIOD_NS = 30 days).
• The salted-hash recipe: sha256(origin || salt) with the salt hashed as its hex string, keyed as <hex>:<hex>, cleartext and hashed keys mixable in one file. The shell snippet produces exactly what AppClientKey::parse accepts.
• OIDC client settings: response_type=code id_token with response_mode=form_post, no access token, redirect https://id.ai/callback, default scopes openid/profile/email.
• sso:<domain>:<key> attribute keys, and that verified_email is deliberately unavailable under sso: (attributes.rs:468), matching the page's reasoning.
• session_max_age_seconds is live on mainnet: proposal 143403 executed 2026-08-10, module f6c0abac... = release-2026-08-07.
• Style rules: no em-dashes, no dfx, no mo:base, no absolute internal links, .md extensions, complete frontmatter, ## Next steps present. All three links resolve.

One release-state note

The internet-identity.mdx additions (ssoDomain, isValidSsoDomain, scopedKeys({ ssoDomain })) come from dfinity/icp-js-auth#141, which is still open. The latest published @icp-sdk/auth is 8.0.3 and exposes none of them: scopedKeys accepts only openIdProvider. The canister half of this PR is fully live, so that section is the only part gated on an external release.

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical security and reliability issues, plus multiple moderate documentation issues, remain unresolved.

Review effort: Lite
Findings: 2 · 4

Open (6)

• Prevent unauthorized access to other users' profiles · New
• Bound and expire pending nonces to prevent memory exhaustion · New
• Label provider-specific OIDC navigation or provide equivalent steps · New
• Configure the nonce actor for the backend's environment · New
• Pass the environment-specific host when creating HttpAgent · New
• Instantiate authClient before subscribing on the open page · New

[Copilot]

Copilot review overview

🟡 Changes recommended

A critical authorization flaw and several unresolved correctness, resource-management, and setup issues remain.

Review effort: Lite
Findings: 1

Open (1)

• Prevent unauthorized access to stored profiles · New

Resolved since last review (6)

• Bound and expire pending nonces to prevent memory exhaustion
• Prevent unauthorized access to other users' profiles
• Instantiate authClient before subscribing on the open page
• Pass the environment-specific host when creating HttpAgent
• Configure the nonce actor for the backend's environment
• Label provider-specific OIDC navigation or provide equivalent steps

Previously missed (1)

In code that hasn't changed since last review

Dispose or reuse the temporary AuthClient

docs/​guides/​authentication/​shared-sessions.md:141

This creates an AuthClient solely to read the status and then loses the instance. The guide states that each client installs listeners and schedules delegation refreshes, so every page that is not redirected leaks those resources for the lifetime of the page; use the page's existing client or dispose this temporary client when no redirect is needed.

[sea-snake]

On the item Copilot lists under "previously missed" (shared-sessions.md, a client created only to read the status): fixed in fdc5052. The page-load snippet now creates the page's own authClient, and the open-page snippet subscribes on that same client.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical and moderate correctness issues must be addressed before approval.

Review effort: Lite
Findings: 1

Open (1)

• Rust verifier lacks trusted SSO domain validation · New

Resolved since last review (1)

• Prevent unauthorized access to stored profiles

Previously missed (1)

In code that hasn't changed since last review

Incorrectly treats icp.net as equivalent to ic0.app

docs/​guides/​authentication/​shared-sessions.md:14

The Internet Identity specification only normalizes the icp0.io gateway to ic0.app; it does not make icp.net automatically equivalent. Treating all three as sharing a principal can cause users to skip alternative-origin configuration and receive different principals when moving between icp.net and ic0.app. Clarify the gateway exception and direct readers to configure alternative origins for other gateway origins.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Moderate documentation issues remain around certified alternative-origin hosting, legacy redirects, gateway behavior, and Enterprise SSO fallback.

Review effort: Lite
Findings: None

Resolved since last review (1)

• Rust verifier lacks trusted SSO domain validation

Previously missed (1)

In code that hasn't changed since last review

Fix grammatical omissions in OpenID provider sentence

docs/​guides/​authentication/​identity-attributes.mdx:18

This sentence has a grammatical omission: “one an OpenID provider” and “one the user linked” should both be “one that ...”.

[sea-snake]

On Copilot's latest overview: the verified_email row now reads "one that an OpenID provider ... or one that the user linked", in 15015f9.

[sea-snake]

getProfile takes a principal again, in 3035554: it is a public profile lookup, so reading another user's profile is what it is for. The Rust tab now uses the identity-attributes crate with the same lookup.