docs: Internet Identity authentication guide

[marc0olo]

Summary

• Full end-to-end II authentication guide: project setup, frontend login flow, backend caller verification, local development, and alternative origins
• Uses safeGetCanisterEnv() / ic_env cookie for root key handling in browser contexts — no shouldFetchRootKey or environment branching
• Clarifies Node.js vs browser distinction: fetchRootKey() is acceptable for local-only scripts, never on mainnet
• Documents both II canister IDs (backend rdmx6-... and frontend uqzsh-...), noting they are identical on local replicas with ii: true
• Covers --identity flag for CLI testing, alternative origins, common mistakes

Sync recommendation

informed by dfinity/portal — docs/building-apps/authentication/overview.mdx, docs/building-apps/authentication/integrate-internet-identity.mdx, docs/building-apps/authentication/alternative-origins.mdx; dfinity/icskills — skills/internet-identity/SKILL.md

[marc0olo]

Review: Internet Identity authentication guide

Must fix

• icp identity use does not exist (lines 247, 250): icp-cli has no use subcommand. The correct command is icp identity default <name>, or use --identity anonymous inline. E.g. icp identity default anonymous instead of icp identity use anonymous.
• Missing Unity native app integration: The stub's content brief explicitly requires "Include Unity native app integration via deep links" with native-apps/unity_ii_* as source material. The page omits this entirely. At minimum, add a <!-- TODO --> flag so it's tracked.
• some_async_operation() is undefined (line 224): The Rust async example calls a placeholder function that is not defined in the snippet. This violates the "self-contained and copy-pasteable" rule. Replace with a real canister call pattern or add a clear comment like // Replace with your actual async canister call.

Suggestions

• whoAmI should be a query: The Motoko whoAmI is an update call, but it's read-only. Adding query would be cheaper and faster: public shared query ({ caller }) func whoAmI() : async Text.
• Delegation chain depth: The brief asks to "explain the delegation chain and session management." Current coverage is high-level — a paragraph about session persistence (localStorage/IndexedDB) would help developers debug "why am I logged out" issues.
• fetch: window.fetch.bind(window) tip appears both inline and in common mistakes — consider deduplicating.
• icp-cli pulling mainnet II wasm: The claim on lines 59-60 couldn't be fully verified against .sources/. Consider adding a <!-- Needs human verification --> flag.

Verified

• All internal links resolve (../defi/wallet-integration.md, ../frontends/frameworks.md, ../../reference/internet-identity-spec.md, ../../concepts/security.md)
• No dfx references — all CLI commands use icp
• Correct Motoko core imports (mo:core/Principal, mo:core/Runtime)
• persistent actor syntax correct
• Rust ic_cdk::api::msg_caller() correct (not deprecated ic_cdk::caller())
• II canister ID rdmx6-jaaaa-aaaaa-aaadq-cai verified
• Tab order (Motoko first), syncKey="lang", no headings in TabItem — all correct
• Upstream comment present in correct JSX format
• Alternative origins section accurate (10 origin limit, .well-known/ii-alternative-origins)
• External links follow linking rules (https://js.icp.build, no old docs links)
• Build passes
• Diataxis how-to compliance confirmed

[marc0olo]

icskills was bumped to 1d125a9. The following content on this PR may be outdated:

1. Identity provider URL uses the wrong canister ID locally. The II backend/frontend split landed in icskills#130. The identity provider URL must now point to the frontend canister (uqzsh-gqaaa-aaaaq-qaada-cai), not the backend (rdmx6-jaaaa-aaaaa-aaadq-cai). For local development, the URL should be http://id.ai.localhost:8000 (not http://rdmx6-jaaaa-aaaaa-aaadq-cai.localhost:8000). The getIdentityProviderUrl() function and its surrounding explanation need updating.

2. shouldFetchRootKey: true pattern. The updated skill recommends passing the root key via the ic_env cookie (IC_ROOT_KEY) to HttpAgent.create() instead of using shouldFetchRootKey or fetchRootKey(). The PR's current approach still works, but the recommended pattern has changed — worth aligning.

3. derivationOrigin section. The new skill adds a pitfall: do NOT use derivationOrigin / ii-alternative-origins to handle icp0.io vs ic0.app — II now rewrites these automatically. If the section in this PR is showing this specific pattern, it should be removed or reframed. If it's showing a legitimate cross-origin use case (two custom domains sharing a principal), it's fine to keep with a clarifying note.

Please review before merging.

[marc0olo]

Feedback addressed:

• Fixed icp identity use → icp identity default
• Added {/* TODO */} flag for Unity native app integration
• Added clarifying comment for some_async_operation() placeholder in Rust example
• Updated identity provider URL to frontend canister (uqzsh-gqaaa-aaaaq-qaada-cai) and local URL to http://id.ai.localhost:8000
• Updated shouldFetchRootKey section with note about IC_ROOT_KEY recommended pattern
• Added clarifying note to derivationOrigin/alternative origins section: II now handles icp0.io vs ic0.app automatically; use alternative origins only for genuinely distinct custom domains
• Changed whoAmI to a query call (public shared query)
• Deduplicated fetch: window.fetch.bind(window) tip (kept in Common mistakes, removed redundant inline comment)

[marc0olo]

Review complete. All findings addressed in commit 80674b4:

Fixed:

• Replaced shouldFetchRootKey: true / verifyQuerySignatures: false in createAuthenticatedActor with safeGetCanisterEnv() pattern (rootKey: canisterEnv?.IC_ROOT_KEY) — no environment branching needed
• Removed dead II_FRONTEND_CANISTER_ID constant
• Added Node.js note: fetchRootKey() is acceptable for local scripts only, never on mainnet
• Fixed CLI test: --identity anonymous flag instead of mutating global default identity
• Mentioned both II canister IDs (backend rdmx6-... + frontend uqzsh-...); noted they are identical on local replicas with ii: true
• .ic-assets.json → .ic-assets.json5 in alternative origins section
• Rewrote "Common mistakes" shouldFetchRootKey entry with correct nuanced guidance for browser vs Node.js contexts

Verified:

• All internal links resolve; frontmatter correct; Motoko/Rust API calls verified against .sources/; CLI flags verified against .sources/icp-cli/; build passes