Skip to content
MCP Gateway

Identity, Policy, Credentials

Access

Identity, Policy, Credentials

Section titled “Identity, Policy, Credentials”

Access in MCP Gateway is a chain, not a single login check. Runtime calls need actor context, agent context, client surface, environment, policy, approval state, and credential binding state before upstream work is allowed.

Audience

Section titled “Audience”
  • Identity admins mapping enterprise IdP claims to gateway actor context.
  • Security admins authoring Cedar policy and running simulations.
  • Source owners choosing credential modes for MCP servers or selected API operations.
  • Operators diagnosing missing identity, policy, credential, or agent state.

What is this?

Section titled “What is this?”

This page connects the access model across identity, agents, Cedar policy, role bindings, client surfaces, and credential bindings.

Production auth modes are explicit:

  • trusted_proxy: an upstream enterprise proxy validates OIDC, SAML, or session state, strips inbound gateway headers, and forwards normalized actor headers.
  • oidc_jwt: the control plane validates bearer JWT issuer, audience, signature, algorithm, time bounds, subject, tenant, environment, and client-surface claims.
  • local_identity: no-IdP production mode backed by PostgreSQL local users, groups, sessions, and service-account token hashes.
  • local_header_bootstrap: local/test only.

Agents are governed actors. They need owner metadata, approval state, policy context, audit attribution, and revocation paths before runtime calls can rely on them.

Credentials stay behind the broker. Bindings store safe refs and metadata. The broker resolves an allowed credential mode without returning raw secret material to docs, UI, CLI, audit, traces, metrics, fixtures, or prompts.

When do I use it?

Section titled “When do I use it?”

Use this page when a caller cannot discover a tool, a call is denied, a credential binding fails, or a reviewer needs to prove default deny before approving a new source.

What happens?

Section titled “What happens?”
  1. The request resolves authenticated actor context through the configured auth mode.
  2. GET /v1/identity/me returns normalized actor, role IDs, and collection permissions without echoing raw token claims.
  3. Role bindings grant scoped admin actions such as role_binding.read, role_binding.manage, or MCP server review actions.
  4. Runtime agent ID and agent instance ID resolve through approved registry state.
  5. Cedar evaluates principal, action, resource, and context. Deny overrides allow, and default deny is preserved.
  6. Discovery hides unauthorized tools. Execution denials return stable machine reasons.
  7. Policy simulation can evaluate user, group, agent, client surface, environment, server/API source, tool, credential mode, and policy version without side effects.
  8. Credential bindings move through validation, approval, rotation, disable, and revoke states. Missing, disabled, revoked, or policy-disallowed credentials fail closed.

What can go wrong?

Section titled “What can go wrong?”
  • Missing actor identity returns 401 invalid_actor_identity.
  • OIDC/JWT validation can fail on malformed token, missing key ID, issuer, audience, algorithm, signature, expiry, subject, tenant, environment, or client-surface claims.
  • Disabled or expired role bindings stop granting roles without a process restart.
  • A non-human agent may be submitted but not approved, disabled, missing an instance ID, outside an allowed surface, or outside an allowed environment.
  • A permit rule does not win if a matching forbid rule exists.
  • Credential material pasted into values, docs, diagnostics, fixtures, logs, traces, metrics, audit, or prompts is a release blocker.

Source truth

Section titled “Source truth”

Next

Section titled “Next”

Type set in Geist, Source Serif 4, and Departure Mono.