Skip to content

Commit 37937b8

Browse files
committed
Sync open source content 🐝 (from 179623a35a986d62049471e9e9a0cde05f183e00)
1 parent 36a1adb commit 37937b8

6 files changed

Lines changed: 108 additions & 20 deletions

File tree

β€Ždocs/ai-control-plane/concepts.mdxβ€Ž

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,7 @@ Authentication answers two separate questions, and each server configures them i
223223

224224
The first is who is calling. The platform is the OAuth 2.1 authorization server for each MCP server. Clients identify themselves with Dynamic Client Registration (DCR) or a Client ID Metadata Document (CIMD), sign in with PKCE, and see a consent screen on every sign-in. Access tokens are short-lived and refresh tokens rotate. See [User sessions](/docs/ai-control-plane/mcp-gateway/access/user-sessions).
225225

226-
The second is which credential reaches the upstream API. A remote server calls upstream as each user, with one shared agent credential, or with no identity. Built servers read secrets from [environments](/docs/ai-control-plane/mcp-gateway/environments). See [Upstream credentials](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials).
226+
The second is which credential reaches the upstream API. A remote server calls upstream as each user, with one shared service account credential, or with no managed identity. Built servers read secrets from [environments](/docs/ai-control-plane/mcp-gateway/environments). See [Upstream credentials](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials).
227227

228228
[OAuth and upstream providers](/docs/ai-control-plane/concepts#oauth-and-upstream-providers) covers both relationships in detail.
229229

@@ -293,7 +293,7 @@ A remote identity provider is an upstream OAuth or OIDC issuer the platform trus
293293
| **Project** | The organization, scoped to one project that needs its own branding, scopes, or audience handling. |
294294

295295
- **Issuer discovery.** Admins add an issuer by URL. The platform reads its endpoints from published metadata (RFC 8414) and warns when the issuer does not advertise PKCE `S256`.
296-
- **Client registration.** Each provider needs a registered client, created by DCR (RFC 7591), by a CIMD the platform hosts with no stored secret, or entered manually.
296+
- **Client registration.** Each provider needs a registered client, created by DCR (RFC 7591), by a CIMD the platform hosts with no stored secret, or entered manually. A client either signs in as each user, holding a token per person, or as a service account, holding one token for itself obtained with the OAuth client credentials grant.
297297
- **Signed-key client authentication.** A client can authenticate to the issuer with `private_key_jwt` instead of a shared secret. The assertion is signed with a signing key set built from the organization's own KMS keys, which requires the customer-managed encryption keys entitlement. See [Encryption Keys](/docs/ai-control-plane/org-admin/encryption-keys#signing-keys-jwks).
298298
- **Private issuers.** An issuer reachable only from a private network can be bound to an MCP tunnel. Discovery, token exchange, refresh, revocation, and client registration then go through the tunnel.
299299
- **Housekeeping.** Providers can move between project and organization scope or be consolidated into another provider for the same issuer. DCR clients can be rotated in place. Client secrets are encrypted at rest and never displayed.
@@ -307,8 +307,8 @@ Each server decides what reaches the upstream API.
307307
| Mode | What reaches the upstream API |
308308
| --- | --- |
309309
| **User Identity** | Each person's own OAuth token from the remote identity provider. A tool call runs as that person in the upstream system. |
310-
| **Agent Identity** | One shared credential for the server, sent as the `Authorization` header for every caller. |
311-
| **No Identity** | No managed credential. Suitable for public upstream APIs, with any static headers set by hand. |
310+
| **Service Account** | One shared credential for the server, sent as the `Authorization` header for every caller. Either a static credential, or an access token the platform obtains for itself with the OAuth client credentials grant. |
311+
| **Manual** | No managed credential. Suitable for public upstream APIs, with any static headers set by hand. |
312312
| **Environment variables** | On built servers, values from an attached environment injected by the system, or supplied by each user when they connect. |
313313

314314
Per-user credentials require user sessions, since each token is stored against a known person. Shared credentials work on any server. See [Upstream credentials](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials) and [Picking an authentication model](/docs/ai-control-plane/mcp-gateway/access#picking-an-authentication-model).

β€Ždocs/ai-control-plane/identity/remote-identity-providers.mdxβ€Ž

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ A remote identity provider is an upstream OAuth or OIDC issuer that the platform
1010
## Access requirements
1111

1212
<Callout type="info">
13-
Viewing providers requires the `org:read` scope, which both default roles hold. Creating, editing, moving, consolidating, and deleting providers, and managing their clients, requires `org:admin`, which only the [Admin role](/docs/ai-control-plane/org-admin/roles-and-permissions) includes by default. Registering a client by dynamic client registration through a tunnel-bound provider requires a Speakeasy platform administrator.
13+
Viewing providers requires the `org:read` scope, which both default roles hold. Creating, editing, moving, consolidating, and deleting providers, and managing their clients, requires `org:admin`, which only the [Admin role](/docs/ai-control-plane/org-admin/roles-and-permissions) includes by default. Registering a client by dynamic client registration through a tunnel-bound provider requires a Speakeasy platform administrator. A service account client can also be created from an MCP server's **Identity** section with `project:write` and `mcp:write`, as described in [Upstream credentials](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials#oauth-client-credentials-on-remote-servers).
1414
</Callout>
1515

1616
## Where a provider lives
@@ -33,7 +33,14 @@ When the issuer changes its metadata, use **Refresh Discoverable Metadata** to u
3333

3434
## Register a client
3535

36-
A provider needs a registered OAuth client before MCP servers can use it. Select **Add Client** and choose how to register it:
36+
A provider needs a registered OAuth client before MCP servers can use it. Select **Add Client**, or **New Client** on the provider's **Clients** tab.
37+
38+
**Signs in as** decides whose upstream credential the client holds, and is fixed once the client is created:
39+
40+
- **Each user**: every caller connects their own account at the provider. This is the client a server uses for [User Identity](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials#credentials-per-end-user).
41+
- **Service account**: the client gets one token for itself with the OAuth client credentials grant, and every caller shares it. See [Service account clients](#service-account-clients).
42+
43+
An **Each user** client can be registered three ways:
3744

3845
- **Dynamic Client Registration (DCR)** registers a client automatically when the issuer has a registration endpoint (RFC 7591). **Rotate client** later registers a replacement and swaps it in place, which signs out existing sessions so users reconnect once.
3946
- **Client ID Metadata Document (CIMD)** uses a public document the platform hosts as the client ID, when the issuer supports it. No credentials are stored, so there is nothing to expire or rotate.
@@ -43,10 +50,30 @@ MCP servers select a provider in their authentication settings. An MCP server ho
4350

4451
Deleting a client revokes every session issued through it. Client secrets are encrypted at rest and never displayed.
4552

53+
### Service account clients
54+
55+
A service account client holds one upstream credential for itself instead of one per person. The platform requests its access token from the provider's token endpoint with the OAuth client credentials grant, and an MCP server that uses it sends that token upstream for every caller. See [OAuth client credentials on remote servers](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials#oauth-client-credentials-on-remote-servers) for how a server uses one.
56+
57+
The quickest way to create one is from the MCP server's **Identity** section, which creates the client and attaches it to the server in one step. To create one from the provider instead, choose **Service account** under **Signs in as** in the **New Client** sheet:
58+
59+
1. Create a machine-to-machine app at the provider that is allowed the client credentials grant, and turn off DPoP for it, since the platform does not send DPoP proofs.
60+
2. Paste the app's **Client ID**.
61+
3. Choose the **Token Endpoint Auth Method**: a secret in the Authorization header (`client_secret_basic`, the default), a secret in the request body (`client_secret_post`), or an assertion signed with one of the organization's key sets (`private_key_jwt`). Enter the **Client Secret**, or pick the key set and the **Client assertion audience**. `private_key_jwt` shows **Requires KMS** without the customer-managed encryption keys entitlement.
62+
4. Optionally set **Scope (override)**, comma-separated, and **Audience (optional)**. A service account client requests no scopes when the override is empty. On an organizational provider, also choose whether the client serves all projects or one.
63+
5. Select **Create**.
64+
65+
Selecting **Create** opens the client's page. For a `private_key_jwt` client, that page shows the **Key set URL** and **Public key** to register with the provider.
66+
67+
The provider must have a token endpoint. When it publishes none, **Service account** is disabled until one is added on the provider's **Settings** tab. The endpoint can be entered by hand without metadata discovery, and it cannot be removed while a service account client depends on it.
68+
69+
A service account client is marked **Service account** on the provider's **Clients** tab and on its own page, where **Signs in as** reads **Itself**. Its token endpoint auth method can be changed later, except to `none`, since a service account client must always authenticate. It cannot be rotated by dynamic client registration or used for trusted identity provider login. When the provider stops accepting its credentials, MCP servers that use it report an upstream credential error to callers until a new secret or key is entered. Deleting a service account client is allowed while MCP servers use it, and those servers then stop authenticating upstream.
70+
4671
## Authenticate a client with a signed key
4772

4873
A client can authenticate to the issuer with a signed assertion instead of a shared secret. Set the client's token endpoint authentication method to `private_key_jwt` and attach a **Signing key set**. The assertion audience defaults to the issuer identifier and can be switched to the token endpoint URL for issuers that require it. A key set cannot be deleted while a client uses it.
4974

75+
For a service account client, the client's page also shows the **Key set URL** and the **Public key** to register with the provider, so the provider can verify the client's assertions.
76+
5077
<Callout type="info">
5178
Signing key sets are created from the organization's own KMS keys on [Encryption Keys](/docs/ai-control-plane/org-admin/encryption-keys#signing-keys-jwks) and require the customer-managed encryption keys entitlement.
5279
</Callout>

β€Ždocs/ai-control-plane/mcp-gateway/access/index.mdxβ€Ž

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,12 @@ Authentication covers the first two questions. A server can answer one, both, or
3737
On a remote server, the **Identity** section of the **Settings** tab asks the second question as one choice, described as how callers are identified to the upstream service. Changes take effect on new connections. There are three options:
3838

3939
- **User Identity**: each person signs in to the upstream service as themselves and keeps their own permissions there. Pick the **Identity provider** where people sign in, and the platform registers the server with it. **Manage identity providers** links to the organization-wide list. Because each upstream token is stored against a person, User Identity also requires callers to sign in to the server.
40-
- **Agent Identity**: every caller acts as one service account. The **Agent credential** is one credential every caller shares, sent to the upstream service as the `Authorization` header. What that account may do is managed in the control plane.
41-
- **No Identity**: the platform manages no identity for the upstream service, and any static headers are managed by hand. No `Authorization` header is set. When the upstream answers with an authentication challenge, the **No Identity** option carries a warning, because requests will keep failing without an identity.
40+
- **Service Account**: every caller shares one identity, sent to the upstream service as the `Authorization` header. The credential is either **Static** (a **Bearer** token, a **Basic** username and password, or a **Manual** header value) or **OAuth** (an access token the platform obtains for itself with the client credentials grant, using a **Client Secret** or a **Signing Client**). What callers may do with it is managed in the control plane. See [One credential for the whole server](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials#one-credential-for-the-whole-server).
41+
- **Manual**: the platform manages no identity for the upstream service, and any static headers are managed by hand. No `Authorization` header is set. When the upstream answers with an authentication challenge, the **Manual** option carries a warning, because requests will keep failing without an identity.
4242

4343
The collapsible **Custom Headers** row holds upstream headers sent with every request, whichever option is chosen. See [Upstream headers on remote servers](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials#upstream-headers-on-remote-servers).
4444

45-
Leaving User Identity unlinks the identity provider from the server. People who already signed in lose access through it and have to authorize again if the server switches back. Leaving Agent Identity removes the shared credential, so requests no longer authenticate upstream. Both changes ask for confirmation before saving.
45+
Leaving User Identity unlinks the identity provider from the server. People who already signed in lose access through it and have to authorize again if the server switches back. Leaving Service Account removes the shared credential or detaches the service account client, so requests no longer authenticate upstream. Both changes ask for confirmation before saving.
4646

4747
<Screenshot
4848
url="ai.speakeasy.com"
@@ -59,7 +59,7 @@ Built and tunneled servers make the same decisions through separate settings, su
5959
| Only organization members can connect, using their Speakeasy login | [User sessions](/docs/ai-control-plane/mcp-gateway/access/user-sessions) on a private server | Identity only |
6060
| Anyone can connect anonymously, with no login | Public visibility, which requires a [tunneled backend](/docs/ai-control-plane/mcp-gateway/tunneled-servers) and the tunnel source owner's consent | No |
6161
| Each end user acts against their own account on an upstream service | User Identity on a remote server, or [remote identity providers](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials) layered on user sessions | Yes |
62-
| One shared credential for the whole server | Agent Identity on a remote server, or [environment system variables or upstream headers](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials) | No |
62+
| One shared credential for the whole server | Service Account on a remote server, with a static credential or an OAuth client credentials token, or [environment system variables or upstream headers](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials) | No |
6363
| Each connecting user supplies their own API key | Environment variables marked as user-provided | Yes |
6464
| Each end user reaches an upstream service through the organization's Okta, with no per-service connect step | [Enterprise Managed Auth](/docs/ai-control-plane/identity/identities/enterprise-managed-auth) on a server signed in through an Okta-trusted user session issuer | Yes |
6565

0 commit comments

Comments
Β (0)