Configuring Keycloak¶

This guide describes the creation and configuration of a Keycloak Realm, Client, and Audience Mapper. It enables the Actian MCP Server to authenticate users through OAuth 2.0 and OpenID Connect (OIDC).

By the completion of this guide, you will have obtained the values that are required to populate the oauth block in the conf.json file. For the full configuration reference and shared concepts such as TLS, user impersonation, and security practices, see Authentication Overview.

Quick Start - Existing Keycloak User¶

If you are an experienced Keycloak user, use the following checklist to set up the environment:

1. Create a realm (or use an existing one).
2. Create a client with Client authentication enabled and record the Client ID and Client Secret.

3. Add an audience mapper using the Included Custom Audience field to show the audience string in the token's aud claim.

   Warning

   If you skip this step, the MCP Server rejects tokens with audience mismatch.

4. (Optional) Add a sub override mapper to the sub claim containing the username instead of a UUID.

5. Create users in the realm, if using user_impersonation: true.
6. Fill conf.json file with the values from Step 1 to Step 3.
7. Start the server with --transport sseor http / streamable-http.

Prerequisites - New Keycloak User¶

• A running Keycloak instance (version 22 or higher) is accessible by the MCP server.
• Admin access is granted to the Keycloak Admin Console.
• The Actian MCP Server is installed and ready for deployment.

Step 1: Create a Keycloak Realm¶

A Realm is an isolated container for managing users, credentials, and roles.

1. Log in to the Keycloak Admin Console http://<keycloak-host>:8080/admin.
2. In the top-left drop-down (displaying master), select Create Realm.

3. Fill the form as follows:

   Field	Value	Notes
   Realm name	actian-mcp	Any descriptive name; it appears in all OIDC URLs
   Enabled	On	NA

4. Select Create.

Output of Step 1¶

Step 2: Create a Keycloak Client¶

The client represents the MCP server’s OAuth credentials and holds client_id and client_secret.

1. In the Admin Console, select your realm from the drop-down.
2. Select Clients in the left panel.
3. Select Create client.

4. Fill the form as follows:

   Field	Value	Notes
   Client type	OpenID Connect	Default
   Client ID	actian-mcp	Becomes both FASTMCP_SERVER_AUTH_CLIENT_ID and FASTMCP_SERVER_AUTH_AUDIENCE (after audience mapper)

5. Select Next.

6. On the Capability config screen, configure the following values:

   Setting	Value	Notes
   Client authentication	On	Makes the client confidential and generates a client secret
   Authorization	Off	Not needed for basic OAuth
   Standard flow	Checked	Required for browser login
   Direct access grants	Checked	Required for testing only

   Disable direct access grants in production

   The password grant (direct access grants) is insecure for production use and only intended for local debugging with curl.

7. Select Next.

8. On the Login settings screen, configure the following values:

   Setting	Value	Notes
   Root URL	https://<mcp-server-host>:8000	MCP server's external URL
   Valid redirect URIs	https://<mcp-server-host>:8000/*	Must match the server's external URL
   Web origins	https://<mcp-server-host>:8000	For CORS

9. Select Save.

Get the Client Secret¶

1. After creating the client, select the Credentials tab.
2. Copy the Client secret value.

Output of Step 2¶

Step 3: Add the Audience Mapper (Required)¶

By default, Keycloak tokens only include internal audiences like account. The MCP server validates that the token's aud claim matches the configured FASTMCP_SERVER_AUTH_AUDIENCE value. You must inform Keycloak to include the audience string in the token.

1. Navigate to Clients and select your client, for example, actian-mcp.
2. Select the Client scopes tab.
3. Select the actian-mcp-dedicated link (listed as "Dedicated"). If you do not see the dedicated scope, check the Mappers tab directly.
4. Select Configure a new mapper or Add Mapper.

5. Select Audience (not Audience Resolve) from the list.

   Audience versus Audience Resolve

   "Audience Resolve" is a different mapper that resolves audiences dynamically. It does not hardcode your audience into aud. Therefore, you are required to select Audience mapper.

6. Configure the following fields:

   Field	Value	Notes
   Name	audience-mapping	Provide a descriptive name.
   Included Client Audience	(leave empty)	Do not use this field. It resolves to an internal UUID.
   Included Custom Audience	actian-mcp	The literal string that must match FASTMCP_SERVER_AUTH_AUDIENCE in the conf.json file.
   Add to ID token	Off	This field is not required.
   Add to access token	On	Required - the MCP server checks the access token.

7. Select Save.

Verification¶

After adding the mapper, request a new token and decode it. The aud claim includes the audience string:

# Request a token
TOKEN=$(curl -s -X POST \
  "http://<keycloak-host>:8080/realms/actian-mcp/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=actian-mcp" \
  -d "client_secret=<your-secret>" | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# Decode and inspect the aud claim
echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool | grep aud

Expected output:

"aud": ["actian-mcp", "account"]

Step 4 (Optional): Add the Sub Override Mapper¶

By default, Keycloak sets the sub claim to a UUID. You can override it to contain the login name for easier user_impersonation mapping.

1. Navigate to Clients > your client > Client scopes tab.
2. Select the actian-mcp-dedicated link.
3. Select Configure a new mapper > User Property.

4. Configure the following fields:

   Field	Value	Notes
   Name	sub-override	Acts as a label
   Property	username	Maps the login name
   Token Claim Name	sub	Overwrites the standard sub field
   Claim JSON Type	String	NA
   Add to ID token	On	NA
   Add to access token	On	NA

5. Select Save.

Verification¶

After adding the mapper, the token contains the following:

{
  "sub": "jdoe",
  "iss": "http://<keycloak-host>:8080/realms/actian-mcp",
  "aud": ["realm-management", "account", "actian-mcp"],
  "preferred_username": "jdoe",
  "scope": "openid email profile"
}

Step 5: Create Keycloak Users (If Using User Impersonation)¶

If user_impersonation is true, each Keycloak user contains a matching database account. For more information, see User Impersonation.

1. Navigate to Users in the left panel.
2. Select Add user.

3. Fill the form as follows:

   Field	Value	Notes
   Username	jdoe	Must match with the database account name
   Email	jdoe@example.com	Optional but recommended
   First Name	John	Optional
   Last Name	Doe	Optional
   Enabled	On	NA

4. Select Create.

5. Navigate to the Credentials tab > Set password > enter a password > toggle Temporary to Off > Save.

Creating Matching Database User¶

-- Create the user account (no DB password needed — Keycloak handles authentication)
CREATE USER jdoe;

-- Grant access to the database
GRANT ACCESS ON DATABASE mydb TO jdoe;

-- Grant the necessary table permissions (adjust per your schema)
GRANT SELECT ON TABLE orders TO jdoe;
GRANT SELECT ON TABLE products TO jdoe;

Step 6: Assemble the Final Configuration¶

Mapping Summary¶

Example conf.json¶

{
    "driver": "{Ingres}",
    "server": "@<db-host>,tcp_ip,<port>",
    "database": "mydb",
    "database_user": "<database_user>",
    "database_password": "<database_password>",
    "max_connections": 10,
    "host": "0.0.0.0",
    "port": 8000,
    "ssl_certfile": "/app/server.crt",
    "ssl_keyfile":  "/app/server.key",
    "oauth": {
        "FASTMCP_SERVER_AUTH_CONFIG_URL": "http://<keycloak-host>:8080/realms/actian-mcp/.well-known/openid-configuration",
        "FASTMCP_SERVER_AUTH_CLIENT_ID": "actian-mcp",
        "FASTMCP_SERVER_AUTH_CLIENT_SECRET": "<your-client-secret>",
        "FASTMCP_SERVER_AUTH_BASE_URL": "https://<mcp-server-host>:8000",
        "FASTMCP_SERVER_AUTH_AUDIENCE": "actian-mcp",
        "user_impersonation": true
    }
}

For TLS setup details (certificate generation, Docker deployment, trusting self-signed certifications), see HTTPS / TLS for Remote Deployments.

For security best practices (file permissions, .gitignore, secrets management), see Security Best Practices.

Verify End-to-End¶

After starting the MCP server container with OAuth configured:

1. Open a browser and navigate to the server's /mcp endpoint, for example, https://<mcp-server-host>:8000/mcp.
2. You are redirected to the Keycloak login page.
3. Log in with a Keycloak user, for example, jdoe.
4. After logging in, Keycloak redirects you back to the MCP server with a valid token.
5. Check server logs for Stored database username: jdoe to confirm user impersonation is active.

Troubleshooting¶

Verify OIDC Discovery Endpoint¶

curl http://<keycloak-host>:8080/realms/actian-mcp/.well-known/openid-configuration \
  | python3 -m json.tool

Verify Token Contents (Development Only)¶

curl -s -X POST \
  http://<keycloak-host>:8080/realms/actian-mcp/protocol/openid-connect/token \
  -d "grant_type=password" \
  -d "client_id=actian-mcp" \
  -d "client_secret=your-secret" \
  -d "username=jdoe" \
  -d "password=secret" \
  -d "scope=openid email profile" \
  | python3 -m json.tool

Decode the access_token at jwt.io and verify the following:

• aud contains Client ID, for example, actian-mcp.
• sub contains the username (if you added the sub override mapper) or a UUID.
• preferred_username contains the login name.

Common Errors¶

Token Expiration¶

Keycloak tokens have a configurable lifetime:

1. Navigate to Realm Settings > Tokens tab.

2. Do the following key settings:

   Setting	Default	Notes
   Access Token Lifespan	5 minutes	Increase for long-running MCP sessions, for example, 1 hour
   SSO Session Idle	30 minutes	How long before an idle session expires
   SSO Session Max	10 hours	Maximum session duration

3. Adjust as needed and select Save.

Keycloak versus Auth0 - Key Differences¶

Staging versus Production¶