docs: add Okta setup guide (#986)

* docs: add Okta setup guide for User Sources (GRO-95)

Second per-provider page under /guides/user-sources/, modeled on the
Microsoft Entra ID page. Walks an admin through creating an OIDC Web
Application integration in Okta, requiring PKCE, and pasting the
resulting values into Arcade's User Source form.

Includes three light-mode screenshots:
- Create a new app integration dialog (OIDC + Web Application)
- New Web App Integration form with the Arcade redirect URI
- Client Credentials panel with Require PKCE checked

Notes cover:
- Okta-hosted custom domains
- Custom Authorization Servers (the page uses the Org Authorization
  Server by default since it ships with every Okta org; custom servers
  are positioned as an advanced opt-in for teams that need custom
  scopes, claims, or policies)
- Client secret rotation
- Custom subject claims via a Custom Authorization Server

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

* 🤖 Regenerate LLMs.txt

* docs: match Okta's literal UI character in the sign-in method bullet

The radio label in the Okta admin console screenshot reads
'OIDC - OpenID Connect' with a regular hyphen, not an em-dash. Match
the literal UI character (which also satisfies the Google.EmDash
style rule).

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

* docs: explain Okta Assignments as the access-control mechanism

Per Wils — newer Okta admins won't always know that the assignment
model is how they govern which end users can sign in to a Gateway
backed by this User Source. Be explicit: anyone Okta won't let through
the assignment is blocked at sign-in.

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

* docs: add stability/uniqueness guidance for subject claims

Adds a new "Pick a subject claim" section to the User Sources overview
explaining the two properties a subject claim value must satisfy:
- Stable per user (a changing value mints a new identity in Arcade)
- Unique forever (email/username reuse can hand the new owner the
  previous person's access)

Both per-provider Custom subject claims notes (Okta and Microsoft
Entra ID) get a brief pointer to the new overview section so the
per-provider guidance stays focused on provider-specific config while
the general principles live in one place.

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

* docs: address Mateo + Bugbot review on Okta PKCE step

- Add "click **Edit**" to the Client Credentials panel instruction —
  Okta's UI requires entering edit mode before the Require PKCE
  checkbox can be toggled (Mateo).
- Add "Click **Save**." after the PKCE bullet so admins don't leave
  the change uncommitted (Mateo).
- Drop the unused `Callout` import — copy-paste leftover from the
  Entra template; the Okta page doesn't use any callouts (Bugbot).

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

app/en/guides/user-sources/_meta.tsx

@@ -7,6 +7,9 @@ export const meta: MetaRecord = {
   "microsoft-entra-id": {
     title: "Microsoft Entra ID",
   },
+  okta: {
+    title: "Okta",
+  },
 };
 
 export default meta;

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

@@ -119,4 +119,4 @@ Once the User Source is active, attach it to an MCP Gateway by following [Create
 - **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.
+- **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.

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

@@ -0,0 +1,109 @@
+---
+title: "Okta"
+description: "Use Okta as a User Source so people who already sign in with their Okta account can sign in to your MCP Gateways"
+---
+
+import Image from "next/image";
+import { Steps } from "nextra/components";
+
+export const IMAGE_SCALE_FACTOR = 1.5;
+export const OKTA_SCREENSHOT_WIDTH = 1312 / IMAGE_SCALE_FACTOR;
+export const OKTA_SCREENSHOT_HEIGHT = 1099 / IMAGE_SCALE_FACTOR;
+
+# Okta
+
+Use Okta as a User Source so the people who already sign in with their Okta account can sign in to your MCP Gateways. This guide walks you through what to do in the Okta admin console. Once you have the values it tells you to copy, [create the User Source in Arcade](/guides/user-sources#create-a-user-source).
+
+## Before you start
+
+- An Okta admin role that can create OIDC app integrations, such as **Super Admin** or **Application Administrator**.
+- An Arcade project where you'll create the User Source.
+
+## Register an app in Okta
+
+<Steps>
+
+### Open the Okta admin console
+
+Sign in to your Okta admin console (typically `https://<your-okta-org>-admin.okta.com`) with one of the roles listed above.
+
+Go to **Applications** → **Applications** → **Create App Integration**.
+
+### Choose OIDC and Web Application
+
+In the **Create a new app integration** dialog:
+
+- **Sign-in method**: **OIDC - OpenID Connect**
+- **Application type**: **Web Application**
+
+Click **Next**.
+
+<Image
+  alt="Create a new app integration dialog with OIDC and Web Application selected"
+  className="max-w-full mt-4"
+  src="/images/user-sources/okta/okta-create-app-light.png"
+  width={OKTA_SCREENSHOT_WIDTH}
+  height={OKTA_SCREENSHOT_HEIGHT}
+/>
+
+### Fill in the app settings
+
+On the **New Web App Integration** form:
+
+- **App integration name**: a name your team will recognize, for example `Arcade User Source`.
+- **Grant type**: leave **Authorization Code** checked (the default). Leave **Refresh Token** unchecked; Arcade doesn't need it.
+- **Sign-in redirect URIs**: replace the placeholder value with `https://cloud.arcade.dev/oauth2/intermediate_callback`.
+- **Sign-out redirect URIs**: leave empty.
+- **Assignments**: the users and groups you assign to this app are exactly the people who'll be able to sign in to any MCP Gateway backed by this User Source. Anyone Okta won't let through here is blocked at sign-in. Pick whichever assignment model fits how your team usually grants application access.
+
+Scroll down and click **Save**. Okta creates the app and opens its details page.
+
+<Image
+  alt="New Web App Integration form with the Arcade redirect URI filled in"
+  className="max-w-full mt-4"
+  src="/images/user-sources/okta/okta-new-web-app-form-light.png"
+  width={OKTA_SCREENSHOT_WIDTH}
+  height={OKTA_SCREENSHOT_HEIGHT}
+/>
+
+### Require PKCE and note the client credentials
+
+On the app's **General** tab, find the **Client Credentials** panel and click **Edit**.
+
+- Check **Require PKCE as additional verification**. Arcade always uses PKCE when authenticating end users; requiring it here means Okta refuses any non-PKCE flow, even by accident. Click **Save**.
+- Note the **Client ID** value.
+- Click the eye icon next to the **Client secret** value, copy it, and keep it somewhere safe. You'll paste this into Arcade as the **Client Secret**.
+
+<Image
+  alt="Client Credentials panel with Require PKCE checked and the Client ID and Client secret visible"
+  className="max-w-full mt-4"
+  src="/images/user-sources/okta/okta-client-credentials-pkce-light.png"
+  width={OKTA_SCREENSHOT_WIDTH}
+  height={OKTA_SCREENSHOT_HEIGHT}
+/>
+
+</Steps>
+
+## Copy these values to Arcade
+
+Copy these values into Arcade's User Source form:
+
+| Arcade field | Where to find it in Okta |
+|---|---|
+| **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
+
+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.
+
+## Notes
+
+- **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.

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

@@ -72,6 +72,15 @@ Click **Create**. The new User Source appears in the list with **Active** status
 
 </Steps>
 
+## Pick a 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:
+
+- **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.
+
 ## Use a User Source on an MCP Gateway
 
 You attach a User Source to an MCP Gateway when you create or edit the gateway. One User Source can back multiple gateways in the same project, so you can reuse the same end-user identity system across every gateway you build for those users.

public/images/user-sources/okta/okta-client-credentials-pkce-light.png

@@ -1,4 +1,4 @@
-<!-- git-sha: b56ac0164cc7b381c580ebf19de6e96480d189f9 generation-date: 2026-05-27T18:32:19.485Z -->
+<!-- git-sha: a34da7ac5970c7ea6f9c8bc54e74c1eb7be908cc generation-date: 2026-05-30T17:56:27.802Z -->
 
 # Arcade
 
@@ -114,6 +114,7 @@ Arcade delivers three core capabilities: Deploy agents even your security team w
 - [MCP Gateways](https://docs.arcade.dev/en/guides/mcp-gateways): The MCP Gateways documentation provides users with guidance on connecting multiple MCP servers to their agents, applications, or IDEs, enabling the federation of tools for streamlined management and access. It outlines the benefits of using MCP Gateways, including simplified configuration and customizable
 - [Microsoft Entra ID](https://docs.arcade.dev/en/guides/user-sources/microsoft-entra-id): Documentation page
 - [Migrate from toolkits to MCP servers](https://docs.arcade.dev/en/guides/create-tools/migrate-toolkits): This documentation page provides a comprehensive guide for users looking to migrate their existing Arcade toolkits to the new MCP Server framework. It outlines necessary changes in terminology, package updates, and detailed steps for updating dependencies, imports, and entrypoint files to ensure a
+- [Okta](https://docs.arcade.dev/en/guides/user-sources/okta): Documentation page
 - [On-premise MCP Servers](https://docs.arcade.dev/en/guides/deployment-hosting/on-prem): This documentation page guides users on how to deploy on-premises MCP servers within a hybrid architecture, allowing them to utilize Arcade's cloud infrastructure while maintaining control over their local environment. Users will learn to set up their MCP server, create secure tunnels for public
 - [Organize your MCP server and tools](https://docs.arcade.dev/en/guides/create-tools/tool-basics/organize-mcp-tools): This documentation page provides best practices for organizing your MCP server and tools, including how to define and import tools from separate files and other packages. Users will learn to maintain a clean project structure, enhance code readability, and effectively utilize decorators for tool management.
 - [page](https://docs.arcade.dev/en/resources/examples): This documentation page provides a collection of example applications that utilize Arcade's tools and MCP servers, showcasing various real-world scenarios and integration patterns. Users can explore complete source code and setup instructions for each example, enabling them to quickly understand and implement similar projects.