From 4f3bf844c20000e2df37c925e52fe9e366cecf1f Mon Sep 17 00:00:00 2001 From: ritam77 Date: Tue, 12 May 2026 13:57:23 +0530 Subject: [PATCH 1/2] Add AuthSec to MCP-compatible provider list AuthSec passes the MCP compatibility test at https://prod.api.authsec.ai/authsec/oauth/.well-known/oauth-authorization-server (5 successes, 1 warning for DCR). Co-Authored-By: Claude Opus 4.7 (1M context) --- src/pages/provider-list.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/pages/provider-list.mdx b/src/pages/provider-list.mdx index 248e1a0..6e25d00 100644 --- a/src/pages/provider-list.mdx +++ b/src/pages/provider-list.mdx @@ -16,6 +16,7 @@ This list contains providers that have been tested with MCP Auth. | [WSO2 Identity Server](https://wso2.com/identity-server/) | OpenID Connect | ✅ | ✅ | ✅ | ❌ | | [Auth0](https://www.auth0.com) | OpenID Connect | ✅ | ✅ | ✅ | ⚠️[^4] | | [Descope](https://www.descope.com) | OpenID Connect | ✅ | ✅ | ✅ | ⚠️[^4] | +| [AuthSec](https://authsec.ai) | OpenID Connect | ✅ | ✅ | ❌[^5] | ✅ | If you have tested MCP Auth with another provider, please feel free to submit a pull request to add it to the list. @@ -27,6 +28,8 @@ If you have tested MCP Auth with another provider, please feel free to submit a [^4]: Auth0 and Descope support multi-resource refresh tokens (MRRT) but not full RFC 8707. Resource indicator support is limited and not standards-based. +[^5]: AuthSec is shipping RFC 7591 Dynamic Client Registration in an upcoming release. The current discovery document intentionally omits `registration_endpoint` until the public DCR handler is live, rather than advertising an auth-gated endpoint that MCP clients cannot use. + ## Is Dynamic Client Registration required? {#is-dcr-required} [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) is not required for MCP servers and MCP Auth. In fact, you can choose the approach that best suits your needs: From bbc5e4bfebb9d68e8cc27a961ea83b8520bc8bef Mon Sep 17 00:00:00 2001 From: ritam77 Date: Tue, 12 May 2026 14:08:55 +0530 Subject: [PATCH 2/2] Add AuthSec provider guide Mirrors the structure of the Logto and Keycloak guides. Covers: - Issuer URL (clarifies AuthSec's SPIRE-federation vs user-facing OAuth endpoints) - Configuring scopes - Retrieving user identity (incl. tenant_id and spiffe_id claims) - RFC 8707 resource indicator usage - Manually registering an MCP client (first-party vs third-party) - AuthSec's delegate-svid endpoint for agent-on-behalf-of-user flows Registers the new page in sidebars.ts under Provider Guides. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/provider-guides/authsec.mdx | 117 +++++++++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 118 insertions(+) create mode 100644 docs/provider-guides/authsec.mdx diff --git a/docs/provider-guides/authsec.mdx b/docs/provider-guides/authsec.mdx new file mode 100644 index 0000000..0b8b1d4 --- /dev/null +++ b/docs/provider-guides/authsec.mdx @@ -0,0 +1,117 @@ +--- +sidebar_position: 3 +sidebar_label: AuthSec +--- + +# AuthSec + +[AuthSec](https://authsec.ai) is an open-source, agent-first identity layer for autonomous AI. It ships OAuth 2.1, SPIFFE/mTLS, RBAC, MFA WebAuthn, MCP Server authentication, and Voice Agent authentication — designed for the case where the principal holding credentials is an agent, not a human. + +This guide covers configuring AuthSec as the authorization server for an MCP server. + +## Get issuer URL {#get-issuer-url} + +AuthSec exposes two `/.well-known` documents on the same host: + +| Path | Purpose | +| ------------------------------------------------- | ----------------------------------------------------------- | +| `/authsec/.well-known/openid-configuration` | **SPIRE federation only** — used by SPIRE servers to verify AuthSec-issued JWT-SVIDs. Not spec-compliant for user-facing OAuth, and **not** the URL to use for MCP. | +| `/authsec/oauth/.well-known/oauth-authorization-server` | **User-facing OAuth 2.1 / OIDC** — this is what MCP clients should consume. | + +For MCP, the issuer URL is your AuthSec base URL with the `/authsec/oauth` suffix. For example, on AuthSec Cloud: + +``` +https://prod.api.authsec.ai/authsec/oauth +``` + +If you self-host AuthSec, the issuer is `/authsec/oauth`. The discovery document is served at `/.well-known/oauth-authorization-server` and `/.well-known/openid-configuration` (both return the same JSON). + +:::tip[Verify your AuthSec deployment is MCP-compatible] +Paste your AuthSec discovery URL into the [provider tester](/provider-list#test-your-provider). AuthSec Cloud passes 5/6 checks; see the [Provider List](/provider-list) entry for current Dynamic Client Registration status. +::: + +## Configure scopes {#configure-scopes} + +AuthSec advertises a baseline scope set in the discovery document: `openid`, `profile`, `email`, `offline_access`. + +To define MCP-server-specific scopes (e.g. `create:todos`, `read:todos`): + +1. Sign in to the AuthSec Console. +2. Open **OAuth Scopes** under your tenant. +3. Create the scopes your MCP server requires. Use short, action-shaped names (`read:todos`, not `todo_reader_can_read`). +4. Assign scopes to the roles or users who should hold them. + +AuthSec's scopes flow through to the access token's `scope` claim, where your MCP server can enforce them via MCP Auth's `BearerAuth` middleware in the usual way. + +## Retrieving user identity {#retrieving-user-identity} + +AuthSec is OIDC-compliant and exposes a standard userinfo endpoint. The discovery document advertises the following claims: + +``` +sub, iss, aud, exp, iat, user_id, tenant_id, email, spiffe_id +``` + +The `tenant_id` claim is AuthSec-specific and useful when your MCP server is multi-tenant — you can authorize per-tenant without re-keying. + +The `spiffe_id` claim only appears when the token is a delegated JWT-SVID (an agent acting on behalf of a user, via AuthSec's `delegate-svid` endpoint). For standard user OAuth flows you will not see it; for agent-to-agent flows where AuthSec brokers SPIFFE identity, you will. + +To fetch a token usable against the userinfo endpoint, request at least the `openid` and `profile` scopes during the authorization flow. + +## Token request parameters {#token-request-parameters} + +AuthSec supports both the [RFC 8707 `resource` parameter](https://datatracker.ietf.org/doc/html/rfc8707) and conventional scope-based authorization. The discovery document declares `resource_indicators_supported: true`. + +### Resource indicator (recommended for MCP) + +```json +{ + "resource": "https://my-mcp-server.example.com/", + "scope": "read:todos create:todos openid" +} +``` + +The MCP authorization spec encourages binding tokens to a specific resource using the `resource` parameter — AuthSec honors this and will scope the token's audience to the supplied resource URL. + +:::note[Trailing slash in resource indicator] +Include a trailing slash in the resource value. The MCP SDK currently appends one automatically; mismatched values cause the authorization server to reject the request. +::: + +## Register MCP client {#register-mcp-client} + +AuthSec's public Dynamic Client Registration (RFC 7591) endpoint is in active development. Until it ships, register your MCP client manually: + +1. Sign in to the AuthSec Console. +2. Navigate to **Applications → Clients**. +3. Create a new client: + - **Type**: **Native App** for desktop MCP clients (VS Code, Cursor, the MCP Inspector running on a developer's machine). **Single Page App** for browser-based clients. + - **Name**: e.g. "VS Code MCP Bridge" + - **Redirect URIs** (check the client's documentation; for VS Code): + ``` + http://127.0.0.1 + https://vscode.dev/redirect + ``` +4. Under the client's **Scopes** tab, attach the scopes the MCP server requires. +5. Copy the **Client ID** for use in your MCP client configuration. Public clients do not need a client secret — AuthSec accepts `none` as a `token_endpoint_auth_method` and requires PKCE (`S256`) for all such clients. + +### First-party vs third-party MCP clients + +- **First-party**: you operate both the MCP client and the MCP server (e.g. an AI assistant embedded in your own product). Users are your existing AuthSec users; no consent screen is shown. +- **Third-party**: the MCP client is operated by someone else (VS Code, Cursor, community tooling). Users will see an AuthSec consent screen describing exactly which scopes the client is requesting. + +AuthSec's consent screen lists the requesting client, the scopes, and (if a resource indicator was supplied) the target MCP server URL — so users see explicitly which server is being authorized, not just which client. + +## Agent-on-behalf-of-user flows {#agent-delegation} + +AuthSec ships a `delegate-svid` endpoint that mints a short-lived RS256 JWT-SVID with a SPIFFE ID of the shape: + +``` +spiffe:///user//agent/ +``` + +This is useful when your MCP server hands work off to a secondary agent (a sub-LLM, a background worker) and you want that downstream agent to carry verifiable user identity *and* be distinguishable from the user in audit logs. The endpoint lives at: + +``` +POST /authsec/uflow/auth/enduser/delegate-svid +``` + +This is AuthSec-specific and outside the MCP authorization spec — useful but not required to be MCP-compatible. See the AuthSec documentation for the full delegation flow. diff --git a/sidebars.ts b/sidebars.ts index 05f64ca..f5508a2 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -31,6 +31,7 @@ const sidebars: SidebarsConfig = { label: 'Provider Guides', link: { type: 'doc', id: 'provider-guides/README' }, items: [ + 'provider-guides/authsec', 'provider-guides/logto', 'provider-guides/keycloak', 'provider-guides/generic',