diff --git a/app/en/guides/user-sources/_meta.tsx b/app/en/guides/user-sources/_meta.tsx index 1e40bc16f..c2949ed00 100644 --- a/app/en/guides/user-sources/_meta.tsx +++ b/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; diff --git a/app/en/guides/user-sources/microsoft-entra-id/page.mdx b/app/en/guides/user-sources/microsoft-entra-id/page.mdx index bf2d2fbe7..7950ef894 100644 --- a/app/en/guides/user-sources/microsoft-entra-id/page.mdx +++ b/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. diff --git a/app/en/guides/user-sources/okta/page.mdx b/app/en/guides/user-sources/okta/page.mdx new file mode 100644 index 000000000..110b8beaf --- /dev/null +++ b/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 { Callout, 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 + + + +### Open the Okta admin console + +Sign in to your Okta admin console (typically `https://-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**. + +Create a new app integration dialog with OIDC and Web Application selected + +### 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. + +New Web App Integration form with the Arcade redirect URI filled in + +### Require PKCE and note the client credentials + +On the app's **General** tab, find the **Client Credentials** panel. + +- 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. +- 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**. + +Client Credentials panel with Require PKCE checked and the Client ID and Client secret visible + + + +## 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://.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 `.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. diff --git a/app/en/guides/user-sources/page.mdx b/app/en/guides/user-sources/page.mdx index 57fde038a..6499c1554 100644 --- a/app/en/guides/user-sources/page.mdx +++ b/app/en/guides/user-sources/page.mdx @@ -72,6 +72,15 @@ Click **Create**. The new User Source appears in the list with **Active** status +## 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. diff --git a/public/images/user-sources/okta/okta-client-credentials-pkce-light.png b/public/images/user-sources/okta/okta-client-credentials-pkce-light.png new file mode 100644 index 000000000..535d3cb00 Binary files /dev/null and b/public/images/user-sources/okta/okta-client-credentials-pkce-light.png differ diff --git a/public/images/user-sources/okta/okta-create-app-light.png b/public/images/user-sources/okta/okta-create-app-light.png new file mode 100644 index 000000000..7e547e459 Binary files /dev/null and b/public/images/user-sources/okta/okta-create-app-light.png differ diff --git a/public/images/user-sources/okta/okta-new-web-app-form-light.png b/public/images/user-sources/okta/okta-new-web-app-form-light.png new file mode 100644 index 000000000..22bb38b39 Binary files /dev/null and b/public/images/user-sources/okta/okta-new-web-app-form-light.png differ diff --git a/public/llms.txt b/public/llms.txt index 26525c857..c0cc9890c 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,4 +1,4 @@ - + # 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.