RBAC Configuration¶

Role-based access control (RBAC) defines which actions users or teams can perform in ContextForge. This document covers the two-layer security model, token scoping semantics, permission system, and best practices for access control.

Overview¶

ContextForge implements a two-layer security model:

1. Token Scoping (Layer 1): Controls what resources a user CAN SEE (data filtering)
2. RBAC (Layer 2): Controls what actions a user CAN DO (action authorization)

Both layers must pass for an operation to succeed.

┌─────────────────────────────────────────────────────────────────────────────┐
│                      Two-Layer Security Model                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Request → Authentication → Token Scoping → RBAC Check → Operation        │
│                              (Can See?)       (Can Do?)                     │
│                                                                             │
│   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│   │   JWT    │   │  User    │   │ Resource │   │Permission│   │ Execute  │ │
│   │  Token   │──▶│ Identity │──▶│  Access  │──▶│  Check   │──▶│ Operation│ │
│   │          │   │          │   │          │   │          │   │          │ │
│   └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Authentication Methods¶

Core Concepts¶

Subjects¶

Users authenticated via:

• JWT tokens (session or API)
• SSO providers (OAuth 2.0/OIDC)
• Basic authentication (development only)

Teams¶

Logical groups that:

• Organize users for access boundaries
• Own resources (tools, prompts, resources)
• Map from external identity providers (SSO groups)

Built-in RBAC Roles¶

Resources¶

Protected entities:

• Servers (MCP gateways and virtual servers)
• Tools, Prompts, Resources (MCP primitives)
• System configuration and audit logs

Token Scoping Model¶

Token scoping controls what resources a token can access based on the teams claim in the JWT payload. The normalize_token_teams() function is the single source of truth for interpreting JWT team claims across all enforcement points.

Token Scoping Contract¶

The teams claim in JWT tokens determines resource visibility. The system follows a secure-first design: when in doubt, access is denied.

┌─────────────────────────────────────────────────────────────────────────────┐
│                        Token Teams Claim Handling                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  JWT Claim State          │  is_admin: true       │  is_admin: false        │
├───────────────────────────┼───────────────────────┼─────────────────────────┤
│  No "teams" key           │  PUBLIC-ONLY []       │  PUBLIC-ONLY []         │
│  teams: null              │  ADMIN BYPASS (None)  │  PUBLIC-ONLY []         │
│  teams: []                │  PUBLIC-ONLY []       │  PUBLIC-ONLY []         │
│  teams: ["team-id"]       │  Team + Public        │  Team + Public          │
│  teams: ["t1", "t2"]      │  Both Teams + Public  │  Both Teams + Public    │
└───────────────────────────┴───────────────────────┴─────────────────────────┘

is_admin, teams, and token_use (Mental Model)¶

These three values are related, but they control different things:

Key points:

1. is_admin does not automatically mean "see everything".
2. Visibility comes from normalized token_teams:
3. None = admin bypass scope
4. [] = public-only scope
5. ["t1", ...] = team-scoped visibility
6. token_use decides where teams come from:
7. session: teams are resolved from DB/cache on each request
8. api/legacy: teams come from JWT claim via normalize_token_teams()

End-to-End Authorization Pipeline¶

1. Authenticate token and resolve user
2. Verify JWT/API token.
3. Resolve token_use.
4. Normalize/resolve teams
5. token_use=session → resolve from DB (_resolve_teams_from_db()).
6. token_use!=session → normalize JWT teams (normalize_token_teams()).
7. Layer 1: Token scoping
8. Filter accessible resources by token_teams.
9. Public-only tokens cannot access team/private resources.
10. Layer 2: RBAC permission check
11. Validate action permission (tools.read, admin.system_config, etc.).
12. Public-only guard: admin.* permissions are denied when token_teams=[].

Return Value Semantics¶

Security Design Principles¶

1. Secure-First Defaults

2. Missing teams key always returns [] (public-only access)

3. This prevents accidental exposure when tokens are misconfigured

4. Explicit Admin Bypass

5. Admin bypass requires explicit teams: null AND is_admin: true

6. Empty teams [] disables bypass even for admins

7. Scoped Automation Tokens

8. Tokens with teams: [] are intentionally restricted to public resources

9. Use case: CI/CD pipelines, monitoring systems, public API clients

Token Scoping Flow¶

                                 ┌──────────────────┐
                                 │   JWT Token      │
                                 │   Received       │
                                 └────────┬─────────┘
                                          │
                                          ▼
                              ┌───────────────────────┐
                              │  Extract "teams"      │
                              │  claim from JWT       │
                              └───────────┬───────────┘
                                          │
                          ┌───────────────┴───────────────┐
                          │                               │
                          ▼                               ▼
               ┌─────────────────────┐       ┌─────────────────────┐
               │ "teams" key EXISTS  │       │ "teams" key MISSING │
               └──────────┬──────────┘       └──────────┬──────────┘
                          │                             │
                          ▼                             ▼
               ┌─────────────────────┐       ┌─────────────────────┐
               │ Check teams value   │       │ Return []           │
               └──────────┬──────────┘       │ PUBLIC-ONLY         │
                          │                  │ (secure default)    │
          ┌───────────────┼───────────────┐  └─────────────────────┘
          │               │               │
          ▼               ▼               ▼
  ┌───────────────┐ ┌───────────┐ ┌───────────────┐
  │ teams: null   │ │ teams: [] │ │ teams: [...]  │
  └───────┬───────┘ └─────┬─────┘ └───────┬───────┘
          │               │               │
          ▼               │               ▼
  ┌───────────────┐       │       ┌───────────────┐
  │ Check is_admin│       │       │ Return [...]  │
  └───────┬───────┘       │       │ TEAM-SCOPED   │
          │               │       └───────────────┘
    ┌─────┴─────┐         │
    │           │         │
    ▼           ▼         ▼
┌────────┐ ┌────────┐ ┌────────┐
│ Admin  │ │Non-Adm │ │ Empty  │
│ true   │ │ false  │ │ list   │
├────────┤ ├────────┤ ├────────┤
│ Return │ │ Return │ │ Return │
│ None   │ │ []     │ │ []     │
│ BYPASS │ │ PUBLIC │ │ PUBLIC │
└────────┘ └────────┘ └────────┘

Visibility Levels¶

Resources in ContextForge have three visibility levels:

Access Matrix by Token Type¶

# Public-only token behavior:
# ✅ Can access: visibility='public' resources
# ❌ Cannot access: visibility='team' resources (any team)
# ❌ Cannot access: visibility='private' resources (even if owned by user)

Enforcement Points¶

Token scoping is enforced consistently across all access paths:

Method-Level RBAC Examples¶

The /rpc endpoint applies method-level authorization for sensitive operations. These checks are aligned with equivalent REST endpoints.

Token Types and Use Cases¶

Session Tokens (UI Login)¶

Generated when users log in via the Admin UI:

{
  "sub": "admin@example.com",
  "user": {
    "email": "admin@example.com",
    "is_admin": true
  },
  "token_use": "session",
  "iss": "mcpgateway",
  "aud": "mcpgateway-api",
  "exp": 1234567890
}

Behavior: Session tokens resolve teams server-side per request. For admin users, resolved teams become None (admin bypass). For non-admin users, resolved teams become their DB membership list (or [] if none).

API Tokens (Programmatic Access)¶

Generated via the Admin UI or API for automation:

{
  "sub": "service-account@example.com",
  "is_admin": false,
  "teams": ["team-uuid-1", "team-uuid-2"],
  "iss": "mcpgateway",
  "aud": "mcpgateway-api",
  "exp": 1234567890
}

Behavior: Access restricted to public resources plus resources owned by specified teams.

Scoped Automation Tokens¶

For CI/CD, monitoring, or public API access:

{
  "sub": "ci-pipeline@example.com",
  "is_admin": true,
  "teams": [],  // Explicitly empty = public-only
  "iss": "mcpgateway",
  "aud": "mcpgateway-api",
  "exp": 1234567890
}

Behavior: Even admin tokens with teams: [] are restricted to public resources only. This enables creating limited-scope tokens for automation that shouldn't access team-internal resources.

Generating Scoped Tokens¶

Using the CLI Tool¶

# Unrestricted admin-bypass API token (explicit teams=null + is_admin=true)
python3 -m mcpgateway.utils.create_jwt_token \
  --data '{"sub":"admin@example.com","is_admin":true,"teams":null,"token_use":"api"}' \
  --exp 60 \
  --secret $JWT_SECRET_KEY

# Team-scoped token
python3 -m mcpgateway.utils.create_jwt_token \
  --data '{"sub":"user@example.com","is_admin":false,"teams":["team-uuid-1"],"token_use":"api"}' \
  --exp 60 \
  --secret $JWT_SECRET_KEY

# Public-only scoped token (for automation)
python3 -m mcpgateway.utils.create_jwt_token \
  --data '{"sub":"ci@example.com","is_admin":false,"teams":[],"token_use":"api"}' \
  --exp 60 \
  --secret $JWT_SECRET_KEY

Using the Admin UI¶

1. Navigate to Admin UI → Tokens
2. Click Create Token

3. Select team scope:

4. No team selected: Public resources only (secure default)

5. Specific team(s): Team + public resources

6. Configure additional restrictions (IP, permissions, expiry)

Permission System¶

Permission Categories¶

Permissions are defined in the Permissions class and control what actions users can perform:

Permission Checking Flow¶

@require_permission("resource.action")
    │
    ▼
┌─────────────────────────────┐
│ Extract user_context        │ ← From request/kwargs
└─────────────────────────────┘
    │
    ▼
┌─────────────────────────────┐
│ Plugin Permission Hook      │ ← HTTP_AUTH_CHECK_PERMISSION can override
└─────────────────────────────┘
    │ (no plugin decision)
    ▼
┌─────────────────────────────┐
│ Admin Bypass Check          │ ← If allow_admin_bypass=True AND user.is_admin
└─────────────────────────────┘
    │ (not admin or bypass disabled)
    ▼
┌─────────────────────────────┐
│ Role Collection             │ ← Get all active roles for user
│ - Global scope roles        │
│ - Personal scope roles      │
│ - Team scope roles          │
└─────────────────────────────┘
    │
    ▼
┌─────────────────────────────┐
│ Permission Aggregation      │ ← Collect permissions from roles
│ - Include inherited perms   │   (role inheritance supported)
│ - Check for wildcard (*)    │
└─────────────────────────────┘
    │
    ▼
  GRANT or DENY

Explicit Team/Token Defaults¶

Team and token management behavior is now controlled through explicit role permissions, not implicit fallback checks.

Users without role assignments do not receive implicit team/token permissions.

Admin API RBAC¶

The Admin API enforces strict RBAC where even users with is_admin: true must have explicit permissions granted. This enables delegated administration - granting specific admin capabilities without full superuser access.

Key behaviors:

Example: Delegated Server Management

{
  "role": "server-manager",
  "permissions": [
    "servers.read",
    "servers.create",
    "servers.update",
    "servers.delete"
  ]
}

A user with this role can:

• ✅ Access /admin/servers/* endpoints
• ✅ View the Admin UI (has servers.* which satisfies has_admin_permission())
• ❌ Access /admin/tools/* endpoints (no tools.* permissions)
• ❌ Access /admin/gateways/* endpoints (no gateways.* permissions)

Configuration Safety¶

Development vs Production Settings¶

The following configuration combinations require careful consideration:

Proxy Authentication Mode¶

When MCP_CLIENT_AUTH_ENABLED=false and TRUST_PROXY_AUTH=true:

• The gateway trusts the X-Forwarded-User header from upstream proxy
• No JWT validation or database verification is performed
• Only use when deployed behind a trusted reverse proxy that handles authentication

Anonymous Mode (AUTH_REQUIRED=false)¶

When AUTH_REQUIRED=false:

• All unauthenticated requests receive platform-admin context
• Never use in production - all users have full admin access
• Intended only for local development and testing

Best Practices¶

Token Lifecycle¶

1. Use short expiration times for interactive sessions (hours)
2. Use longer expiration for service accounts with IP restrictions
3. Rotate tokens regularly (recommended: 90 days for long-lived tokens)
4. Revoke tokens immediately when access should be removed

Team Organization¶

1. Create purpose-specific teams:

2. platform-admins - Full administrative access

3. developers - Development and testing resources
4. ci-automation - CI/CD pipeline access

5. monitoring - Read-only observability access

6. Map SSO groups to teams for automatic membership management

7. Use personal teams for individual resource ownership

Scoping Strategy¶

Troubleshooting¶

Token Not Seeing Expected Resources¶

1. Check token claims: Decode the JWT to verify teams claim

   # Decode JWT payload (middle section)
   echo "$TOKEN" | cut -d. -f2 | base64 -d | jq .
   

2. Verify resource visibility: Check the resource's visibility and team_id

   curl -H "Authorization: Bearer $ADMIN_TOKEN" /tools/{id} | jq '{visibility, teamId}'
   

3. Check user admin status: Non-admin users without teams get public-only access

Admin Token Being Restricted¶

If an admin token is unexpectedly restricted:

1. Check for explicit teams claim: teams: [] restricts even admins
2. Verify is_admin flag: Must be true in JWT or database user
3. Check middleware logs: Look for "token_teams" in debug output

Inconsistent Results Between Endpoints¶

If REST and RPC endpoints return different results:

1. Check for caching: REST list endpoints may have cached data
2. Wait for cache TTL: Default is 60 seconds for registry cache
3. Use direct GET: /tools/{id} bypasses list cache

Bootstrap Custom Roles¶

ContextForge allows you to define custom roles that are automatically created during database bootstrap. This is useful for organizations that need to pre-configure roles before deployment.

Configuration¶

Enable custom role bootstrapping with these environment variables:

Role Definition Format¶

Create a JSON file containing an array of role definitions:

[
  {
    "name": "data_analyst",
    "description": "Read-only access for data analysis",
    "scope": "team",
    "permissions": ["tools.read", "resources.read", "prompts.read"],
    "is_system_role": true
  },
  {
    "name": "auditor",
    "description": "Compliance audit access",
    "scope": "global",
    "permissions": ["tools.read", "resources.read", "prompts.read", "servers.read", "gateways.read"],
    "is_system_role": true
  }
]

Required fields:

• name - Unique role name
• scope - Either team (team-level access) or global (system-wide access)
• permissions - Array of permission strings (e.g., tools.read, resources.create)

Optional fields:

• description - Human-readable description
• is_system_role - Set to true to prevent users from modifying/deleting the role

Available Permissions¶

Docker Compose Example¶

services:
  gateway:
    environment:
      - MCPGATEWAY_BOOTSTRAP_ROLES_IN_DB_ENABLED=true
      - MCPGATEWAY_BOOTSTRAP_ROLES_IN_DB_FILE=/app/custom_roles.json
    volumes:
      - ./custom_roles.json:/app/custom_roles.json:ro

Kubernetes/Helm Example¶

# values.yaml
mcpContextForge:
  env:
    MCPGATEWAY_BOOTSTRAP_ROLES_IN_DB_ENABLED: "true"
    MCPGATEWAY_BOOTSTRAP_ROLES_IN_DB_FILE: "/config/custom_roles.json"

  # Mount ConfigMap with role definitions
  extraVolumes:
    - name: custom-roles
      configMap:
        name: mcp-gateway-roles
  extraVolumeMounts:
    - name: custom-roles
      mountPath: /config

Error Handling¶

• File not found: Bootstrap continues with default roles only; warning logged
• Invalid JSON: Bootstrap continues with default roles only; error logged
• Malformed entries: Invalid role entries are skipped with warnings; valid entries are processed

Related Documentation¶

• Team Management - Setting up teams and SSO mapping
• Security Features - Comprehensive security configuration
• Configuration Reference - Environment variables
• API Usage - Token usage in API calls