Authentication and Authorisation - cturner8/kube-mcp GitHub Wiki

To ensure secure access to the MCP server, integration with an OIDC (OpenID Connect) authentication provider is required. The server implements OAuth 2.0 Bearer Token authentication using JWT (JSON Web Tokens) validated against your OIDC provider.

The kube-mcp server validates bearer tokens on every request by:

1. Extracting the JWT from the Authorization: Bearer <token> header
2. Validating the token signature using JWKS (JSON Web Key Set) from the OIDC issuer
3. Verifying token claims including issuer, audience (client ID), and expiration
4. Checking for required scopes (if configured)
5. Caching JWKS keys for 5 minutes to improve performance

Authentication is always enforced, with the exception of the following HTTP routes:

• /health: Server health check route - used for liveness and readiness probes
• /.well-known/oauth-protected-resource: Serves Protected Resource Metadata (PRM) configuration to MCP clients

Any OIDC compliant issuer can be used for authentication. The only requirement is that the issuer must expose an OpenID Configuration endpoint (typically available at /.well-known/openid-configuration).

Some example OIDC compliant issuers:

• Microsoft Entra ID (Azure AD): https://login.microsoftonline.com/{tenant}/v2.0
• Google: https://accounts.google.com
• Okta: https://{yourcompany}.okta.com
• Auth0: https://{yourcompany}.auth0.com
• Keycloak: https://{yourcompany}/auth/realms/{realm}

Append /.well-known/openid-configuration to the issuer URL to view the OpenID Configuration. This will help determine:

• Available scopes
• Supported signing algorithms (e.g., RS256, HS256)

kube-mcp supports the following JWT signing methods:

• RS256 (RSA Signature with SHA-256)
• HS256 (HMAC with SHA-256)

Configure the signing method in your Helm values to match your OIDC provider's configuration.

User based authentication is currently tied to a single OIDC client, so user access control should be managed by:

1. OIDC Client Assignment: Control which users or groups have access by assigning them to the OIDC client in your identity provider
2. Scope Requirements: Configure required scopes that users must consent to during authentication
3. Tool Restrictions: Use the mcp.tools.allowed or mcp.tools.disallowed Helm values to control which MCP tools are available

• Tool access restrictions apply globally to all authenticated users (no per-user tool permissions)
• Only a single OIDC client is supported per deployment
• Scope validation is performed but does not affect tool availability

For more granular resource-level access control within Kubernetes, see RBAC.

If supported by your OIDC issuer, you can configure additional custom scopes to better communicate to users the access they are granting during the authentication consent process.

Configure scopes in your Helm values:

mcp:
  oidc:
    scopes: "openid,profile,email,mcp"

The openid scope is required by the OIDC specification. Additional scopes like profile, email, or custom scopes (e.g., mcp, k8s:read) can be added as comma-separated values.

To use custom scopes:

1. Register the custom scope in your OIDC provider (e.g., create an mcp scope in Entra ID, Okta, or Auth0)
2. Configure the scope to include relevant claims in the JWT token
3. Assign the scope to your OIDC client application
4. Add the scope to the mcp.oidc.scopes configuration

kube-mcp implements Protected Resource Metadata (PRM) discovery of the MCP specification to provide users with an interactive authentication that does not require any static API keys or tokens to be configured in advance.

This relies on the following:

• A PRM configuration available at /.well-known/oauth-protected-resource. This provides the required authentication metadata to MCP clients, allowing them to initiate an authentication flow. Example PRM configuration:

  {
    "resource": "https://mcp.example.com",
    "authorization_servers": ["https://auth.example.com"],
    "scopes_supported": ["mcp"]
  }

• A WWW-Authenticate header returned in non-authenticated responses which points to the above PRM configuration. Example unauthorised response:

  HTTP/1.1 401 Unauthorized
  WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                       scope="mcp"
  

• An MCP client that supports PRM discovery

For more information, see Protected Resource Metadata Discovery Requirements from the MCP specification.