Document connector auth types and policies

docs/connector-gateway/connector-authentication.mdx

@@ -0,0 +1,107 @@
+---
+title: Configure connector authentication
+sidebar_label: Connector authentication
+description:
+  Choose how the Connector Gateway authenticates to each connector's backend,
+  from static secrets to per-user OAuth and token exchange flows.
+---
+
+Connector authentication sets the credential the Connector Gateway sends to a
+connector's backend MCP server. Callers authenticate to the gateway with their
+own identity, and the gateway attaches the outbound credential that the
+connector's authentication type defines.
+
+## Choose an authentication type
+
+Every connector has exactly one authentication type. The console supports the
+first five types in the table below. Configure `awsSts`, `obo`, and `xaa`
+through the
+[Enterprise Manager API](../platform/enterprise-platform/api-reference.mdx#enterprise-manager).
+
+| Console label                  | API `type`        | What the gateway sends                                                                     | Needs                                      |
+| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------ |
+| **None**                       | `none`            | No credential                                                                              | Nothing                                    |
+| **Bearer token**               | `bearerToken`     | A static token in the `Authorization` header                                               | A secret                                   |
+| **Header injection**           | `headerInjection` | A static value in a header you name                                                        | A secret                                   |
+| **Upstream identity provider** | `upstreamInject`  | The calling user's own OAuth token, collected through a per-user consent flow              | A connector identity provider              |
+| **Token exchange (RFC 8693)**  | `tokenExchange`   | A token obtained by exchanging the caller's token at call time                             | A token endpoint; a secret is optional     |
+| API only                       | `awsSts`          | AWS SigV4-signed requests using temporary credentials from AWS STS web-identity federation | An identity provider; no secret            |
+| API only                       | `obo`             | A Microsoft Entra ID token from the On-Behalf-Of (OBO) flow                                | An identity provider and a secret          |
+| API only                       | `xaa`             | A token from the cross-app access (ID-JAG) flow                                            | An identity provider; secrets are optional |
+
+Use these guidelines to pick a type:
+
+- Use **None** for a backend that needs no credential, such as an internal MCP
+  server that's reachable only inside your cluster.
+- Use **Bearer token** or **Header injection** when the backend accepts one
+  shared API key for every caller. Every user reaches the backend with the same
+  identity.
+- Use **Upstream identity provider** when the backend should act as each user,
+  for example a SaaS MCP server that requires the user's own OAuth grant.
+- Use **Token exchange (RFC 8693)**, `obo`, `xaa`, or `awsSts` when the backend
+  trusts your identity provider and accepts a token derived from the caller's
+  identity.
+
+## Set up the prerequisites in order
+
+Each authentication type references objects that must exist before you save the
+connector. Create them in this order:
+
+1. **Secrets.** Create a
+   [managed secret](../platform/enterprise-directory/managed-secrets.mdx) for
+   each static credential or client secret the type needs.
+2. **Identity provider.** Register a
+   [connector identity provider](../platform/enterprise-directory/identity-providers.mdx)
+   for types that need one. The provider's client secret is itself a managed
+   secret, which is why secrets come first.
+3. **Connector authentication.** Configure the connector's authentication type,
+   referencing the secrets and provider.
+4. **Access.** Grant access to the connector through its
+   [connector policy](./connector-policies.mdx).
+
+## Configure authentication in the console
+
+1. In the console, open the connector and select the **Configuration** tab.
+2. Under **Authentication**, choose a **Backend auth** type and fill in its
+   fields:
+   - **Bearer token**: under **Secret reference**, choose the managed secret
+     that holds the token.
+   - **Header injection**: enter the **Header name**, for example `X-API-Key`,
+     and choose the managed secret that holds its value.
+   - **Upstream identity provider**: choose the connector identity provider that
+     users authorize against.
+   - **Token exchange (RFC 8693)**: enter the **Token URL** and **Client ID**,
+     and optionally an audience, scopes, and a **Client secret reference**.
+3. Select **Save**. For a draft connector, select **Save and verify**, which
+   checks the endpoint and authentication before publishing it.
+
+## How users authorize connectors
+
+For an **Upstream identity provider** connector, each user completes consent in
+**Your workspace** or during client connection. The Connector Gateway stores the
+authorization and prompts the user to **Re-authenticate** after it expires.
+
+Each stored authorization is bound to the identity provider configuration that
+issued it. Changing any of these settings makes every user of that provider
+authorize again on their next connection:
+
+- The provider's issuer, OAuth endpoints, or client ID
+- The requested scopes or additional authorization parameters
+- The redirect URI, which derives from the Connector Gateway issuer
+
+The gateway keeps the stored authorizations. If you revert the change, users'
+existing authorizations work again without another consent step.
+
+## Next steps
+
+- [Grant and revoke connector access](./connector-policies.mdx) to choose which
+  groups can use the connector.
+- [Tool usage](./tool-usage.mdx) to confirm that users are calling the
+  connector's tools.
+
+## Related information
+
+- [Identity providers](../platform/enterprise-directory/identity-providers.mdx) -
+  register the providers that per-user and federation types reference
+- [Managed secrets](../platform/enterprise-directory/managed-secrets.mdx) -
+  store the credentials that static types reference

docs/connector-gateway/connector-policies.mdx

@@ -0,0 +1,59 @@
+---
+title: Grant and revoke connector access
+sidebar_label: Connector access
+description:
+  Grant directory groups access to a connector and revoke it, so each user sees
+  only the connectors their groups allow.
+---
+
+Each connector has a _connector policy_ that decides which users can reach it.
+In the console, you manage a connector's policy by granting directory groups
+access to it. A connector with no groups is unreachable.
+
+The Connector Gateway evaluates the policy on every request, so a grant or
+revocation takes effect on the caller's next request.
+
+## Grant access to directory groups
+
+1. In the console, open the connector and select the **Access** tab.
+2. Select **Add groups**.
+3. Select one or more groups, then select **Grant access**.
+
+Membership is inherited, so granting to a parent group reaches every subgroup
+beneath it. See
+[Subgroups and inherited membership](../platform/enterprise-directory/users-and-groups.mdx#subgroups-and-inherited-membership).
+Directory groups are separate from the OpenID Connect (OIDC) claim groups that
+cluster authorization policy matches. See
+[Directory groups and OIDC claim groups](../platform/concepts/two-group-models.mdx).
+
+## Revoke a group's access
+
+1. On the connector's **Access** tab, open the actions menu for the group.
+2. Select **Revoke access**.
+
+The revocation applies immediately, with no confirmation step. Revoking the last
+group leaves the connector unreachable by anyone.
+
+## Cedar-mode connectors
+
+A connector policy can also be in Cedar mode, where a Cedar policy document
+decides access instead of group grants. For a Cedar-mode connector, the console
+shows a notice on the **Access** tab and disables group editing.
+
+Switch modes and write Cedar policy documents through the connector policy
+routes of the
+[Enterprise Manager API](../platform/enterprise-platform/api-reference.mdx#enterprise-manager).
+
+## Next steps
+
+- [Configure connector authentication](./connector-authentication.mdx) to set
+  the credential the gateway sends to the backend.
+- [Tool usage](./tool-usage.mdx) to confirm the right users are calling the
+  connector.
+
+## Related information
+
+- [Directory groups and OIDC claim groups](../platform/concepts/two-group-models.mdx) -
+  how connector policies relate to cluster authorization groups
+- [Users and groups](../platform/enterprise-directory/users-and-groups.mdx) -
+  manage the directory groups that policies reference

docs/connector-gateway/connectors.mdx

@@ -2,90 +2,76 @@
 title: Manage connectors
 sidebar_label: Connectors
 description:
-  Register connectors, import them from your registry, grant access to groups,
-  and understand the draft, available, and failure states.
+  Register connectors from your registry, cluster, or by hand, and configure
+  their transport and private network access.
 ---
 
-A _connector_ is an MCP server available through the Connector Gateway. After
-registering a connector, grant access to it through its connector policy.
+A _connector_ is an MCP server available through the Connector Gateway. Manage
+connectors in the console under **Connectors**. After registering a connector,
+configure its authentication and grant access to it through its connector
+policy.
 
-## The connector list
+## Connector sources
 
-The **Connectors** screen lists every registered connector with its endpoint,
-transport, state, the number of groups that have access, and when it was
-created.
+Select **Add connector** and choose a source:
 
-## Where connectors come from
+- **Import from registry** adds remote MCP servers that your curated MCP
+  registry publishes.
+- **Discover in Kubernetes** lists the `MCPServer` resources running in your
+  cluster. Select the ones you want and choose **Add to catalog**. Each one
+  becomes a draft connector.
+- **Configure manually** registers any MCP server by name, endpoint, and
+  transport.
 
-Select **Add connector** and choose how to register the connector:
+## Connector settings
 
-- **Import from registry** adds remote servers that your curated MCP registry
-  publishes.
-- **Discover in Kubernetes** scans your cluster for running MCP servers and lets
-  you choose which ones to add.
-- **Configure manually** registers a server by name, endpoint, and transport.
+A connector's **Configuration** tab holds its name, endpoint, transport, and
+authentication. See
+[Configure connector authentication](./connector-authentication.mdx) for the
+authentication types.
 
-### Add MCP servers from your cluster
-
-Discovery lists every `MCPServer` resource in your cluster, across all
-namespaces, as a candidate. Nothing is registered until you select candidates
-and choose **Add to catalog**.
-
-Each candidate shows its namespace, transport, and endpoint. If an existing
-connector already uses a candidate's endpoint, the candidate shows **Already
-added as** and the connector's name. A candidate that belongs to an MCP server
-group shows that group, because a vMCP might already aggregate it and adding it
-separately would expose its tools twice. If discovery can't determine a
-candidate's transport, choose one before adding it.
-
-Each server you add becomes a **Draft** connector with no backend authentication
-and a description naming the namespace it came from. Open the connector to
-review its configuration, then save it to publish the connector.
-
-## Draft, available, and failure
+### Draft, available, and failure
 
 **Draft** connectors are registered but inactive. Activating a connector
 triggers an endpoint check. A valid MCP endpoint becomes **Available**; an
 invalid or unreachable endpoint enters **Failure**.
 
-## Granting access
-
-Each connector has a connector policy that decides who can use it. The policy
-has two authoring modes:
-
-- **Structured** mode grants access to directory groups. This is the mode the
-  console manages.
-- **Cedar** mode uses a Cedar policy document. A document can match directory
-  group (`UserGroup`) membership, custom claims from the caller's token such as
-  `principal.claim_department`, or both.
+### Transport
 
-To grant access in structured mode, open a connector and use **Grant access** to
-add one or more groups. Membership is inherited, so granting to a parent group
-reaches every subgroup beneath it. Directory groups are separate from the OIDC
-claim groups that cluster authorization policy matches. See
-[Directory groups and OIDC claim groups](../platform/concepts/two-group-models.mdx).
+The Connector Gateway serves connectors that use the `streamable-http` or `sse`
+transport. SSE is a deprecated MCP transport, so choose **Streamable HTTP**
+unless the backend supports only SSE. If a connector's stored transport isn't
+one of these, the gateway withholds the connector and the console asks you to
+choose a transport before you can save.
 
-The console doesn't edit Cedar-mode policies. For a Cedar-mode connector, it
-shows a notice and disables group editing. Switch modes and write Cedar
-documents through the connector policy routes of the
-[Enterprise Manager API](../platform/enterprise-platform/api-reference.mdx#enterprise-manager).
+### Private network endpoints
 
-The Connector Gateway evaluates access on every request, so changes take effect
-on the next request.
+By default, a connector endpoint must use HTTPS (plain HTTP is allowed only for
+`localhost`), and the gateway refuses to connect to an address in a private,
+loopback, or link-local range. In-cluster endpoints resolve to private
+addresses, so a connector that points at a Kubernetes Service needs **Allow
+private IPs** turned on (`allow_private_ips` in the API). The setting also
+permits plain HTTP. The gateway never connects to link-local addresses such as
+the cloud metadata endpoint, even with this setting on.
 
-## Connector authentication
+Discovery turns on **Allow private IPs** for a candidate whose endpoint is a
+Service in the candidate's own namespace. For a connector you add manually or
+import, turn it on yourself when the endpoint is in-cluster.
 
-A connector can broker OAuth through an
-[identity provider](../platform/enterprise-directory/identity-providers.mdx)
-when it needs user authorization for its backend.
+## Access and authentication
 
-Users complete consent in **Your workspace** or during client connection. The
-Connector Gateway stores the authorization and prompts the user to
-**Re-authenticate** after it expires.
+Each connector's [connector policy](./connector-policies.mdx) decides who can
+reach it, either through directory group grants on the **Access** tab or through
+a Cedar policy document. The connector's
+[authentication type](./connector-authentication.mdx) decides the credential the
+gateway sends to the backend, including per-user OAuth through an identity
+provider.
 
 ## Next steps
 
-- [Tool usage](./tool-usage.mdx) to see which connectors are actually being
-  called.
+- [Configure connector authentication](./connector-authentication.mdx) to set
+  the credential the gateway sends to each backend.
+- [Grant and revoke connector access](./connector-policies.mdx) to choose which
+  groups can use the connector.
 - [Configure the Connector Gateway](../platform/enterprise-platform/configure-connector-gateway.mdx)
   for the install-time settings behind this screen.

docs/connector-gateway/index.mdx

@@ -38,6 +38,7 @@ cluster.
 ## What you administer here
 
 - Register MCP servers as connectors.
+- Configure how the gateway authenticates to each connector's backend.
 - Grant connector access to directory groups or through Cedar policies.
 - Review tool calls by connector and tool.
 

docs/platform/concepts/two-group-models.mdx

@@ -31,9 +31,9 @@ directory evaluates each connector's policy against that user. A structured-mode
 policy grants access to directory groups. A Cedar-mode policy can match
 directory group (`UserGroup`) membership, claims from the caller's token such as
 `principal.claim_department`, or both. See
-[Granting access](../../connector-gateway/connectors.mdx#granting-access) for
-the two modes. AI Gateway group budgets also reference the directory group's
-identifier.
+[Grant and revoke connector access](../../connector-gateway/connector-policies.mdx)
+to manage group grants in the console. AI Gateway group budgets also reference
+the directory group's identifier.
 
 :::note[Cedar-mode policies are API-only]
 
@@ -64,6 +64,9 @@ Enterprise evaluates the two group models independently.
 
 ## Related information
 
+- [Grant and revoke connector access](../../connector-gateway/connector-policies.mdx)
+  to grant connector access to directory groups.
+
 - [Users and groups](../enterprise-directory/users-and-groups.mdx) for directory
   group administration.
 - [SCIM provisioning](../enterprise-directory/scim-provisioning.mdx) to source

docs/platform/enterprise-directory/identity-providers.mdx

@@ -47,5 +47,5 @@ authentication.
 
 - [Managed secrets](./managed-secrets.mdx) to store the credentials these
   providers need.
-- [Connectors](../../connector-gateway/connectors.mdx) to attach a provider to a
-  connector.
+- [Configure connector authentication](../../connector-gateway/connector-authentication.mdx)
+  to attach a provider to a connector.

sidebars.ts

@@ -465,6 +465,8 @@ const connectorGatewaySidebar: SidebarsConfig[string] = [
     className: 'enterprise-only enterprise-only--tooltip-below',
   },
   'connector-gateway/connectors',
+  'connector-gateway/connector-authentication',
+  'connector-gateway/connector-policies',
   'connector-gateway/tool-usage',
 ];
 

tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-dark-desktop-linux.json

@@ -1,5 +1,8 @@
 {
-  "titlePath": ["pages.spec.ts", "nav page - Connector Gateway"],
+  "titlePath": [
+    "pages.spec.ts",
+    "nav page - Connector Gateway"
+  ],
   "testFile": "tests/visual/pages.spec.ts",
   "url": {
     "origin": "http://localhost:3005",

tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-light-desktop-linux.json

@@ -1,5 +1,8 @@
 {
-  "titlePath": ["pages.spec.ts", "nav page - Connector Gateway"],
+  "titlePath": [
+    "pages.spec.ts",
+    "nav page - Connector Gateway"
+  ],
   "testFile": "tests/visual/pages.spec.ts",
   "url": {
     "origin": "http://localhost:3005",