The whole hunk
from line 327, old and new numbered
/
lines
from line 327
327327
328328### Keys that require user consent
329329
330Some bootstrap-deliverable values point at local commands and credential files, or change where a user signs in. Examples are `inferenceCredentialHelper` and its related keys, `inferenceVertexCredentialsFile`, the AWS profile keys, and connector or marketplace entries that name a local command or helper. The app applies these values only after the user approves them.
330Some bootstrap-deliverable values point at local commands and credential files, change where a user signs in, or change where requests are sent. Examples are `inferenceCredentialHelper` and its related keys, `inferenceVertexCredentialsFile`, the AWS profile keys, the inference base URL keys, and connector or marketplace entries that name a local command or helper. The app applies these values only after the user approves them.
331331
332When a response delivers such a value for the first time, the app applies the rest of the response and then shows a dialog listing each pending value. Choosing **Allow** applies the pending values and records the approval. Until then, the pending keys are held back, and the desktop log (see [Troubleshooting](#troubleshooting)) records them as stripped pending consent. Approval is per delivered value. If the server later changes an approved value, the dialog appears again. For a `managedMcpServers` or `allowedPluginMarketplaces` entry, one approval covers the entry's executable-related fields as a unit.
332When a response delivers such a value for the first time, the app applies none of that response until the user approves it. The app opens an **Apply settings from your organization?** dialog that lists each pending value, and nothing in that response takes effect while the dialog waits. Clicking **Allow** records the approval and applies the whole response. Clicking **Quit**, pressing Esc, or closing the dialog quits the app, and it asks again the next time it opens.
333333
334Approval is per delivered value. If the server later changes an approved value, the dialog appears again. For a `managedMcpServers` or `allowedPluginMarketplaces` entry, one approval covers the entry's executable-related fields as a unit.
335
336The desktop log (see [Troubleshooting](#troubleshooting)) names the keys awaiting consent and records the user's decision. In versions earlier than 1.32352.0 that show this dialog, the app applied the rest of the response while the dialog waited and held back only the pending keys.
337
334338Whether the dialog appears depends on how `bootstrapUrl` reached the device:
335339
336340* Deployed through machine-scoped device management (`HKLM` policy on Windows, a configuration profile on macOS, `/etc/claude-desktop` on Linux): delivered values are trusted without prompting, because the admin already made a device-level decision.
from line 410
406410
407411## Troubleshooting
408412
409| Symptom | Likely cause |
410| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
411| Identity provider shows `AADSTS900144` (Entra) or `invalid_request: scope` | `bootstrapOidc.scopes` is empty. It is required. |
412| Server logs `unexpected "iss"` or `unexpected "aud"` for a valid Entra token | The app registration's accepted-token-version is at its default. Set it to `2` in the Manifest, or accept both v1 (`sts.windows.net` / `api://CLIENT_ID`) and v2 forms in your server. |
413| Sign-in succeeds in the browser but the app immediately re-prompts | Your server returned `401` or `403`. For `401`, check the `aud` match: the requested scope must produce a token whose audience your server validates. For `403`, the user authenticated but is not in the entitled group or role. |
414| Entra returns `AADSTS500011` ("resource principal not found") | The app registration has no Application ID URI. Set one under **Expose an API**. |
415| Silent refresh fails after \~1 hour with `AADSTS90009` | `scopes` uses the `api://CLIENT_ID/.default` form. Use the bare-GUID `CLIENT_ID/.default` form. |
416| Some keys you returned are not applied | They failed schema validation, are structurally excluded, were dropped by origin pinning, or are held for [user consent](#keys-that-require-user-consent). The desktop log (`~/Library/Logs/Claude-3p/main.log` on macOS, `%LOCALAPPDATA%\Claude-3p\logs\main.log` on Windows) records which keys were dropped and why. |
417| Browser opens to your identity provider's device page instead of yours | In device-code mode, `verification_uri` must share the `bootstrapUrl` origin. Federate behind your own page. |
413| Symptom | Likely cause |
414| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
415| Identity provider shows `AADSTS900144` (Entra) or `invalid_request: scope` | `bootstrapOidc.scopes` is empty. It is required. |
416| Server logs `unexpected "iss"` or `unexpected "aud"` for a valid Entra token | The app registration's accepted-token-version is at its default. Set it to `2` in the Manifest, or accept both v1 (`sts.windows.net` / `api://CLIENT_ID`) and v2 forms in your server. |
417| Sign-in succeeds in the browser but the app immediately re-prompts | Your server returned `401` or `403`. For `401`, check the `aud` match: the requested scope must produce a token whose audience your server validates. For `403`, the user authenticated but is not in the entitled group or role. |
418| Entra returns `AADSTS500011` ("resource principal not found") | The app registration has no Application ID URI. Set one under **Expose an API**. |
419| Silent refresh fails after \~1 hour with `AADSTS90009` | `scopes` uses the `api://CLIENT_ID/.default` form. Use the bare-GUID `CLIENT_ID/.default` form. |
420| Some keys you returned are not applied | They failed schema validation, are structurally excluded, or were dropped by origin pinning. If the app instead shows an **Apply settings from your organization?** dialog, the whole response is waiting for [user consent](#keys-that-require-user-consent) and none of it has been applied yet. The desktop log (`~/Library/Logs/Claude-3p/main.log` on macOS, `%LOCALAPPDATA%\Claude-3p\logs\main.log` on Windows) records which keys were dropped and why. |
421| Browser opens to your identity provider's device page instead of yours | In device-code mode, `verification_uri` must share the `bootstrapUrl` origin. Federate behind your own page. |
418422