Authentication & Authorization

MCP-Hangar supports enterprise-grade authentication (AuthN) and authorization (AuthZ) for secure multi-tenant access control.

Quick Start

Authentication is opt-in and disabled by default. To enable it:

1. Enable in Configuration

# config.yaml
auth:
  enabled: true  # Enable authentication
  allow_anonymous: false  # Require authentication for all requests

  api_key:
    enabled: true
    header_name: X-API-Key

2. Create an API Key

# Via the REST API (there is no auth CLI subcommand)
curl -X POST http://localhost:8000/api/auth/keys \
  -H "X-API-Key: <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "service:my-app",
    "name": "My App Key",
    "role": "developer"
  }'

# Response:
# {
#   "key": "mcp_aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
#   "principal": "service:my-app"
# }
# Save this key now - it cannot be retrieved later!

3. Use the API Key

# HTTP mode
curl -H "X-API-Key: mcp_aBcDeFgHiJkLmNoPqRsTuVwXyZ..." \
  http://localhost:8000/mcp

# Or in MCP client configuration
{
  "headers": {
    "X-API-Key": "mcp_aBcDeFgHiJkLmNoPqRsTuVwXyZ..."
  }
}

Authentication Methods

API Key Authentication

Simple key-based authentication. Keys are:

• Prefixed with mcp_ for easy identification
• Stored as SHA-256 hashes (never in plaintext)
• Support expiration and revocation

auth:
  api_key:
    enabled: true
    header_name: X-API-Key  # Can be customized

JWT/OIDC Authentication

For enterprise SSO integration with MCP servers like Okta, Auth0, Azure AD:

auth:
  oidc:
    enabled: true
    issuer: https://auth.company.com
    audience: mcp-hangar
    # Claim mappings (optional)
    groups_claim: groups
    tenant_claim: org_id

Since MCP Hangar 1.4.0, front-door deployments can trust multiple OIDC issuers and bind accepted JWT audiences to the public resource URI.

auth:
  enabled: true
  allow_anonymous: false
  oidc:
    enabled: true
    resource_uri: https://hangar.example.com
    tenant_claim: tenant_id
    issuers:
      - issuer: https://issuer-a.example.com
        audience: https://hangar.example.com
        jwks_uri: https://issuer-a.example.com/jwks
      - issuer: https://issuer-b.example.com
        audience: https://hangar.example.com
        jwks_uri: https://issuer-b.example.com/jwks
        groups_claim: roles

When resource_uri is set, Hangar validates each token's aud claim against that URI, regardless of the issuer entry's audience. This makes the value advertised as RFC 9728 resource the same value enforced as the RFC 8707 resource indicator. Without resource_uri, each issuer uses its own configured audience.

auth.oidc.issuers takes precedence over the legacy top-level issuer field. Per-issuer entries inherit omitted claim mappings from top-level oidc.* fields. Tokens with a missing, empty, non-string, or untrusted iss claim fail closed.

Authorization (RBAC)

Built-in Roles

Assigning Roles

Static (in config.yaml)

auth:
  role_assignments:
    - principal: "user:admin@company.com"
      role: admin
      scope: global

    - principal: "group:developers"
      role: developer
      scope: global

    # Tenant-scoped assignment
    - principal: "group:data-team"
      role: developer
      scope: "tenant:data-team"

Dynamic (via REST API)

curl -X POST http://localhost:8000/api/auth/roles/assign \
  -H "X-API-Key: <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "user:john@company.com",
    "role": "developer",
    "scope": "global"
  }'

Security Best Practices

1. Use HTTPS in Production

Always use HTTPS for MCP endpoints in production. The auth system will warn if OIDC issuer is not HTTPS.

2. Configure Trusted Proxies

If behind a load balancer, configure trusted proxies for correct client IP detection. Trusted proxies are set programmatically via FastMCPServerConfig:

from mcp_hangar.fastmcp_server.config import FastMCPServerConfig

config = FastMCPServerConfig(
    trusted_proxies=frozenset(["10.0.0.0/8", "172.16.0.0/12"]),
)

3. Rotate API Keys Regularly

Set expiration for API keys and rotate them periodically:

curl -X POST http://localhost:8000/api/auth/keys \
  -H "X-API-Key: <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "service:ci",
    "name": "CI Pipeline Key",
    "expires_in_days": 30
  }'

4. Use Tenant Isolation

For multi-tenant deployments, use tenant-scoped roles:

role_assignments:
  - principal: "group:team-alpha"
    role: developer
    scope: "tenant:alpha"

Monitoring

Auth events are emitted as domain events and can be monitored:

• AuthenticationSucceeded - Successful authentication
• AuthenticationFailed - Failed authentication attempt
• AuthorizationDenied - Access denied
• AuthorizationGranted - Access granted

These are logged and can be sent to your observability stack.

Troubleshooting

"No valid credentials provided"

• Check that auth.enabled: true is set
• Verify the X-API-Key header is being sent
• Ensure the key has the correct prefix (mcp_)

"Invalid API key"

• The key may have been revoked
• The key may have expired
• Check for typos in the key

"Access denied"

• The principal doesn't have the required role
• Check role assignments via the REST API (GET /api/auth/roles)
• Verify the scope matches

API Reference

Configuration Schema

auth:
  enabled: bool          # Master switch (default: false)
  allow_anonymous: bool  # Allow unauthenticated requests (default: false)

  api_key:
    enabled: bool        # Enable API key auth (default: true when auth enabled)
    header_name: str     # Header name (default: X-API-Key)

  oidc:
    enabled: bool        # Enable OIDC/JWT auth (default: false)
    issuer: str          # OIDC issuer URL
    audience: str        # Expected audience claim
    jwks_uri: str        # JWKS endpoint (auto-discovered if not set)
    resource_uri: str    # Public resource URI; also enforced as JWT aud when set
    subject_claim: str   # JWT claim for subject (default: sub)
    groups_claim: str    # JWT claim for groups (default: groups)
    tenant_claim: str    # JWT claim for tenant (default: tenant_id)
    issuers: []          # Multi-issuer trust entries; overrides top-level issuer

  opa:
    enabled: bool        # Enable OPA policy engine (default: false)
    url: str             # OPA server URL
    policy_path: str     # Policy decision path

  role_assignments: []   # Static role assignments