docs: update User Sources for configurable scopes + Advanced section (#990)

* docs: update User Sources for configurable scopes + Advanced section (GRO-166)

Follow-up to monorepo #1448 (GRO-165). Coordinator now exposes a
configurable `scopes` field on User Sources (default
`["openid", "profile", "email"]`, openid required, validated against
the IdP's `scopes_supported`); the Dashboard puts both `scopes` and
`subject_claim` into an Advanced collapsible section since the
defaults cover most setups.

User Sources overview:
- Move Subject Claim out of the primary "Fill in the User Source
  details" bullet list. Add a one-line pointer to the Advanced section.
- Replace "Pick a subject claim" with "Advanced: scopes and subject
  claim", split into two subsections. Scopes subsection notes the
  openid requirement and scopes_supported validation; subject claim
  subsection keeps the stability + uniqueness guidance and adds the
  directory-wide-identifier note for providers that expose one (Entra
  `oid` as the canonical example).

Microsoft Entra ID page:
- Rename "Allow the openid permission" -> "Grant the OIDC permissions".
  Admins now grant openid, profile, AND email. The `profile` grant is
  what unlocks `oid` later for teams that want it.
- Add a TODO note for the API-permissions screenshot — needs all three
  scopes checked, currently only openid.
- Drop the Subject Claim row from "Copy these values to Arcade".
  Replace with a pointer to the new Advanced settings section.
- Add an "Advanced settings" section that frames `sub` as the default
  with `oid` as the opt-in for cross-app correlation, calling out the
  privacy trade-off and the `profile` scope dependency.
- Update the Custom subject claims Note to reference the new overview
  anchor and drop the `oid` prescription.

Okta page:
- Drop the Subject Claim row from "Copy these values to Arcade" the
  same way; replace with a pointer to Advanced settings.
- Add an Advanced settings section noting `sub` default + Custom
  Authorization Server caveat for both fields.
- Update the Custom subject claims Note to reference the new anchor.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: tighten provider-page coverage of the Advanced section

Per Wils — say less about the Advanced section in the per-provider
pages. The overview already covers it; the only provider page where
the Advanced section is worth a callout is Entra (oid for auditing).

Okta:
- Drop the standalone "Advanced settings" section entirely. The table
  trailer now points readers to the overview's Advanced section if
  they want to customize.

Microsoft Entra ID:
- Replace the broad "Advanced settings" subsection with a focused
  "Optional: use oid as the subject claim" subsection that frames the
  switch as an auditing/correlation choice rather than a generic
  Advanced overview.
- Update the table trailer to point at the new section anchor.
- Trim the Custom subject claims Note since oid now has its own
  section heading.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: refresh Entra API permissions screenshot for all three scopes

Replace the old screenshot (only openid checked) with the new one
showing openid, profile, and email all checked — matches the new
default scope set the docs now instruct admins to grant. Remove the
TODO comment.

Same dimensions (1312 × 849) as the prior screenshot, so the page
layout is unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: tighten Entra oid section + fix broken anchor

- Rewrite the "Optional: use oid as the subject claim" paragraph to
  match the rest of the page's tone — three short paragraphs (what
  the default is, when to switch, the prerequisite) instead of one
  long comma-stacked sentence.
- Fix a broken `#advanced-settings` anchor in the OIDC permissions
  step. The Advanced settings section was replaced by the focused
  "Optional: use oid as the subject claim" section in 06a6d80;
  the link was missed in that cleanup. Re-point at the surviving
  `#optional-use-oid-as-the-subject-claim` anchor.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: drop Advanced section call-out from Okta page

Per Wils — the Advanced section isn't worth surfacing on the Okta
page since `sub` is the right pick for almost every Okta setup and
the Org Authorization Server emits the default scopes without any
admin action.

- Remove the table trailer that pointed readers at the form's
  Advanced section.
- Rewrite the Custom subject claims Note to lead with what Okta's
  `sub` actually is (the user's Okta user ID), then route admins
  who need a different value to the Custom Authorization Server
  approach.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: cut the Advanced bridge paragraph from the User Sources overview

Per Wils — the bridge to the Advanced section was unnecessary noise
between the field list and the Save step. The Advanced section already
has its own H2 below; readers who want it will find it via the TOC.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wdawson

app/en/guides/user-sources/microsoft-entra-id/page.mdx

@@ -79,16 +79,16 @@ Copy the **Value** column immediately and keep it somewhere safe—Entra hides i
 Arcade currently supports client secrets only, not certificate credentials.
 </Callout>
 
-### Allow the openid permission
+### Grant the OIDC permissions
 
 In the app's left menu, go to **API permissions**.
 
-Microsoft adds `User.Read` for you by default; leave it alone. Then click **Add a permission** → **Microsoft Graph** → **Delegated permissions** and check **openid**. Click **Add permissions**.
+Microsoft adds `User.Read` for you by default; leave it alone. Then click **Add a permission** → **Microsoft Graph** → **Delegated permissions** and check **openid**, **profile**, and **email**. Click **Add permissions**.
 
-`openid` is the only permission Arcade needs. You can optionally add `profile` and `email` if you want Entra to include those claims in the token; Arcade doesn't require them today.
+These three are the OIDC scopes Arcade requests by default. Granting `profile` is what unlocks Entra's directory-wide user identifier, which appears again in the [optional `oid` configuration](#optional-use-oid-as-the-subject-claim) below. Without `profile`, Entra omits that claim from the ID token regardless of any other configuration.
 
 <Image
-  alt="Request API permissions panel with the openid OpenID permission checked"
+  alt="Request API permissions panel with the openid, profile, and email OpenID permissions checked"
   className="max-w-full mt-4"
   src="/images/user-sources/microsoft-entra-id/entra-api-permissions-light.png"
   width={ENTRA_SCREENSHOT_WIDTH}
@@ -106,17 +106,26 @@ Open the app's **Overview** page in Entra and copy these values into Arcade's Us
 | **Issuer URL** | `https://login.microsoftonline.com/{tenant-id}/v2.0`. `{tenant-id}` is the **Directory (tenant) ID** field on the app's **Overview** page. |
 | **Client ID** | The **Application (client) ID** field on the app's **Overview** page. |
 | **Client Secret** | The value you copied earlier when you created the client secret. It is not shown anywhere after creation, so use the value you saved rather than going back to the **Overview** page for it. |
-| **Subject Claim** | Use `oid`. The default `sub` is unique per app registration, which makes it harder to trace a signed-in user back to their identity in your Entra directory. `oid` is the same identifier across your directory. It's also a better choice than `email`, because `oid` stays the same if the person's email address ever changes. |
+
+Leave Arcade's other defaults alone for a standard Entra setup. See [Optional: use `oid` as the subject claim](#optional-use-oid-as-the-subject-claim) below if you'd rather have Arcade identify users by their Entra directory ID instead of the per-app default.
 
 ## Create the User Source in Arcade
 
 Open the [User Sources dashboard](https://cloud.arcade.dev/dashboard/user-sources), click **Create User Source**, and paste the values from the table above. For a walkthrough of the form, see [Create a User Source](/guides/user-sources#create-a-user-source) in the User Sources overview.
 
 Once the User Source is active, attach it to an MCP Gateway by following [Create via Dashboard](/guides/mcp-gateways/create-via-dashboard) and picking **User Source** under "Non-Arcade Users" in the gateway form.
 
+## Optional: use `oid` as the subject claim
+
+The default Subject Claim is `sub`. Entra issues `sub` as an opaque, per-application identifier, which suits most setups.
+
+To identify users by their directory-wide identifier instead, open the form's **Advanced** section and set **Subject Claim** to `oid`. The `oid` claim makes auditing against your Entra directory more straightforward and lets you correlate the same user across multiple User Sources.
+
+Entra only emits `oid` when `profile` is in the requested scopes. You granted the `profile` permission in the step above, and `profile` belongs to Arcade's default scope set, so no further changes apply.
+
 ## Notes
 
 - **Multi-tenant and personal-account options aren't supported today**: Arcade matches the OIDC `iss` claim on every ID token byte-for-byte against the issuer URL you save on the User Source. The **Multiple Entra ID tenants**, **Any Entra ID Tenant + Personal Microsoft accounts**, and **Personal accounts only** options all rely on Entra issuing tokens whose `iss` reflects the signing-in user's home tenant, so there's no single issuer URL that will validate for users from more than one tenant. If you need to onboard users from multiple Entra tenants today, create a separate Arcade User Source per tenant.
 - **PKCE**: Arcade always uses PKCE when authenticating end users. Entra ID accepts PKCE automatically on the **Web** platform, so you don't need to change any Entra setting.
 - **Client secret rotation**: Entra client secrets expire. Rotate yours before the expiration date. See [Rotate the client secret](/guides/user-sources#rotate-the-client-secret) in the User Sources guide for how.
-- **Custom subject claims**: If you need Arcade to identify end users by a value other than `oid`, configure that value as an [optional claim](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims#configure-optional-claims-in-your-application) on Entra's ID token, then set the User Source's **Subject Claim** to its name. Arcade can read any claim that ends up in the ID token; it doesn't have access to access tokens or other token types. See [Pick a subject claim](/guides/user-sources#pick-a-subject-claim) in the User Sources overview for what makes a good claim value. In particular, avoid claims that aren't both stable and never-reused.
+- **Custom subject claims**: If neither `sub` nor `oid` fits, you can configure a different value as an [optional claim](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims#configure-optional-claims-in-your-application) on Entra's ID token, then set the User Source's **Subject Claim** to its name. Arcade only reads ID tokens, so the claim must be on the ID token specifically (not the access token). See [Advanced: scopes and subject claim](/guides/user-sources#advanced-scopes-and-subject-claim) in the overview for what makes a good claim.

app/en/guides/user-sources/okta/page.mdx

@@ -93,7 +93,6 @@ Copy these values into Arcade's User Source form:
 | **Issuer URL** | Your Okta org URL, for example `https://<your-okta-org>.okta.com`. This is the same hostname you see in the admin console URL, minus the `-admin` suffix. |
 | **Client ID** | The **Client ID** field on the app's **General** tab, **Client Credentials** panel. |
 | **Client Secret** | The Client secret value you copied earlier. The secret stays visible on the **General** tab so you can re-copy it later if needed. |
-| **Subject Claim** | Use the default, `sub`. Okta's `sub` claim is the user's stable Okta user ID. |
 
 ## Create the User Source in Arcade
 
@@ -106,4 +105,4 @@ Once the User Source is active, attach it to an MCP Gateway by following [Create
 - **Custom Okta domains**: If your org uses an Okta-hosted custom domain (for example, `auth.yourcompany.com`), use that hostname in the **Issuer URL** instead of `<your-okta-org>.okta.com`. Your end users will see the custom domain in the sign-in URL.
 - **Custom Authorization Servers**: This guide uses Okta's built-in **Org Authorization Server**, whose issuer is your Okta org URL. If your team uses a Custom Authorization Server for this app (for example, the default `oauth2/default` server, or one you've configured under **Security** → **API** → **Authorization Servers**), use that server's **Issuer URI** instead. Custom Authorization Servers are useful when you need to customize scopes, claims, or access policies.
 - **Client secret rotation**: Okta lets you generate a new client secret on the same Client Credentials panel and keep the old one active until you're ready to switch. See [Rotate the client secret](/guides/user-sources#rotate-the-client-secret) in the User Sources guide for the Arcade side.
-- **Custom subject claims**: If you need Arcade to identify end users by a value other than `sub`, configure a custom claim on a [Custom Authorization Server](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/) and set the User Source's **Subject Claim** to its name. Arcade only reads the ID token; it doesn't have access to access tokens or other token types. See [Pick a subject claim](/guides/user-sources#pick-a-subject-claim) in the User Sources overview for what makes a good claim value. In particular, avoid claims that aren't both stable and never-reused.
+- **Custom subject claims**: Arcade's default Subject Claim, `sub`, is the user's Okta user ID. If you need Arcade to identify users by a different value, configure a custom claim on a [Custom Authorization Server](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/) and set the User Source's **Subject Claim** to its name. Arcade only reads ID tokens, so the claim must be on the ID token (not the access token). See [Advanced: scopes and subject claim](/guides/user-sources#advanced-scopes-and-subject-claim) in the overview for what makes a good claim.

app/en/guides/user-sources/page.mdx

@@ -64,22 +64,33 @@ Provide the following:
 - **Issuer URL**: The OIDC issuer URL from your identity provider, for example `https://accounts.example.com`. Arcade matches this against the `iss` claim on incoming tokens, so it must exactly match what your identity provider issues.
 - **Client ID**: The client ID of the OAuth client you registered with your identity provider.
 - **Client Secret**: The matching client secret. Arcade stores it encrypted and never returns it through the API or dashboard.
-- **Subject Claim**: The JWT claim Arcade uses as the end user's stable identifier. Defaults to `sub`.
 
 ### Save the User Source
 
 Click **Create**. The new User Source appears in the list with **Active** status and is ready to attach to an MCP Gateway.
 
 </Steps>
 
-## Pick a subject claim
+## Advanced: scopes and subject claim
 
-The **Subject Claim** is the value Arcade uses to identify each of your end users on every gateway request. The right value to pick depends on your identity provider, so the per-provider guides recommend a specific claim for each. Whatever you pick must satisfy two properties:
+The User Source form's **Advanced** section exposes two settings most setups can ignore. Both have defaults that work for the providers covered by the per-provider guides. Expand the section only if you have a specific reason to change them.
+
+### Scopes
+
+**Scopes** are the OIDC scopes Arcade requests from your identity provider on every sign-in. The default is `openid profile email`, which is enough to receive an ID token and the standard profile claims most providers emit.
+
+- `openid` is always required. Arcade refuses to save a User Source without it.
+- Arcade validates the rest of the list against your provider's published `scopes_supported`, so the form catches an unrecognized scope at save time rather than letting it surface at runtime.
+- Add a provider-specific scope (for example, `groups` on Okta) when you've configured a custom claim that depends on it. See your provider's documentation for which scopes unlock which claims.
+
+### Subject claim
+
+The **Subject Claim** is the JWT claim Arcade uses to identify each of your end users on every gateway request. The default is `sub`, and it's the right pick on almost every provider. Whichever claim you choose must satisfy two properties:
 
 - **Stable per user**: the value for one person stays the same across sessions, password resets, profile edits, and so on. If the value changes, Arcade treats the returning person as a brand-new user. Arcade prompts them to authorize again, and any per-user state your agents track starts over.
 - **Unique forever**: the value is never reused for a different person. Some claim values feel unique but aren't. Email addresses and usernames are commonly reassigned, for example when a former employee leaves and a new hire with a similar name takes over the address. If a claim value gets reused, the new person inherits whatever the previous owner had access to.
 
-`sub` satisfies both properties on most providers and is a safe default unless your per-provider guide says otherwise.
+`sub` satisfies both properties on every provider Arcade has documented. Some providers also expose a directory-wide identifier (for example, Microsoft Entra ID's `oid`) that's stable across multiple app registrations in the same tenant. Pick one of those only when you specifically need to correlate the same person across multiple Arcade projects or User Sources. The per-app `sub` is otherwise more privacy-preserving.
 
 ## Use a User Source on an MCP Gateway