MidPilot infrastructure setup

Last modified 30 Jul 2026 17:34 UTC
Table of Contents

MidPilot is a set of AI-assisted features that extend core identity management capabilities of midPoint and enable fast onboarding of applications for which no suitable connector exists.

Introduction

MidPilot consists of two independent microservices:

midpilot-smart-resource-integration

Generates configuration suggestions for resource object types, inbound/outbound mappings, delineation, synchronization, and correlation rules. Uses midPoint schema information as context.
Smart integration microservice repository on GitHub

midpilot-connector-gen

Generates connector code for a target application by analyzing API documentation of the application retrieved from the Internet. Requires its own PostgreSQL database, JAR file with generic connector, and access to a search engine.
Connector generator microservice repository on GitHub

Both services use a large language model (LLM) of your choice for certain parts of their operations. Hence the "AI-assisted" term.

Both services are optional and not essential for midPoint itself to function. Either service can be deployed independently of the other. At the same time, the services are not ready to use out of the box in a default midPoint installation. You need to explicitly add and configure them; this article is a reference for such configuration.

MidPoint itself does not communicate directly with the LLM. Instead, it delegates the communication to the microservices, which call the LLM via an OpenAI-compatible Chat Completions API.

Prerequisites

This section covers the basic requirements for deployment of midPilot AI services.

MidPoint version

MidPilot integration requires midPoint 4.11 or later. See, for example, the Docker Hub midPoint 4.11 tags.

LLM provider

Evolveum does not provide an LLM and the required infrastructure. You must supply your own LLM with an endpoint that is compatible with the OpenAI Chat Completions API. OpenAI itself is not required—any OpenAI-compatible provider or proxy works.

When configuring either of the microservices, you need the following from your LLM provider:

Environment variable Description

LLM__OPENAI_API_BASE

Base URL of the OpenAI-compatible API endpoint

LLM__MODEL_NAME

Model identifier.
Value not required. Defaults to openai/gpt-oss-120b.
Based on our analysis, gpt-oss-120b has proven to be the most effective so far. Pay attention to naming conventions—some providers prefix model names (e.g., open-ai/gpt-oss-120b). Consult your provider’s documentation.

LLM__OPENAI_API_KEY

Bearer JWT token for authentication

Internet access

The connector generator microservice requires Internet access in order to:

Additionally, both microservices require network connection to call the LLM API. If you do not run the LLM within the same network perimeter, then the smart resource integration service requires Internet connection as well.

If your deployment environment restricts Internet access, see the Corporate proxy environments section below.

PostgreSQL

The connector generator microservice requires a dedicated PostgreSQL database for storing indexed documentation chunks and LLM query optimization metadata. The database must exist and be accessible before the service starts because the service runs Alembic database migrations on startup.

Use a separate PostgreSQL instance for the connector generator. While it may be technically possible to share the main midPoint repository database, doing so risks namespace collisions between the midPoint schema and the connector generator database schema.

Langfuse tracing (optional)

Langfuse is an AI engineering platform that helps debug and analyze LLM applications. It is used purely for tracking LLM calls made by the microservices and it is not required for midPilot microservices or midPoint to function.

You can enable Langfuse tracing by setting LANGFUSE__TRACING_ENABLED to true.

LLM call tracing is disabled by default. If you want to use Langfuse, you need to deploy and configure it yourself according to the official Langfuse documentation.

If you enable tracing, you must also configure the remaining Langfuse variables in the .env file for each service:

Environment variable Description

LANGFUSE__HOST

Service host

LANGFUSE__SECRET_KEY

Secret key of the Langfuse API

LANGFUSE__PUBLIC_KEY

Public key of the Langfuse API

LANGFUSE__ENVIRONMENT

Label assigned to all traces sent to Langfuse. See below.

LANGFUSE__CA_CERT_FILE

Optional path to certificate for securing communication with the service

Langfuse environment label

This setting is used exclusively for observability and trace organization. It does not affect application behavior, LLM calls, database operations, or which endpoints are traced.

Purpose

The environment label can be used to filter and segment traces in the Langfuse UI. This is particularly important when multiple application environments send traces to the same Langfuse project. For example, it makes it possible to distinguish production and staging traces from local development runs. Without a unique environment label, traces from all application instances are displayed together in the same project.

How it works

The value is loaded into LangfuseSettings.environment in src/config/langfuse.py and passed to the Langfuse client constructor in src/core/observability/langfuse.py. The Langfuse SDK registers the value as an OpenTelemetry resource attribute. It is therefore automatically attached to every span and trace exported by the application process. No manual propagation is required.

Recommended values

  • production

  • development

  • developer’s name for testing and development
    Each developer should use a unique dev-<name> value. Otherwise, local traces generated by different developers cannot be reliably distinguished.

Smart resource integration microservice

The smart resource integration microservice (midpilot-smart-resource-integration) provides AI-assisted suggestions for:

  • Resource object type configuration

  • Inbound and outbound mapping rules

    • Mapping suggestions are generated on demand using midPoint schema information as context.

  • Delineation

  • Synchronization rules

  • Correlation rules

    • Requires related shadow objects to be present in midPoint.

Requirements

  • Accessible LLM endpoint

  • Network connectivity between midPoint and the microservice

No additional database is required.

Deployment

Deploy the midpilot-smart-resource-integration container (e.g., via Kubernetes, Docker Compose, Nomad job, etc.). The service listens on port 8090 by default. MidPoint communicates with the microservice using REST API over HTTP.

A demo Docker Compose file is available at Evolveum midpoint-samples GitHub repository.

Environment variables

Beside the required configuration variables and the optional Langfuse service connection setup, you can define the following:

Environment variable Default Description

LOGGING__LEVEL

info

Logging level (e.g., info, trace, debug)

  1. Verify the LLM endpoint is reachable by the microservice.

  2. Verify network connectivity between midPoint and the microservice.

  3. Perform a simple runtime test with a dummy CSV resource.

Connector generator microservice

The connector generator microservice (midpilot-connector-gen) generates connector code for target applications by:

  1. Searching for and downloading API documentation of the target application

  2. Indexing documentation chunks in PostgreSQL

  3. Using LLM-assisted analysis to produce connector code based on the SCIMREST connector framework

Requirements

  • Accessible LLM endpoint

  • Dedicated PostgreSQL database (must exist before startup)

  • Access to a connector framework JAR file (retrieved from a URL or local path—see the Connector framework JAR section)

  • Internet access for documentation discovery

  • Optionally: Brave Search API key (recommended for better search quality)

Deployment

Deploy the midpilot-connector-gen container (e.g., via Kubernetes, Docker Compose, Nomad job, etc.). The service listens on port 8090 by default. MidPoint communicates with the microservice using REST API over HTTP. Additionally, ensure the dedicated PostgreSQL database is running and accessible before starting the service (see the Prerequisites section).

Components

This microservice consists of two containers:

  • midpilot-connector-gen: the API server

  • midpilot-connector-gen-db: the PostgreSQL database

Environment variables

Beside the required configuration variables and the optional Langfuse service connection setup, you can define the following:

Environment variable Default Required? Description

LOGGING__LEVEL

info

no

Logging level (e.g., info, trace, debug)

SEARCH__METHOD_NAME

none

yes

Search provider:

  • ddgs (DuckDuckGo, free but limited)

  • brave (recommended, requires API key)

BRAVE__API_KEY

none

yes if using Brave

API key for Brave Search

BRAVE__ENDPOINT

none

yes if using Brave

API endpoint for Brave Search

Connector framework JAR

The connector generator requires a connector framework JAR file (one layer above ConnId) that serves as a template during connector generation. This file is referenced by the connectorFrameworkUrl element in midPoint System configuration object.

You have two options to get the connector framework JAR:

  • Use the universal URL which always points to the newest version:
    https://nexus.evolveum.com/nexus/service/rest/v1/search/assets/download?repository=snapshots&maven.groupId=com.evolveum.polygon.scimrest&maven.artifactId=connector-scimrest-generic&maven.extension=jar&maven.classifier=&sort=version&direction=desc

  • Get the connector framework JAR in Evolveum Nexus repository. Select the version you wish to use and download the JAR to use it locally. For development versions of midPoint, use the framework version that is current (i.e., newest) at the time your midPoint and midPilot have been built.
    A local file:// path may be used instead of an HTTP URL if, for example, network access to Nexus is restricted.

Startup behavior

The connector generator service starts by running Python Alembic database migrations before launching the API server. This is why the PostgreSQL database must already exist and be accessible at startup.

At runtime, uvicorn (ASGI web server implementation for Python, used internally by the microservice) may attempt to download or verify Python dependencies. If your deployment environment has restricted Internet access, you can prevent this using either of the following approaches:

Use --no-sync flags

uv run --no-sync alembic upgrade head && uv run --no-sync python server.py

Use the virtual environment binaries directly

/app/.venv/bin/alembic upgrade head && /app/.venv/bin/python server.py

  1. Verify the LLM endpoint is reachable.

  2. Verify the LLM API key is valid.

  3. Verify PostgreSQL connectivity and that the database exists.

  4. Verify search engine access and configuration (DuckDuckGo or Brave, depending on configuration).

  5. Verify access to Nexus or the local path for the connector framework JAR.

  6. Test connectivity between midPoint and the connector generator service.

  7. Perform a runtime test: create a SCIM connector targeting scim.dev (search for documentation and generate a connector).

Demo target application

A demo Docker Compose file for OpenProject is available at Evolveum midpoint-samples GitHub repository. This OpenProject instance (deployed separately) can serve as your testing target application.

MidPoint configuration

Once the microservices are deployed, configure midPoint to connect to them. This is done in the smartIntegration block within the midPoint System configuration object. The configuration block is present in the System configuration object out of the box.

<smartIntegration>
    <!-- Shared settings for both microservices -->
    <statisticsTtl>P1D</statisticsTtl> (1)
    <schemaMatchTtl>P1D</schemaMatchTtl> (2)
    <mappingSuggestionRetryCount>0</mappingSuggestionRetryCount> (3)

    <!-- Smart resource integration service URL -->
    <serviceUrl>http://midpilot-smart-resource-integration:8090/</serviceUrl> (4)

    <!-- Connector generator service URL -->
    <connectorGenerationUrl>http://midpilot-connector-gen:8090/api/v1</connectorGenerationUrl> (5)

    <!-- Connector framework JAR (URL or local path) -->
    <connectorFrameworkUrl>https://nexus.evolveum.com/nexus/service/rest/v1/search/assets/download?repository=snapshots&maven.groupId=com.evolveum.polygon.scimrest&maven.artifactId=connector-scimrest-generic&maven.extension=jar&maven.classifier=&sort=version&direction=desc</connectorFrameworkUrl> (6)
</smartIntegration>
1 Time-to-live for cached statistics data (ISO 8601 duration, e.g., P1D = 1 day)
2 Time-to-live for cached schema matching results (ISO 8601 duration)
3 Number of retry attempts for mapping suggestions (0 = no retries)
4 Base URL of the smart resource integration microservice
5 Base URL of the connector generator microservice API
6 URL or local file:// path to the connector framework JAR

Addendum

Deployment considerations

Network

The microservices communicate with midPoint using REST API over HTTP. Ensure your network policies permit such communication.

Authentication

By default, the microservices do not require authentication for requests from midPoint.

Secrets management

API keys (LLM, Brave search), database passwords, and other sensitive values should be injected through your secret vault (e.g., Kubernetes Secrets), not hardcoded in deployment manifests.

Logs

The midPoint-side logging module for the midPilot microservices is com.evolveum.midpoint.smart.impl.

Corporate proxy environments

If your deployment sits behind a corporate proxy, additional configuration is needed:

  • Microservices inherit proxy configuration from the operating system (standard HTTP_PROXY / HTTPS_PROXY environment variables).

  • MidPoint (Java) additionally requires JVM proxy properties.
    Container proxy variables alone are not sufficient for outbound HTTP communication initiated by Java. You must set:

    • http.proxyHost

    • http.proxyPort

    • https.proxyHost (if applicable)

    • https.proxyPort (if applicable)

These configuration options are typically passed as JVM arguments (e.g., ‑Dhttp.proxyHost=proxy.example.com ‑Dhttp.proxyPort=8080).
We suggest using the MP_SET environment variables, such as:

  • MP_SET_http_proxyHost

  • MP_SET_http_proxyPort

  • MP_SET_http_proxyUser

  • MP_SET_http_proxyPassword

  • MP_SET_http_nonProxyHost

  • And their https counterparts if applicable

Verification checklist

Use these checklists after deployment to confirm everything works correctly.

  • Common to both microservices

    • LLM endpoint is reachable from the microservices.

    • LLM API key is valid.

    • MidPoint and the microservices can communicate.

  • Smart resource integration

    • serviceUrl in System configuration points to the correct microservice address and port.

    • Verification: create a dummy CSV resource and request mapping suggestions.

  • Connector generator

    • connectorGenerationUrl in System configuration points to the correct microservice address and port.

    • connectorFrameworkUrl points to a valid, accessible JAR. The JAR version matters.

    • PostgreSQL is running, the database exists, and the microservice can connect.

    • Search engine is configured and accessible by the microservice.

    • Verification: generate a SCIM connector targeting scim.dev.

See also

Was this page helpful?
YES NO
Thanks for your feedback