docs: state the CLI access prerequisite for identity link web --app - #695
Merged
Conversation
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 <name>` form, then a `--app` subsection that states the prerequisite before the examples rather than after them.
Contributor
There was a problem hiding this comment.
Pull request overview
Clarifies the prerequisite for linking an Internet Identity as a specific app.
Changes:
- Leads with the setup-free linking flow.
- Documents enabling per-browser, per-identity CLI access before using
--app. - Relocates app-specific examples and
alternativeOriginguidance.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
`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.
lwshang
approved these changes
Aug 6, 2026
marc0olo
added a commit
that referenced
this pull request
Aug 6, 2026
…#695) * docs: state the CLI access prerequisite for `identity link web --app` 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 <name>` form, then a `--app` subsection that states the prerequisite before the examples rather than after them. * 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
We received this feedback on
icp identity link web:Both examples are supported. Internet Identity gates a delegation for another app's domain behind a per-identity CLI access setting, and without it the sign-in page shows "CLI access not enabled". Our guide never mentioned the prerequisite, so the screen reads as a capability limitation rather than a setting the user can flip.
The gate applies specifically to
--app. Linking without it — where II hands icp-cli its own account atcli.id.ai— is not gated, which is why the plain example works and the two documented ones don't.Changes
Restructures Linking a Web-Based Identity in the identity guide so the working path leads:
icp identity link web <name>, flagged as working without further setup.--app, stating the CLI access prerequisite before the examples: what the failure looks like, how to fix it (sign in at id.ai → identity settings → CLI access), and that the setting is per browser and per identity.alternativeOrigin/nns.ic0.appnote, now attached to the--appsection where it applies.Docs only, no behavior change.
For discussion: the CLI still hangs silently
Worth raising separately, because docs only help people who read them before running the command — the reporter was looking at a spinner.
When II reaches its
cli-disabledstate it renders that screen and stops there, without posting anything back to our loopback callback — the POST happens only on the path past the gate.recv_delegationhas no timeout, so the CLI sits on⠹ Linking web-based identityindefinitely: no error, no exit, nothing to check. That silent hang is arguably the worse half of the reported experience.I have a small change ready that prints an actionable hint after ~30s of waiting when
--appis set, naming CLI access as the likely cause. Held back from this PR pending the II conversation below — happy to open it as a follow-up if people want it.We asked the II team whether the
cli-disabledscreen could grant access inline and continue to the delegation in the same request. Answer: no, independently granting access was a deliberate security decision — requiring an out-of-band act is anti-social-engineering, since otherwise a malicious local CLI could present the enable prompt at exactly the moment a user is primed to approve it. Reasonable, and we're not pushing back on it.Two asks that the security rationale does not cover, still open with them:
error=cli-disabledplus the nonce to the loopback URL. Grants nothing and reveals nothing new (the page already holds the nonce), but it would let us print a real error and exit non-zero instead of hanging. It also covers self-hosted--authproviders. This would need a small change on our side too:delegationis currently a required form field, so a delegation-less POST 422s.Neither changes what's in this PR. Flagging in case anyone has an opinion on the hint, or wants to weigh in on the asks before we follow up with II.