Authentication

Secure your MCP server with JWT and Keycloak SSO

Overview

MCP Server with LangGraph supports pluggable authentication with two built-in providers:

InMemory Provider

Development & Testing

Pre-defined users for local development. Fast, zero-config.

Keycloak SSO

Production

Enterprise OpenID Connect/OAuth2 authentication. NEW in v2.1.0 🆕

Quick Start

InMemory Authentication (Development)

Perfect for local development and testing:

## .env configuration
AUTH_PROVIDER=inmemory
AUTH_MODE=token  # JWT tokens

Pre-defined users:

• alice - Premium user, admin of organization:acme
• bob - Standard user, member of organization:acme
• admin - System administrator

Get Token

from mcp_server_langgraph.auth.middleware import AuthMiddleware

auth = AuthMiddleware()
token = auth.create_token("alice", expires_in=3600)
print(f"Token: {token}")

Never use InMemory provider in production! It has hard-coded credentials and no real authentication.

Keycloak SSO (Production) 🆕

NEW in v2.1.0: Enterprise-grade authentication with Keycloak.

Features

OpenID Connect / OAuth2

Standards-compliant OIDC/OAuth2 flows with authorization code grant and refresh tokens.

Single Sign-On (SSO)

Centralized identity management across all applications in your organization.

JWKS Verification

Public key verification without shared secrets. Token validation using Keycloak’s JWKS endpoint.

Token Refresh

Automatic refresh token rotation for long-lived sessions without re-authentication.

Role Mapping

Flexible role and group mapping from Keycloak to OpenFGA permissions.

Setup

1. Deploy Keycloak

   # Docker Compose (development)
   docker compose up -d keycloak
   
   # Or deploy to Kubernetes
   helm install keycloak bitnami/keycloak \
     --namespace mcp-server-langgraph \
     --set replicaCount=2 \
     --set postgresql.enabled=true
   

   Access Keycloak admin console:

   • Docker: http://localhost:8080/admin (admin/admin)
   • Kubernetes: Port-forward and access
2. Initialize Keycloak

   Run the setup script to create realm and client:

   python scripts/setup/setup_keycloak.py
   

   This creates:

   • Realm: mcp-server-langgraph
   • Client: langgraph-client (confidential, OIDC)
   • Redirect URIs: Configured for your domain

   Save the client secret from the output.

3. Configure Environment

   # .env or Kubernetes ConfigMap
   AUTH_PROVIDER=keycloak
   AUTH_MODE=session  # or token
   
   KEYCLOAK_SERVER_URL=https://sso.yourdomain.com
   KEYCLOAK_REALM=mcp-server-langgraph
   KEYCLOAK_CLIENT_ID=langgraph-client
   KEYCLOAK_CLIENT_SECRET=your-client-secret-here
   KEYCLOAK_VERIFY_SSL=true  # Required for production
   
4. Test Authentication

   from mcp_server_langgraph.auth.keycloak import KeycloakClient
   
   client = KeycloakClient()
   
   # Authenticate user
   result = await client.authenticate("alice", "password")
   print(f"Access Token: {result['access_token']}")
   print(f"Refresh Token: {result['refresh_token']}")
   
   # Verify token
   user_info = await client.get_user_info(result['access_token'])
   print(f"User: {user_info}")
   

Authentication Modes

Token Mode (Stateless)

Overview

JWT tokens issued by Keycloak or InMemory provider.

Benefits:

• Stateless (no server-side session storage)
• Works with Cloud Run and other serverless platforms
• Lower infrastructure costs (no Redis required)

Trade-offs:

• Shorter token lifetimes (refresh required)
• No concurrent session limits
• Cannot revoke individual tokens

Configuration

# Token-based authentication
AUTH_MODE=token
JWT_SECRET_KEY=your-secret-key-here
JWT_EXPIRATION_SECONDS=3600  # 1 hour

With Keycloak:

AUTH_PROVIDER=keycloak
AUTH_MODE=token
# Tokens validated via Keycloak JWKS

Usage

# Get access token
token = auth.create_token("alice")

# Use in requests
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(url, headers=headers)

# Token refresh (Keycloak only)
new_tokens = await keycloak.refresh_token(refresh_token)

Session Mode (Stateful) 🆕

Overview

Server-side sessions with Redis or in-memory storage.

Benefits:

• Longer session lifetimes (24+ hours)
• Sliding expiration windows
• Concurrent session limits per user
• Instant session revocation
• User session tracking

Requirements:

• Redis instance (production)
• Or in-memory storage (development only)

Configuration

# Session-based authentication
AUTH_MODE=session
SESSION_BACKEND=redis  # or memory

# Redis configuration
REDIS_URL=redis://redis-session:6379/0
REDIS_PASSWORD=your-redis-password
REDIS_SSL=true  # For production

# Session settings
SESSION_TTL_SECONDS=86400  # 24 hours
SESSION_SLIDING_WINDOW=true  # Extend on activity
SESSION_MAX_CONCURRENT=5  # Per user

Usage

# Create session
session = await auth.create_session(
    user_id="alice",
    metadata={"ip": "192.168.1.1"}
)
print(f"Session ID: {session.session_id}")

# Get session
session = await auth.get_session(session_id)

# Refresh session (extends TTL)
session = await auth.refresh_session(session_id)

# Revoke session
await auth.revoke_session(session_id)

# Revoke all user sessions
await auth.revoke_user_sessions("alice")

Security Best Practices

Production Checklist

• Use Keycloak (not InMemory)
• Set KEYCLOAK_VERIFY_SSL=true
• Use strong JWT secret (256-bit): openssl rand -base64 32
• Enable session mode with Redis for sensitive applications
• Configure appropriate token/session TTLs
• Enable HTTPS/TLS for all endpoints
• Store secrets in secret manager (not .env files)
• Rotate secrets regularly
• Monitor authentication failures
• Set up rate limiting

Token Security

JWT Tokens:

• Use HS256 or RS256 algorithm
• Set reasonable expiration (1-4 hours)
• Include user ID and permissions
• Validate signature on every request
• Don’t store sensitive data in tokens

Refresh Tokens (Keycloak):

• Longer TTL than access tokens
• Rotate on refresh
• Revoke on logout
• Secure storage (HttpOnly cookies)

Session Security

Redis Sessions:

• Use password authentication
• Enable TLS/SSL in production
• Set appropriate TTL (balance UX vs security)
• Implement sliding windows carefully
• Limit concurrent sessions per user
• Clear sessions on password change
• Monitor session creation rate

Keycloak Hardening

• Deploy with PostgreSQL (not H2)
• Enable SSL/TLS
• Use strong admin password
• Configure proper redirect URIs
• Enable brute force protection
• Set up backup and recovery
• Regular security updates
• Monitor admin console access

Troubleshooting

Invalid credentials

Symptom: 401 Unauthorized

Solutions:

# Check InMemory users
python -c "from mcp_server_langgraph.auth.middleware import InMemoryUserProvider; print(InMemoryUserProvider().users)"

# Verify Keycloak connectivity
curl https://sso.yourdomain.com/realms/mcp-server-langgraph/.well-known/openid-configuration

# Check environment variables
env | grep AUTH
env | grep KEYCLOAK

Token expired

Symptom: 401 Unauthorized - Token expired

Solutions:

• Request new token
• Use refresh token (Keycloak)
• Increase JWT_EXPIRATION_SECONDS
• Enable session mode with longer TTL

Keycloak connection refused

Symptom: Connection refused to Keycloak

Solutions:

# Check Keycloak status
docker compose ps keycloak  # Docker
kubectl get pods -l app=keycloak  # Kubernetes

# Test connectivity
curl http://keycloak:8080/health

# Check logs
docker compose logs keycloak
kubectl logs -l app=keycloak

Session not found

Symptom: Session not found errors

Solutions:

• Check Redis connectivity
• Verify SESSION_TTL_SECONDS not too short
• Check session was created successfully
• Verify session ID format
• Check Redis memory not full

Next Steps

Authorization

Configure OpenFGA fine-grained permissions

Keycloak Guide

Complete Keycloak integration guide

Session Management

Setup Redis session store

API Reference

Authentication API endpoints

---

Production Ready: With Keycloak SSO and Redis sessions, your authentication is enterprise-grade!