diff --git a/app/en/guides/user-sources/_meta.tsx b/app/en/guides/user-sources/_meta.tsx index d8e563d9e..1e40bc16f 100644 --- a/app/en/guides/user-sources/_meta.tsx +++ b/app/en/guides/user-sources/_meta.tsx @@ -1,5 +1,12 @@ import type { MetaRecord } from "nextra"; -export const meta: MetaRecord = {}; +export const meta: MetaRecord = { + index: { + title: "Overview", + }, + "microsoft-entra-id": { + title: "Microsoft Entra ID", + }, +}; 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 new file mode 100644 index 000000000..bf2d2fbe7 --- /dev/null +++ b/app/en/guides/user-sources/microsoft-entra-id/page.mdx @@ -0,0 +1,122 @@ +--- +title: "Microsoft Entra ID" +description: "Use Microsoft Entra ID as a User Source so people who already sign in with Microsoft work or school accounts 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 ENTRA_SCREENSHOT_WIDTH = 1312 / IMAGE_SCALE_FACTOR; +export const ENTRA_SCREENSHOT_HEIGHT = 849 / IMAGE_SCALE_FACTOR; + +# Microsoft Entra ID + +Use Microsoft Entra ID as a User Source so the people who already sign in with their Microsoft work or school account can sign in to your MCP Gateways. This guide walks you through what to do in the Microsoft Entra admin center. 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 account with one of these roles in your Microsoft Entra tenant: **Cloud Application Administrator** or **Application Administrator**. +- An Arcade project where you'll create the User Source. + +## Register an app in Microsoft Entra ID + + + +### Open the Entra admin center + +Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) with one of the roles listed above. + +Go to **Entra ID** → **App registrations** → **New registration**. + +App registrations page in the Microsoft Entra admin center, with the New registration button highlighted + +### Name the app and choose who can sign in + +Give the app a name your team will recognize, for example `Arcade MCP Gateways`. + +Under **Supported account types**, pick **Single tenant only — _your tenant name_**. This is the only account type Arcade supports today — see the [Notes](#notes) below for details on the other options. + +### Add the Arcade redirect URL + +In the **Redirect URI** section, select the **Web** platform and paste this URL: + +`https://cloud.arcade.dev/oauth2/intermediate_callback` + +Click **Register**. Entra creates the app and opens its **Overview** page. + +Register an application form with Name, Supported account types, and Redirect URI filled in + +### Create a client secret + +In the new app's left menu, go to **Certificates & secrets** → **Client secrets** → **New client secret**. + +Add a description (for example, `Arcade User Source`) and pick an expiration period. Click **Add**. + +Copy the **Value** column immediately and keep it somewhere safe—Entra hides it as soon as you leave the page. You'll paste this into Arcade as the **Client Secret**. + +Certificates and secrets page with a newly created client secret, with the Value field highlighted + + +Arcade currently supports client secrets only, not certificate credentials. + + +### Allow the openid permission + +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**. + +`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. + +Request API permissions panel with the openid OpenID permission checked + + + +## Copy these values to Arcade + +Open the app's **Overview** page in Entra and copy these values into Arcade's User Source form: + +| Arcade field | Where to find it in Entra ID | +|---|---| +| **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. | + +## 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 + +- **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. diff --git a/lib/remark-glossary.ts b/lib/remark-glossary.ts index c59cc5173..3b87950e6 100644 --- a/lib/remark-glossary.ts +++ b/lib/remark-glossary.ts @@ -34,6 +34,18 @@ export function remarkGlossary(options: RemarkGlossaryOptions) { return; } + // Don't process User Source per-provider pages — they discuss + // Microsoft, Auth0, Okta, etc. concepts (account, tenant, realm) + // that collide with Arcade glossary terms in ways that mislead + // readers. The User Sources overview itself stays opted-in. + const filePath = file.history?.[0]; + if ( + filePath?.includes("/guides/user-sources/") && + !filePath.endsWith("/guides/user-sources/page.mdx") + ) { + return; + } + // Lazy-load and cache glossary terms if (!cachedTerms || cachedGlossaryPath !== glossaryPath) { cachedTerms = sortTermsByLength(parseGlossary(glossaryPath)); diff --git a/public/images/user-sources/microsoft-entra-id/entra-api-permissions-light.png b/public/images/user-sources/microsoft-entra-id/entra-api-permissions-light.png new file mode 100644 index 000000000..4a2d0931a Binary files /dev/null and b/public/images/user-sources/microsoft-entra-id/entra-api-permissions-light.png differ diff --git a/public/images/user-sources/microsoft-entra-id/entra-app-registration-light.png b/public/images/user-sources/microsoft-entra-id/entra-app-registration-light.png new file mode 100644 index 000000000..c729c1af5 Binary files /dev/null and b/public/images/user-sources/microsoft-entra-id/entra-app-registration-light.png differ diff --git a/public/images/user-sources/microsoft-entra-id/entra-client-secret-light.png b/public/images/user-sources/microsoft-entra-id/entra-client-secret-light.png new file mode 100644 index 000000000..1f630747a Binary files /dev/null and b/public/images/user-sources/microsoft-entra-id/entra-client-secret-light.png differ diff --git a/public/images/user-sources/microsoft-entra-id/entra-registration-form-light.png b/public/images/user-sources/microsoft-entra-id/entra-registration-form-light.png new file mode 100644 index 000000000..6ac135c53 Binary files /dev/null and b/public/images/user-sources/microsoft-entra-id/entra-registration-form-light.png differ diff --git a/public/llms.txt b/public/llms.txt index df69c6d45..26525c857 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,4 +1,4 @@ - + # Arcade @@ -112,6 +112,7 @@ Arcade delivers three core capabilities: Deploy agents even your security team w - [How Hooks Work](https://docs.arcade.dev/en/guides/contextual-access/how-hooks-work): This documentation page provides a comprehensive overview of how to configure and utilize hook points within the Arcade platform, detailing the execution order, extensions, and handling of failures. Users will learn how to implement access, pre-execution, and post-execution hooks to - [In Custom Applications](https://docs.arcade.dev/en/guides/tool-calling/custom-apps): This documentation page provides guidance on integrating Arcade tools into custom applications, focusing on user authentication, authorization status checks, and retrieving tool definitions. It is designed to assist developers in creating their own tool-calling interfaces effectively. - [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 - [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. diff --git a/styles/config/vocabularies/Arcade/accept.txt b/styles/config/vocabularies/Arcade/accept.txt index 8df6d97e9..ae9fd68db 100644 --- a/styles/config/vocabularies/Arcade/accept.txt +++ b/styles/config/vocabularies/Arcade/accept.txt @@ -3,6 +3,8 @@ Arcade MCP User Source User Sources +Entra +Entra ID LLM SDK API