Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""LDAP authentication plugin.
Supports authenticating users against an LDAP server (Active Directory, OpenLDAP, etc.)
and mapping LDAP attributes to OpenViking identities.
"""
from __future__ import annotations
import asyncio
import logging
import re
import sys
from typing import Any, Dict, List, Optional, Tuple
from fastapi import Request
from openviking.server.auth.identity_mapping import IdentityMapper
from openviking.server.auth.ldap_config import LDAPConfig
from openviking.server.auth.plugin import AuthPlugin
from openviking.server.identity import ResolvedIdentity, Role
from openviking_cli.exceptions import UnauthenticatedError
logger = logging.getLogger(__name__)
# Try to import LDAP library, provide helpful error if missing
try:
import ldap
import ldap.filter
LDAP_AVAILABLE = True
except ImportError:
LDAP_AVAILABLE = False
logger.warning(
"LDAP library not available. LDAP authentication will not work. "
"Install with: uv pip install python-ldap"
)
# Network/operation timeout (seconds) for synchronous LDAP calls. The calls
# are offloaded to a thread executor (see _authenticate_ldap), but a hung LDAP
# server must not be allowed to tie up a thread indefinitely.
_LDAP_NETWORK_TIMEOUT = 10.0
_LDAP_OPERATION_TIMEOUT = 10.0
_DN_VALUE_ESCAPES = {
"\x00": r"\00",
'"': r'\"',
"+": r"\+",
",": r"\,",
";": r"\;",
"<": r"\<",
"=": r"\=",
">": r"\>",
"\\": r"\\",
}
_DN_ESCAPE_RE = re.compile(r"\\([0-9A-Fa-f]{2}|[\s\S])")
_FIRST_RDN_RE = re.compile(r"(?:\\.|[^,])*")
def _escape_dn_value(value: str) -> str:
"""Escape a single LDAP DN attribute value per RFC 4514."""
escaped = "".join(_DN_VALUE_ESCAPES.get(char, char) for char in value)
if not escaped:
return escaped
if value[0] in {" ", "#"}:
escaped = "\\" + escaped
if len(value) > 1 and value[-1] == " ":
escaped = escaped[:-1] + r"\ "
return escaped
def _split_first_rdn(dn: str) -> str:
return _FIRST_RDN_RE.match(dn)[0]
def _unescape_dn_value(value: str) -> str:
return _DN_ESCAPE_RE.sub(
lambda match: chr(int(match[1], 16)) if len(match[1]) == 2 else match[1],
value,
)
def _apply_ldap_connection_options(conn: Any) -> None:
"""Apply standard connection options including network timeouts."""
conn.set_option(ldap.OPT_REFERRALS, 0) # Disable chasing referrals
conn.set_option(ldap.OPT_PROTOCOL_VERSION, 3) # LDAPv3
# Bound blocking I/O — without these a dead LDAP server can hang the
# worker thread for the OS default (often minutes).
conn.set_option(ldap.OPT_NETWORK_TIMEOUT, _LDAP_NETWORK_TIMEOUT)
conn.set_option(ldap.OPT_TIMEOUT, _LDAP_OPERATION_TIMEOUT)
def _format_user_dn(pattern: str, username: str) -> str:
"""Render a user DN pattern.
Supports two idioms:
* ``"%s"`` positional substitution, the classic LDAP template style
(``uid=%s,ou=users,dc=example,dc=com``).
* ``"%(username)s"`` / ``"%(user)s"`` mapping substitution.
"""
safe_username = _escape_dn_value(username)
if "%(" in pattern:
return pattern % {"username": safe_username, "user": safe_username}
# Only substitute a single %s; treat %% as an escaped %.
return pattern % (safe_username,)
class LDAPAuthPlugin(AuthPlugin):
"""LDAP authentication plugin.
Authenticates users against an LDAP server and maps attributes
to OpenViking account/user identities.
"""
auth_mode = "ldap"
def __init__(self) -> None:
self._config: Optional[LDAPConfig] = None
self._mapper: Optional[IdentityMapper] = None
async def resolve_identity(
self,
request: Request,
*,
api_key: Optional[str] = None,
x_openviking_account: Optional[str] = None,
x_openviking_user: Optional[str] = None,
) -> ResolvedIdentity:
"""Resolve identity from LDAP authentication."""
if not LDAP_AVAILABLE:
raise UnauthenticatedError(
"LDAP authentication not available: missing python-ldap"
)
if self._config is None:
raise RuntimeError("LDAP config not initialized")
if self._mapper is None:
raise RuntimeError("Identity mapper not initialized")
# Extract credentials from request
username, password = await self._extract_credentials(
request,
api_key,
x_openviking_user,
)
if not username or not password:
raise UnauthenticatedError("Missing LDAP credentials (username/password)")
# Authenticate against LDAP server and return attributes.
# python-ldap is a synchronous binding to OpenLDAP's libldap; every
# network call blocks. Offload to the default thread executor so a
# slow/unreachable directory cannot stall the event loop (and thus
# unrelated requests on the same worker).
try:
attributes = await asyncio.to_thread(
self._authenticate_ldap, username, password
)
logger.debug("Successfully authenticated LDAP user: %s", username)
# Log available attributes for debugging
if attributes:
logger.debug(
"Available LDAP attributes: %s", list(attributes.keys())
)
except ldap.LDAPError as e:
error_code = getattr(e, "args", [None])[0] if e.args else None
logger.debug(
"LDAP authentication failed for user %s - Error: %s, Code: %s",
username,
str(e),
error_code,
)
raise UnauthenticatedError(f"LDAP authentication failed: {e}") from e
# Map LDAP attributes to OpenViking identity.
# Role is always USER for LDAP-authenticated identities. This is by
# design: LDAP authenticates directory users, and their role in the
# directory (e.g., membership in an "admins" group) should not
# automatically grant OpenViking admin privileges. Operators who
# need admin access should use the root API key mechanism.
try:
normalized_attrs = self._normalize_attributes(attributes)
dn_bytes = attributes.get("dn", [None])[0] if attributes else None
dn = dn_bytes.decode("utf-8") if dn_bytes else None
account_id = self._mapper.map_account_id(
claims={}, attributes=normalized_attrs, dn=dn
)
user_id = self._mapper.map_user_id(
claims={}, attributes=normalized_attrs, dn=dn
)
except ValueError as e:
logger.error("Failed to map LDAP attributes: %s", e)
raise UnauthenticatedError(f"Failed to map attributes: {e}") from e
logger.debug(
"Successfully authenticated LDAP user: account=%s, user=%s, role=%s",
account_id,
user_id,
Role.USER,
)
return ResolvedIdentity(role=Role.USER, account_id=account_id, user_id=user_id)
async def _extract_credentials(
self,
request: Request,
api_key: Optional[str] = None,
x_openviking_user: Optional[str] = None,
) -> Tuple[Optional[str], Optional[str]]:
"""Extract username and password from request."""
# Try Basic Auth first
auth_header = request.headers.get("Authorization")
if auth_header and auth_header.lower().startswith("basic "):
import base64
try:
encoded = auth_header.split(" ", 1)[1]
decoded = base64.b64decode(encoded).decode("utf-8")
username, password = decoded.split(":", 1)
return username, password
except Exception: # noqa: BLE001
pass
# Try form data
try:
form = await request.form()
username = form.get("username")
password = form.get("password")
if username and password:
return str(username), str(password)
except Exception: # noqa: BLE001
pass
# Fallback: use api_key as password if x_openviking_user is present
if x_openviking_user and api_key:
return x_openviking_user, api_key
return None, None
def _new_connection(self, ldap_url: str) -> Any:
conn = ldap.initialize(ldap_url)
_apply_ldap_connection_options(conn)
if self._config.use_starttls and not self._config.use_ssl:
conn.start_tls_s()
return conn
def _search_user_attributes(
self,
conn: Any,
username: str,
) -> Tuple[Optional[str], Dict[str, List[bytes]]]:
"""Search for a user's DN and attributes using the bound connection.
Used both by the search+bind flow (with the service account) and the
direct-bind flow (where the bound user typically has read access to
their own entry).
"""
assert self._config is not None
safe_username = ldap.filter.escape_filter_chars(username)
search_filter = self._config.user_search_filter % safe_username
search_base = (
self._config.user_search_base or self._config.base_dn
)
logger.debug(
"Searching for user with filter: %s, base: %s",
search_filter,
search_base,
)
result = conn.search_s(
search_base,
ldap.SCOPE_SUBTREE,
search_filter,
["*"],
)
for dn, attrs in result:
if dn: # Skip referrals / continuation references
return dn, attrs
return None, {}
def _authenticate_ldap(
self, username: str, password: str
) -> Dict[str, List[bytes]]:
"""Authenticate user against LDAP server and return attributes.
This is a synchronous method; callers must run it in a worker thread.
"""
if self._config is None:
raise RuntimeError("LDAP config not initialized")
protocol = "ldaps" if self._config.use_ssl else "ldap"
ldap_url = f"{protocol}://{self._config.host}:{self._config.port}"
user_dn: Optional[str] = None
user_attrs: Dict[str, List[bytes]] = {}
if self._config.bind_dn and self._config.bind_password:
# --- Search + Bind flow -----------------------------------------
# 1. Bind as a service account, search for the user entry.
# 2. Rebind as the user to verify the supplied password.
# 3. Re-bind as the service account to read attributes (the user
# bind may not have read access to its own object in some
# deployments).
search_conn = self._new_connection(ldap_url)
try:
search_conn.simple_bind_s(
self._config.bind_dn, self._config.bind_password
)
user_dn, user_attrs = self._search_user_attributes(
search_conn, username
)
finally:
try:
search_conn.unbind()
except Exception: # noqa: BLE001
pass
if not user_dn:
raise UnauthenticatedError(f"User {username} not found")
# Validate the user's credentials.
user_conn = self._new_connection(ldap_url)
try:
user_conn.simple_bind_s(user_dn, password)
finally:
try:
user_conn.unbind()
except Exception: # noqa: BLE001
pass
# Re-bind as the service account to fetch attributes if the first
# search didn't return them (shouldn't normally happen).
if not user_attrs:
attr_conn = self._new_connection(ldap_url)
try:
attr_conn.simple_bind_s(
self._config.bind_dn, self._config.bind_password
)
user_dn, user_attrs = self._search_user_attributes(
attr_conn, username
)
finally:
try:
attr_conn.unbind()
except Exception: # noqa: BLE001
pass
elif self._config.user_dn_pattern:
# --- Direct Bind flow -------------------------------------------
# No service account: construct the user's DN from the pattern,
# bind as the user directly, then attempt to read their own
# attributes using the bound connection.
user_dn = _format_user_dn(self._config.user_dn_pattern, username)
conn = self._new_connection(ldap_url)
try:
conn.simple_bind_s(user_dn, password)
# Best-effort attribute read: most directory ACLs permit a
# user to read their own entry. If the server forbids it, we
# fall back to synthesizing attributes from the DN so that
# the documented ``user_id <- uid`` default still works for
# ``uid=<username>,...`` patterns.
try:
_, found_attrs = self._search_user_attributes(conn, username)
if found_attrs:
user_attrs = found_attrs
except ldap.LDAPError as e:
logger.debug(
"Direct bind: unable to read own attributes for %s: %s",
username,
e,
)
finally:
try:
conn.unbind()
except Exception: # noqa: BLE001
pass
if not user_attrs:
# Fallback: derive the RDN attribute/value pair from the DN.
# For ``uid=alice,ou=users,...`` this yields {"uid": [b"alice"]}.
user_attrs = self._attrs_from_dn(user_dn)
else:
raise UnauthenticatedError(
"LDAP config requires either bind_dn/bind_password or "
"user_dn_pattern"
)
# Ensure DN is present in attributes for identity mapping.
if user_dn:
user_attrs.setdefault("dn", [user_dn.encode("utf-8")])
# Always make the DN RDN value available under its attribute name
# so the default user_id <- uid mapping works even if the server
# returned no attributes.
rdn_attr, rdn_value = self._parse_first_rdn(user_dn)
if rdn_attr and rdn_value:
user_attrs.setdefault(
rdn_attr.lower(), [rdn_value.encode("utf-8")]
)
return user_attrs
@staticmethod
def _parse_first_rdn(dn: str) -> Tuple[Optional[str], Optional[str]]:
"""Parse the first RDN of a DN, returning (attr_name, value)."""
if not dn:
return None, None
first = _split_first_rdn(dn)
if "=" not in first:
return None, None
attr, _, value = first.partition("=")
return attr.strip(), _unescape_dn_value(value)
@classmethod
def _attrs_from_dn(cls, dn: str) -> Dict[str, List[bytes]]:
"""Build a minimal attribute dict from a DN.
Used as a fallback when a direct-bind user cannot read their own
entry. Extracts the first RDN pair (e.g. ``uid=alice``).
"""
attr, value = cls._parse_first_rdn(dn)
if not attr or not value:
return {}
return {attr.lower(): [value.encode("utf-8")]}
def _normalize_attributes(
self, attributes: Dict[str, List[bytes]]
) -> Dict[str, str]:
"""Normalize LDAP attributes from bytes to strings."""
normalized: Dict[str, str] = {}
for key, values in attributes.items():
if values:
try:
normalized[key.lower()] = values[0].decode("utf-8")
except UnicodeDecodeError:
try:
normalized[key.lower()] = values[0].decode("latin-1")
except UnicodeDecodeError:
normalized[key.lower()] = ""
return normalized
def validate_config(self, config) -> None:
"""Validate LDAP configuration."""
if config.ldap is None:
logger.error(
"auth_mode=ldap but 'ldap' section missing in config. "
"Please configure the LDAP server settings."
)
sys.exit(1)
if not config.ldap.host:
logger.error("LDAP config missing 'host'")
sys.exit(1)
if not config.ldap.base_dn:
logger.error("LDAP config missing 'base_dn'")
sys.exit(1)
if not config.ldap.bind_dn and not config.ldap.user_dn_pattern:
logger.error(
"LDAP config requires either 'bind_dn'/'bind_password' or "
"'user_dn_pattern'"
)
sys.exit(1)
if config.ldap.bind_dn and not config.ldap.bind_password:
logger.warning(
"LDAP config has 'bind_dn' but missing 'bind_password' — "
"searches may fail"
)
logger.info("LDAP config validated successfully")
async def initialize(self, app, service, config) -> None:
"""Initialize LDAP plugin."""
if config.ldap is None:
raise RuntimeError("LDAP config missing")
self._config = config.ldap
# LDAPConfig supplies LDAP-specific defaults (user_id <- uid,
# fixed USER role) via default_factory, so no fallback is needed
# here. Operators can still override via the `identity` config block.
self._mapper = IdentityMapper(self._config.identity)
logger.info(
"LDAP auth plugin initialized with host=%s", self._config.host
)
def can_skip_api_key_for_bot_proxy(self) -> bool:
"""LDAP does not declare bot-proxy compatibility until VikingBot
natively understands the ``ldap`` auth mode (mode inference, Basic
Auth credential propagation, and identity forwarding to bot tools).
Returning False here makes ``--with-bot`` fail fast with a clear
error instead of producing a silent auth-mode mismatch at runtime.
"""
return False