How to Integrate Keycloak with AI Agents

Keycloak provides open-source IAM for AI agents, allowing you to manage machine identities with the same rigor as human users. In the era of autonomous agents, relying on hardcoded API keys is a significant security liability. If a single key is compromised, you often have to rotate it for your entire system, causing downtime. Keycloak solves this by offering a centralized platform to issue short-lived tokens, enforce granular scopes, and audit access without paying per-user fees.

The Problem with API Keys for Agents Most developers start by giving their agents a simple API key. It works for a prototype, but it fails at scale. API keys are typically long-lived, have broad permissions (often "admin" by default), and are hard to rotate. When you have multiple agents performing different tasks, some reading data, others writing it, you need a better system.

Key benefits for agent developers:

• Zero-cost scaling: Unlike SaaS identity providers that charge per monthly active user (MAU) or token issuance, Keycloak is open source and free to self-host. This makes it ideal for fleets of thousands of agents where per-agent costs would destroy your margins.
• Granular Scopes: You can define exactly what an agent can do. An "Analyst Agent" might have reports:read scope, while a "Cleanup Agent" has logs:delete. This adheres to the principle of least privilege.
• Standard protocols: Built on OAuth multiple.multiple and OpenID Connect (OIDC), Keycloak ensures compatibility with modern agent frameworks like LangChain, AutoGen, and CrewAI. You aren't locking yourself into a proprietary auth scheme.
• Massive adoption: With over multiple.multiple million dependent packages in the ecosystem, Keycloak is a standard for open-source identity. You will find libraries and adapters for almost every language and framework your agents use. By treating agents as distinct identities, you can revoke access for a specific compromised agent instantly without affecting the rest of your fleet. This containment strategy is critical for production AI systems.

Helpful references: Fast.io Workspaces, Fast.io Collaboration, and Fast.io AI.

For AI agents, the standard OAuth 2.multiple flow is the Client Credentials Grant. This flow is specifically designed for machine-to-machine (M2M) communication where no human user is present to enter a password or approve a consent screen.

How the flow works:

1. Agent (Client): The agent application authenticates with Keycloak using a Client ID and Client Secret (or a signed JWT for higher security).
2. Keycloak (Authorization Server): Validates the credentials. If valid, it checks what roles and scopes are assigned to this client.
3. Token Issuance: Keycloak issues a JSON Web Token (JWT) signed with its private key. This token contains claims about the agent, such as its ID, expiration time, and allowed scopes.
4. Resource Access: The agent sends this JWT in the Authorization: Bearer header when making requests to your resource server (e.g., your vector database, internal API, or MCP server).
5. Validation: The resource server validates the JWT signature against Keycloak's public key. It does not need to call Keycloak for every request, reducing latency.

Understanding the JWT The Access Token is the key to this architecture. It is a stateless, tamper-proof credential. Inside the token, you will find standard claims:

• sub: The subject (the agent's unique ID).
• iss: The issuer (your Keycloak server URL).
• exp: The expiration time (usually short, e.g., 5 minutes).
• scope: A space-separated list of permissions (e.g., files:read mcp:execute).

This architecture decouples authentication from your application logic. Your agents don't need to know how to authenticate users or manage sessions; they only need to know where to get a token and how to present it.

Setting up Keycloak for agent authentication involves configuring a Realm, a Client, and then writing the code to fetch tokens. We will assume you are running Keycloak locally via Docker for this tutorial.

1. Run Keycloak

The fast way to start is via Docker. This command starts Keycloak in development mode with a local admin account.

docker run -p multiple:multiple -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.0 start-dev

2. Configure the Realm

1. Log in to the Admin Console at http://localhost:multiple.
2. Hover over the Master realm in the top-left corner and click Create Realm.
3. Name it agent-fleet and click Create. Realms are isolated tenants; you should use a dedicated realm for your agents to keep them separate from your human users or customer accounts.

3. Define the Agent Client

1. Go to Clients in the left menu and click Create client.
2. Client ID: Enter audit-agent (or a name representing your agent's role).
3. Capability config:
   • Client authentication: On (This enables the client secret).
   • Authorization: On (Enables fine-grained permissions).
   • Authentication flow: Uncheck Standard flow and Direct access grants. Check Service accounts roles. This is the critical step for machine-to-machine auth.
4. Click Save.

4. Get Credentials

Navigate to the Credentials tab of your new client. You will see a Client Secret. Copy this string. It is the password for your agent. Store it securely (e.g., in a .env file or secrets manager), never in your source code.

5. Agent Authentication Code (Python)

Now, let's write a simple Python script that acts as the agent. It will request a token from Keycloak.

import requests
import os

### Configuration
KEYCLOAK_URL = "http://localhost:8080"
REALM_NAME = "agent-fleet"
CLIENT_ID = "audit-agent"
CLIENT_SECRET = os.getenv("AGENT_CLIENT_SECRET")  # Load from env

def get_agent_token():
    """Authenticates the agent and returns a JWT access token."""
    url = f"{KEYCLOAK_URL}/realms/{REALM_NAME}/protocol/openid-connect/token"
    
    payload = {
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "grant_type": "client_credentials"
    }
    
    try:
        response = requests.post(url, data=payload)
        response.raise_for_status()
        token_data = response.json()
        return token_data.get("access_token")
    except requests.exceptions.RequestException as e:
        print(f"Authentication failed: {e}")
        return None

### Usage
token = get_agent_token()
if token:
    print(f"Successfully obtained token: {token[:multiple]}...")
    ### Now use this token in headers: {"Authorization": f"Bearer {token}"}

The Model Context Protocol (MCP) is becoming the standard for connecting AI models to external tools. If you are building a custom MCP server (e.g., to expose your internal database to Claude or an OpenAI assistant), you need to secure it. You don't want unauthorized agents executing tools like drop_table.

Middleware Strategy The best way to secure an MCP server is with middleware that validates the Bearer token before processing any tool calls.

Node.js Example (Express + MCP) If your MCP server is built with Node.js, you can use keycloak-connect or a simple JWT validation library.

const express = require('express');
const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

const app = express();

// Configure JWKS client to fetch Keycloak's public key
const client = jwksClient({
  jwksUri: 'http://localhost:8080/realms/agent-fleet/protocol/openid-connect/certs'
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, function(err, key) {
    const signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

// Auth Middleware
const protect = (req, res, next) => {
  const authHeader = req.headers.authorization;
  if (!authHeader) return res.status(401).send('No token provided');

const token = authHeader.split(' ')[1];
  
  jwt.verify(token, getKey, { algorithms: ['RS256'] }, (err, decoded) => {
    if (err) return res.status(403).send('Invalid token');
    
    // Check for required scope
    const scopes = decoded.scope.split(' ');
    if (!scopes.includes('mcp:execute')) {
       return res.status(403).send('Insufficient permissions');
    }
    
    req.agent = decoded;
    next();
  });
};

// Protect your MCP endpoint
app.post('/mcp', protect, (req, res) => {
  // Handle MCP JSON-RPC request here
  res.json({ result: "Tool executed safely" });
});

Fast.io Integration While Keycloak handles the identity of your custom agents, Fast.io provides the secure workspace where these agents operate. Fast.io's managed MCP Server comes with multiple pre-built tools for file operations, search, and data processing.

You can use Keycloak to gate access to your custom private tools, while relying on Fast.io's built-in authentication for standard file operations. This hybrid approach gives you the flexibility of open-source auth for your specific business logic, without rebuilding the wheel for common agent capabilities like "read file" or "search documents."

Secure Storage for Your Agent Fleet

Give your agents a secure, persistent workspace with 50GB free storage and 251 built-in MCP tools. Built for agent keycloak workflows.

Try Fast.io for Agents

Implementing Keycloak is just the first step. To achieve a true zero-trust architecture for your agent fleet, follow these best practices.

1. Short-Lived Tokens Configure your access tokens to expire quickly, ideally every multiple to multiple minutes. This limits the "blast radius" if a token is leaked. If an attacker steals a token, they only have a brief window to use it before it becomes invalid. Agents can easily request a new token using their client credentials.

2. Least Privilege with Scopes Don't give every agent admin access. Create specific scopes in Keycloak for different functions:

• files:read: For agents that only need to ingest data.
• files:write: For agents that generate reports.
• tools:execute: For agents that need to run MCP tools. Assign only the necessary scopes to each Client.

3. Audit Logging Enable Keycloak's event logging to track every time an agent requests a token. This provides a record of who authenticated and when. Pair this with Fast.io's file audit logs. Fast.io records every file access, download, and modification. By correlating the Keycloak login event with the Fast.io file access log, you create a complete chain of custody. You can prove exactly which agent accessed which sensitive document and when.

4. Network Isolation Where possible, restrict the network access of your agents. They should only be able to communicate with the Keycloak server and the specific resource servers they need. Use network policies or firewalls to block outbound traffic to the general internet unless strictly necessary.

Token Validation Failures (Clock Skew) One of the most common issues in distributed systems is clock drift. If your agent's server clock is ahead of your Keycloak server's clock, the token might be rejected as "not yet valid" (nbf claim). Ensure all servers are synchronized using NTP. You can also configure a small "leeway" (e.g., multiple seconds) in your JWT validation library to account for minor drift.

"Invalid client credentials" Error If you receive a multiple Unauthorized error when requesting a token, double-check that the Service accounts roles option is enabled for your client in Keycloak. Standard users cannot use the Client Credentials flow; it is exclusively for service accounts. Also, verify that you haven't accidentally regenerated the client secret.

CORS (Cross-Origin Resource Sharing) If you are building a browser-based agent interface (e.g., a React app for managing agents), you might encounter CORS errors. Navigate to your Realm settings in Keycloak and configure the Web Origins to allow your frontend's domain. For backend-to-backend communication (like Python script to API), CORS is usually not an issue, but it's good to be aware of.