Authentication & Authorization for AI apps (Keycloak + lightspeed core + Kubernetes MCP)

Unified Security System for Secure AI App

This document details the inner workings of a secure AI application's unified security system, protecting both its web interface and underlying AI services. The system leverages Keycloak for authentication and implements token exchange for authorization across various services like Llama Stack and MCP.

Authentication: Proving Identity

• Delegation to Keycloak: To avoid the complexity and risks of building user password and account management from scratch, the AI app delegates authentication to Keycloak, a professional identity management service. This ensures security best practices are followed without the need to store user credentials directly.
• OpenID Connect (OIDC): The system utilizes OIDC, where users are authenticated through a trusted third-party service. In this case, Keycloak serves as the identity provider, similar to how Google was used in a previous demonstration.
• Keycloak Configuration: Keycloak manages user accounts, such as "Lance" and "Admin," with their associated emails and passwords.
• JWT Tokens: Upon successful login to the AI app, users are actually logging into Keycloak. The app then receives a secure JSON Web Token (JWT) that serves as proof of identity. This token contains:
  • Header: Metadata about the token, including the signing algorithm and token type.
  • Payload: Claims about the user, including their permissions.
  • Signature: A cryptographic signature to ensure the token's integrity and prevent tampering.
• Performance and Security: Services can validate JWT tokens independently without constantly querying Keycloak, enhancing both security and performance.

Authorization: Controlling Access

• Unified System for Multiple Services: The AI app interfaces with Llama Stack and MCP, separate services that require their own protection. A unified authentication system prevents malicious users from bypassing the web interface and directly accessing these services. It also avoids the poor user experience of multiple logins.
• Token Exchange v2: This mechanism is employed to achieve unified authentication across services.
• Configuration:
  • Llama Stack: Authentication setup involves a few configuration fields in the run.yaml file.
  • MCP: The fast MCP service was modified to enforce authentication before accessing any tools.
• Roles, Policies, and Scopes: Authorization is managed through roles, policies, and scopes defined within Keycloak's authorization system.
• Principle of Least Privilege: The best practice is to start with minimal permissions and grant more as needed, analogous to a hotel key granting basic access, with further access requiring upgrades.
• Token Exchange for Permissions:
  • Initially, users receive tokens with minimal scopes upon authentication, sufficient only to prove identity.
  • As users interact with the chat interface, tokens are automatically exchanged for additional permissions.
• Llama Stack Scope Configuration:
  • llama models read: Required to list available models.
  • llama agents write: Required to create agents.
• MCP Scope Configuration:
  • MCP server creators can define required scopes for each tool.
  • Example: The list files tool requires the MCP list files scope.
• Custom Agent for MCP Authorization Errors: A custom agent, soon to be part of Lightseed Core, handles MCP authorization errors.
• Demonstration of Token Exchange: When a user says "hello" in the chat:
  1. The Llama Stack token undergoes several exchanges: to list models, then to get tools, and finally to create agents. Each exchange adds specific scopes.
  2. The MCP token begins with an authentication scope, allowing the agent to discover tools.
  3. When a tool call is initiated (e.g., listing files), the token is exchanged for the specific scope required for that operation.
• User Transparency: The token exchange process is transparent to users. Without a token dashboard, users are unaware of the underlying security operations. Developers will benefit from this complexity being handled by Llama Stack, Fast MCP, and the Lightseed Core agent.

Handling External Service Authentication (e.g., Kubernetes)

• Reimplementation in Golang: To integrate with services like Kubernetes that require their own OIDC, the Fast MCP changes were reimplemented in Golang.
• Impersonation: The Kubernetes MCP server impersonates the calling user. The JWT token's identity is used to restrict Kubernetes API calls to only those the user has access to.
• Demo Scenario:
  • Lance, a user with access only to the default namespace in Kubernetes, is also present in Keycloak.
  • Requesting to list pods in the default namespace succeeds because the Kubernetes OIDC server verifies Lance's permissions.
  • Requesting to list pods in another namespace is rejected by Kubernetes, even though the MCP tool is accessible.

Key Architectural Decisions and Alternatives

The development process involved several key architectural decisions with alternative approaches considered:

1. Llama Stack Client per User:

   • Current Implementation: One Llama Stack client per user, assuming the user's identity.
   • Alternative: A global Llama Stack client with its own authorization, spinning up agents that assume user identities.

2. Token Exchange Location for MCP Authorization:

   • Current Implementation: Token exchange for MCP authorization occurs in the client app, allowing for user approval prompts.
   • Alternatives:
     • Token exchange by the Llama client or agent.
     • Token exchange by the MCP server itself.

3. Llama Stack API Access:

   • Current Implementation: Llama Stack client handles token exchange for Llama Stack APIs automatically.
   • Alternative: Define logic to surface OIDC errors back to the client app for token exchange (would require significant refactoring of the Llama client).

4. Tool Exposure to LLM:

   • Current Implementation: Lists all available tools the MCP server can access after authentication; relies on the agent to determine tool access.
   • Alternative: Add only tools theoretically accessible to the user based on their role to the agent's context, reducing exposed tools.

5. Kubernetes API Access:

   • Current Implementation: Implemented impersonation so the MCP server accesses Kubernetes APIs based on user permissions.
   • Alternatives:
     • Pass the user's token directly to Kubernetes.
     • Have the user service account create a new token for itself.
     • Have the MCP server create tokens on behalf of users.
     • Have the MCP server check user permissions and act with its own credentials.

6. Authentication Handling:

   • Current Implementation: Authentication handled directly at the MCP server level for performance and simplicity.
   • Alternative: Rely on an MCP gateway (considered to add latency, configuration, and security complexity).

Acknowledgements

• Jason Smith: For assistance with OIDC questions.
• Aldrau: For contributions to the Kubernetes MCP server.
• Andrew Block: For insights into Keycloak's capabilities.

Key Concepts

• Authentication: Verifying a user's identity.
• Authorization: Determining what an authenticated user is allowed to do.
• Keycloak: An open-source identity and access management solution.
• OpenID Connect (OIDC): An identity layer on top of the OAuth 2.0 protocol, used for authentication.
• JSON Web Token (JWT): A compact, URL-safe means of representing claims to be transferred between two parties.
• Header (JWT): Contains metadata about the token.
• Payload (JWT): Contains claims about the user and their permissions.
• Signature (JWT): Cryptographically verifies the token's integrity.
• Llama Stack: A framework for building and deploying large language models.
• MCP (Model Communication Protocol): A protocol for communication between AI models and services.
• Token Exchange: A process where an existing token is exchanged for a new one with different scopes or permissions.
• Scopes: Permissions granted to a user or application.
• Impersonation: Acting as another user.
• Principle of Least Privilege: Granting only the necessary permissions.