How does an MCP client (Claude, LangChain) interact with gateway-level roles and teams — does the OAuth token carry the identity or is there a separate user management layer the agent doesn't see?

[omar692002]

Hey, I'm new to MCP and trying to understand the full token lifecycle in a spec-compliant flow, specifically when introducing a gateway like ContextForge. From the MCP spec, I understand the client is supposed to do DCR, trigger an Authorization Code flow (popup, user consent), and then make requests with a scoped access token + refresh token issued by an external AS. What confuses me is how this maps to the gateway layer. The gateway exposes /.well-known/oauth-protected-resource/servers/{UUID}/mcp (RFC 9728) which tells the client which external AS to authenticate against — so the gateway itself is purely a Resource Server, not an AS. That part I get. But here's where I lose the thread: the gateway also has its own internal RBAC system (roles, teams, users) managed via admin UI or API. When Claude (on claude.ai, configuring an MCP connector pointing to a virtual server URL) or a LangChain agent connects, is the "user" that the gateway resolves for RBAC purposes derived from the JWT claims of the AS-issued token (e.g. the email field)? Or is there a second gateway-internal JWT in play — the kind generated by the gateway's own auth service? Because looking at the code, get_current_user_with_permissions is used everywhere and the team membership check (is_team_member(gateway_team_id)) happens after token validation — so I can't tell if the gateway is matching the OAuth identity to its internal user registry, or managing these as two completely separate systems. And from the agent side: does it hold a short-lived access token and refresh automatically per spec, or do people just inject a static long-lived token in practice and bypass the refresh flow entirely?

[crivetimihai]

Hi @MnifOmar, excellent deep dive. Let me untangle the token lifecycle for you.

Gateway as Resource Server (RFC 9728) — you've got this right. The path-based endpoint:

GET /.well-known/oauth-protected-resource/servers/{server_id}/mcp

tells spec-compliant clients which external AS to authenticate against. The gateway itself is a Resource Server in this model.

How identity maps to RBAC — the key distinction is token_use:

ContextForge supports two token types that flow through the same get_current_user_with_permissions() pipeline:

Token Type	token_use claim	Team Resolution	Typical Use
Session tokens	session	Teams resolved from DB on each request (dynamic)	Interactive UI/browser sessions
API tokens	api	Teams from JWT teams claim via normalize_token_teams() (static)	Programmatic/agent access

The identity resolution flow:

1. Token arrives (JWT from external AS or gateway-issued)
2. get_current_user() validates the JWT signature and extracts claims (sub, username, email, teams, is_admin)
3. For external AS tokens: The gateway matches the sub/email claim from the external JWT to its internal user registry. The user must exist in the gateway's user table.
4. For gateway-issued tokens: Claims are directly trusted.
5. normalize_token_teams() resolves visibility scope from the teams claim:
   • Missing teams key → public-only access (secure default)
   • teams: null + is_admin: true → admin bypass (sees all)
   • teams: ["team-a"] → sees team-a + public resources
6. get_current_user_with_permissions() then checks RBAC permissions via PermissionService, looking up the user's role assignments in user_roles table

So to answer directly: The gateway matches the OAuth identity (from the AS-issued JWT claims) to its internal user registry, then applies RBAC based on the user's role assignments in the gateway's database. These are bridged systems, not completely separate — the external identity is the key that links to the internal role model.

On token lifecycle in practice: The MCP spec supports Authorization Code flow with refresh tokens. Spec-compliant clients (Claude Desktop, etc.) should handle short-lived access tokens with automatic refresh. In practice, many integrations use longer-lived API tokens generated via the gateway for simplicity, but the proper refresh flow is fully supported.

[omni-front]

not sure exactly how the gateway maps the OAuth identity to its internal RBAC. it could be using the JWT claims, but there might be a separate internal user management layer too. if you're seeing get_current_user_with_permissions and is_team_member, it could be doing some internal mapping. might be worth diving deeper into the gateway's auth service docs or code for clarity.

[crivetimihai]

To clarify the comment above — there's no ambiguity in how we map OAuth identity to RBAC. It's a single pipeline:

1. External OAuth token arrives → JWT validated → sub/email extracted
2. User matched to internal registry — the email from the external JWT is matched against our EmailUser table. Users are auto-provisioned during SSO login or created via the admin API.
3. Team resolution depends on token_use:
   • token_use="session" (SSO/browser): teams resolved dynamically from DB on every request
   • token_use="api" (programmatic): teams read statically from the JWT teams claim
4. RBAC enforced — get_current_user_with_permissions() applies both Layer 1 (token scoping / data filtering) and Layer 2 (permission checks)

So @omar692002, to directly answer your question: the gateway does map the external OAuth identity to its internal user registry — these are not two separate systems. The email claim is the join key. Team membership and role assignments are stored server-side and synced during SSO login via configurable team_mapping and role_mapping on each provider.

Hope that clears things up — let me know if you have follow-up questions.

[itxashancode]

The gatewayuses the external OAuth token's JWT claims (specifically the email field) to map to its internal user registry via EmailUserProvider. After validating the external token, it resolves the email to an internal user and checks team membership with is_team_member(), which operates on the gateway's internal RBAC system. No second JWT is generated