From 4847f481e37476d13fd7ac22ebc8cb3c3cb0b23e Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Thu, 6 Aug 2026 17:10:22 +0200 Subject: [PATCH 1/2] docs: state the CLI access prerequisite for `identity link web --app` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A user followed the `--app nns.ic0.app` / `--app oisy.com` examples, hit Internet Identity's "CLI access not enabled" screen, and concluded that the NNS dapp and OISY don't support linking. They do — the identity just needs CLI access enabled first, which the guide never mentioned. Internet Identity gates a delegation for another app's domain behind a per-identity "CLI access" setting. Linking without `--app`, where the auth provider hands icp-cli its own account, is not gated. Restructure the section so the working path leads: open with the plain `icp identity link web ` form, then a `--app` subsection that states the prerequisite before the examples rather than after them. --- docs/guides/managing-identities.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/guides/managing-identities.md b/docs/guides/managing-identities.md index c4f0b986d..af6f7393a 100644 --- a/docs/guides/managing-identities.md +++ b/docs/guides/managing-identities.md @@ -144,7 +144,23 @@ icp identity import my-identity --read-seed-phrase Sign in to a web-based authentication service and link the resulting identity into icp-cli. **Internet Identity** is one example; the icp-cli default points at [id.ai](https://id.ai), but any service that publishes a `/.well-known/cli-auth-config` for the icp-cli web-auth protocol works the same way. -With Internet Identity, every app sees a *different* principal for the same user. Linking a web-based identity means picking which app you want to sign in *as*. Pass that app's domain with `--app`: +The simplest form gives icp-cli its own account with the auth provider (id.ai uses `cli.id.ai`), and works without any further setup: + +```bash +icp identity link web my-cli-identity +``` + +This opens your browser at the auth provider's sign-in page. Once you complete sign-in, the browser hands the delegation back to icp-cli and the identity is stored locally under the chosen name. + +### Signing In As a Specific App + +With Internet Identity, every app sees a *different* principal for the same user. To get the same principal an app sees in its own UI — your NNS neurons, your OISY wallet — pass that app's domain with `--app`. + +This requires one prerequisite: **you must enable CLI access for your Internet Identity first.** Internet Identity will not hand a command-line tool a delegation for another app's domain unless you have. Until you do, the sign-in page shows *"CLI access not enabled"* and the command never receives an identity. + +To enable it, sign in at [id.ai](https://id.ai) (Internet Identity), open your identity settings, and turn on **CLI access**. The setting is stored per browser and per identity, so enable it again on any other device or browser you sign in from. + +Then link the identity: ```bash # Sign in as your NNS identity @@ -154,13 +170,7 @@ icp identity link web nns-identity --app nns.ic0.app icp identity link web oisy-identity --app oisy.com ``` -This opens your browser at the auth provider's sign-in page. Once you complete sign-in, the browser hands the delegation back to icp-cli and the identity is stored locally under the chosen name. The resulting principal matches the one the app would see in its own UI. Note that apps may use `alternativeOrigin` with II - the correct domain is `nns.ic0.app`, not `nns.internetcomputer.org`, which would give you a different principal. - -When `--app` is omitted, the auth provider picks its own default (id.ai uses `cli.id.ai`): - -```bash -icp identity link web my-cli-identity -``` +Note that apps may use `alternativeOrigin` with II - the correct domain is `nns.ic0.app`, not `nns.internetcomputer.org`, which would give you a different principal. ### Using a Different Auth Provider From b013004e47290f1b77ad93826ede18ccecf7a4c8 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Thu, 6 Aug 2026 17:19:59 +0200 Subject: [PATCH 2/2] docs: correct the `alternativeOrigin` note and the sign-in prompt `icp identity link web` rewrites `nns.internetcomputer.org` to `nns.ic0.app` (web.rs:111-119), so the old warning that the former "would give you a different principal" described an outcome users cannot observe through this CLI. Keep the general `alternativeOrigin` caution, which does hold for other apps, and document the NNS rewrite as the alias it is. Also note that the command waits for Enter before opening the browser, which the previous wording skipped. --- docs/guides/managing-identities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/managing-identities.md b/docs/guides/managing-identities.md index af6f7393a..1237cc09b 100644 --- a/docs/guides/managing-identities.md +++ b/docs/guides/managing-identities.md @@ -150,7 +150,7 @@ The simplest form gives icp-cli its own account with the auth provider (id.ai us icp identity link web my-cli-identity ``` -This opens your browser at the auth provider's sign-in page. Once you complete sign-in, the browser hands the delegation back to icp-cli and the identity is stored locally under the chosen name. +This prints the sign-in URL and waits for you to press Enter, then opens your browser at the auth provider's sign-in page. Once you complete sign-in, the browser hands the delegation back to icp-cli and the identity is stored locally under the chosen name. ### Signing In As a Specific App @@ -170,7 +170,7 @@ icp identity link web nns-identity --app nns.ic0.app icp identity link web oisy-identity --app oisy.com ``` -Note that apps may use `alternativeOrigin` with II - the correct domain is `nns.ic0.app`, not `nns.internetcomputer.org`, which would give you a different principal. +Some apps use II's `alternativeOrigin` mechanism, so the domain Internet Identity knows them by is not the one in your address bar — passing the wrong one links a different principal. `--app` needs the II origin. NNS is the common case: its II origin is `nns.ic0.app`, and icp-cli maps `nns.internetcomputer.org` onto it for you, so either spelling links the same identity. ### Using a Different Auth Provider