Bitrix MCP: Keycloak identity and Vault credentials

This is a Streamable HTTP MCP server for working with Bitrix24 from OpenWebUI. It does not accept Bitrix tokens from OpenWebUI, tool arguments, headers, or the LLM. Every MCP request must carry a Keycloak access token. The server verifies it and uses its verified sub as the only user identity. Bitrix access and refresh tokens stay in Vault and are never returned to OpenWebUI or a model.

Security model

OpenWebUI -- Bearer Keycloak access token --> MCP
                                         | verify signature/JWKS, iss, aud, exp, nbf
                                         v
                                    verified sub
                                         |
                                         v
                                    Vault KV v2
                                         |
                                         v
                                   Bitrix24 REST API

• Keycloak issuer: https://sso.rucortex.ru/realms/rucortex

• Required MCP audience: https://147.45.38.205/mcp. The JWT aud claim may be an array; the server requires this value to be a member of it.

• Vault uses AppRole and keeps its short-lived Vault token only in memory.

• Local SQLite contains only one-time OAuth state and task-form data; it never stores Bitrix access or refresh tokens.

• Audit logs contain request ID, verified Keycloak subject, external Bitrix user ID (when known), tool, and status—never secrets or tokens.

Related MCP server: BitrixMCP

Prerequisites

1. Open TCP ports 80 and 443 to the VPS and set the public IP in PUBLIC_HOST (without protocol or path).

2. Put the DevOps-provided AppRole values in the VPS-only .env file as VAULT_ROLE_ID and VAULT_SECRET_ID. Do not commit .env, print either value, or put either value in logs or chat messages.

3. Vault must contain the shared Bitrix local-app configuration at the read-only API path /v1/mcp/data/config/bitrix:

   {
     "client_id": "...",
     "client_secret": "...",
     "redirect_uri": "https://147.45.38.205/bitrix/oauth/callback",
     "portal_url": "https://electrosteel.bitrix24.ru"
   }

4. In the Bitrix local app, configure this exact redirect URL:

   https://147.45.38.205/bitrix/oauth/callback

   The user who opens the connection link completes the official Bitrix OAuth flow. The callback state is server-generated, short-lived, and already tied to the verified Keycloak sub; the resulting credentials are written only to /v1/mcp-tokens/data/users/<sub>/bitrix in Vault.

VPS environment

Copy .env.example to .env and set the non-secret values, for example:

PUBLIC_HOST=147.45.38.205
ACME_EMAIL=admin@example.com
KEYCLOAK_ISSUER=https://sso.rucortex.ru/realms/rucortex
KEYCLOAK_DISCOVERY_URL=https://sso.rucortex.ru/realms/rucortex/.well-known/openid-configuration
KEYCLOAK_AUDIENCE=https://147.45.38.205/mcp
VAULT_ADDR=https://vault-staging.rucortex.ru
VAULT_ROLE_ID=replace_with_role_id
VAULT_SECRET_ID=replace_with_secret_id
SQLITE_ADMIN_USERNAME=sqlite_admin
SQLITE_ADMIN_PASSWORD=use_a_long_unique_password

Docker Compose passes VAULT_ROLE_ID and VAULT_SECRET_ID from the VPS-only .env into the MCP container. Keep .env restricted to the VPS and out of Git.

Optional shared-account Static Bearer mode

The same /mcp endpoint can also accept one shared bearer token for a separate OpenWebUI connection. Calls made through that connection act as the owner of a single Bitrix incoming webhook and do not use Keycloak identity or per-user Vault credentials. Set both values only in the VPS .env:

MCP_STATIC_BEARER_TOKEN=a-long-random-secret
BITRIX_STATIC_WEBHOOK_URL=https://electrosteel.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE

Keep this connection restricted to trusted administrators: every OWU user who can use it acts with the webhook owner's Bitrix permissions. Keycloak bearer authentication remains available for the existing per-user connection.

Start or update the stack:

cd /tmp/mcp-bitrix && git pull

cd /tmp/mcp-bitrix && docker compose up -d --build

The public MCP endpoint is:

https://147.45.38.205/mcp

/sqlite exposes the current non-secret local state database (data/mcp-state.sqlite3) through sqlite-web, behind Caddy basic auth. It is not a Vault browser and cannot show Bitrix tokens.

Inline Visualizer v2 task drafts

With Classic298 Inline Visualizer v2 enabled, create_task creates a short- lived draft bound to the verified Keycloak subject. It returns exact HTML for Visualizer v2 to stream between its @@@VIZ-START and @@@VIZ-END markers. The form has no iframe, no MCP HTTP request, and no access to Vault or Bitrix credentials.

After Принять, the form sends a strict follow-up prompt through Visualizer v2's sendPrompt bridge. The model must pass its opaque confirmation_payload unchanged to confirm_task_draft; MCP checks draft ownership, expiry, and the selected employee before reading Vault and creating the Bitrix task. That tool returns a static task preview. Отклонить similarly calls reject_task_draft, which creates no Bitrix task.

Enable Allow iframe same origin for Visualizer v2, as required by its streaming observer. Its default Strict CSP is sufficient here: the task form does not make outbound fetches and must not use security_level=none.

Keycloak configuration for OpenWebUI

Create a confidential Keycloak client for the OpenWebUI MCP connection.

1. In realm rucortex, create a client such as openwebui-bitrix-mcp. Enable Standard Flow, enable Client authentication, and use the client secret generated by Keycloak.

2. Add this exact valid redirect URI, replacing the host and connection ID with the values of your OpenWebUI installation and connection:

   https://<openwebui-host>/oauth/clients/<mcp-connection-id>/callback

   The MCP connection ID is the ID field in OpenWebUI, e.g. bitrix-test. If your OpenWebUI is served from the same host, the concrete URI is likely https://<openwebui-host>/oauth/clients/bitrix-test/callback.

3. Add an Audience mapper (or attach a client scope containing one) so the access token has https://147.45.38.205/mcp in its aud claim. It is valid and expected for aud to contain several values.

4. Ensure the assigned users can obtain this client’s access token. The default openid scope is sufficient for MCP authentication; add your normal profile scopes only if your organisation requires them.

OpenWebUI MCP connection

Use MCP Streamable HTTP and set:

Then save/register the connection and authenticate each user with Keycloak. Choose static OAuth because this Keycloak client is pre-created. Do not use OpenWebUI’s Dynamic Client Registration mode unless Keycloak DCR has separately been enabled and secured by your Keycloak administrator.

When a user’s Vault path has no Bitrix credentials, any Bitrix tool returns the controlled BITRIX_NOT_CONNECTED result. Call connect_bitrix, open its one-time link, and complete the official Bitrix login. Repeat the tool call after the confirmation page appears.

Tools

• users_list — employees with ID, full name, position, and departments.

• get_user_info — full current Bitrix profile.

• create_task — returns an embedded task form; the task is created only after its Принять button is pressed.

• connect_bitrix — provides a short-lived user Bitrix OAuth connection link.

The Bitrix local application needs permissions for users and tasks. In typical Bitrix24 terminology that means at least user, department, and task / tasks; retain crm only if future MCP tools will call CRM methods.

Migrating from the old OAuth bridge

The old bridge database may contain historic OAuth material. This code no longer reads it. After confirming the new flow works, take an encrypted backup and remove/archive any legacy data/tokens.json, data/clients.json, and old data/templates.sqlite3 files from the VPS. Do not delete data/mcp-state.sqlite3: it contains only active short-lived UI/OAuth state for this version.