ldapgate 0.1.0__py3-none-any.whl

ldapgate/__init__.py

@@ -0,0 +1,19 @@
+"""ldapgate - LDAP/AD authentication proxy and FastAPI middleware"""
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "LDAPAuthenticator",
+    "LDAPConfig",
+    "LDAPAuthMiddleware",
+    "SessionManager",
+    "create_proxy_app",
+    "create_login_router",
+    "add_ldap_auth",
+]
+
+from ldapgate.config import LDAPConfig
+from ldapgate.ldap import LDAPAuthenticator
+from ldapgate.middleware import LDAPAuthMiddleware, add_ldap_auth
+from ldapgate.proxy import create_proxy_app, create_login_router
+from ldapgate.sessions import SessionManager

ldapgate/cli.py

@@ -0,0 +1,121 @@
+"""CLI for ldapgate reverse proxy."""
+
+import os
+from pathlib import Path
+
+import click
+import uvicorn
+
+from ldapgate.config import load_config
+from ldapgate.proxy import create_proxy_app
+
+# Env var used to pass config path to the module-level app factory for --reload mode
+_CONFIG_ENV_VAR = "LDAPGATE_CONFIG_PATH"
+
+
+@click.group()
+def cli():
+    """ldapgate - LDAP/AD authentication proxy."""
+    pass
+
+
+@cli.command()
+@click.option(
+    "--config",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Path to ldapgate.yaml config file (reads env vars if omitted)",
+)
+@click.option(
+    "--host",
+    default=None,
+    help="Override listen host (default: 0.0.0.0)",
+)
+@click.option(
+    "--port",
+    type=int,
+    default=None,
+    help="Override listen port (default: 9000)",
+)
+@click.option(
+    "--backend",
+    default=None,
+    help="Override backend URL",
+)
+@click.option(
+    "--reload",
+    is_flag=True,
+    help="Enable auto-reload on code changes",
+)
+def serve(config: Path, host: str, port: int, backend: str, reload: bool):
+    """Start ldapgate reverse proxy server.
+
+    Example:
+        ldapgate serve --config ldapgate.yaml
+        ldapgate serve --backend http://localhost:3923
+    """
+    try:
+        cfg = load_config(config)
+
+        if host:
+            cfg.proxy.listen_host = host
+        if port:
+            cfg.proxy.listen_port = port
+        if backend:
+            cfg.proxy.backend_url = backend
+
+        click.echo(
+            f"Starting ldapgate proxy on {cfg.proxy.listen_host}:{cfg.proxy.listen_port}"
+        )
+        click.echo(f"Backend: {cfg.proxy.backend_url}")
+        click.echo(f"Login path: {cfg.proxy.login_path}")
+
+        if reload:
+            # Reload mode requires an import string; pass config + overrides via env vars
+            # so the factory in this module can reconstruct the app identically.
+            if config:
+                os.environ[_CONFIG_ENV_VAR] = str(config)
+            if backend:
+                os.environ["LDAPGATE_BACKEND_URL"] = backend
+            uvicorn.run(
+                "ldapgate.cli:_reload_app_factory",
+                factory=True,
+                host=cfg.proxy.listen_host,
+                port=cfg.proxy.listen_port,
+                reload=True,
+                log_level="info",
+            )
+        else:
+            app = create_proxy_app(cfg)
+            uvicorn.run(
+                app,
+                host=cfg.proxy.listen_host,
+                port=cfg.proxy.listen_port,
+                log_level="info",
+            )
+
+    except FileNotFoundError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+def _reload_app_factory():
+    """App factory used by uvicorn --reload (needs importable callable)."""
+    config_path = os.environ.get(_CONFIG_ENV_VAR)
+    cfg = load_config(config_path)
+    backend = os.environ.get("LDAPGATE_BACKEND_URL")
+    if backend:
+        cfg.proxy.backend_url = backend
+    return create_proxy_app(cfg)
+
+
+def main():
+    """Entry point for ldapgate CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

ldapgate/config.py

@@ -0,0 +1,114 @@
+"""Configuration management for ldapgate."""
+
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class LDAPSettings(BaseModel):
+    """LDAP/AD configuration."""
+
+    url: str = Field(
+        ..., description="LDAP server URL (e.g., ldaps://dc.example.com:636)"
+    )
+    bind_dn: str = Field(..., description="Service account DN for binding")
+    bind_password: str = Field(..., description="Service account password")
+    base_dn: str = Field(..., description="Base DN for user searches")
+    user_filter: str = Field(
+        "(sAMAccountName={username})",
+        description="LDAP filter for user lookup (e.g., AD: sAMAccountName, OpenLDAP: uid)",
+    )
+    group_dn: Optional[str] = Field(
+        None, description="Optional group DN to restrict access (e.g., CN=app-users,..."
+    )
+    timeout: int = Field(10, description="LDAP connection timeout in seconds")
+
+
+class ProxySettings(BaseModel):
+    """Reverse proxy configuration."""
+
+    listen_host: str = Field("0.0.0.0", description="Host to listen on")
+    listen_port: int = Field(9000, description="Port to listen on")
+    backend_url: str = Field(..., description="Backend service URL to proxy to")
+    secret_key: str = Field(..., description="Secret key for signing session cookies")
+    session_ttl: int = Field(3600, description="Session time-to-live in seconds")
+    user_header: str = Field(
+        "X-Forwarded-User", description="Header name for authenticated username"
+    )
+    login_path: str = Field("/_auth/login", description="Login page path")
+    logout_path: str = Field("/_auth/logout", description="Logout page path")
+    app_name: str = Field("ldapgate", description="Application name for login form")
+    secure_cookies: bool = Field(
+        False,
+        description="Set Secure flag on session cookies (enable when behind HTTPS proxy)",
+    )
+
+
+class LDAPConfig(BaseSettings):
+    """Complete ldapgate configuration."""
+
+    ldap: LDAPSettings
+    proxy: ProxySettings
+
+    model_config = SettingsConfigDict(
+        env_nested_delimiter="__",
+    )
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> "LDAPConfig":
+        """Load configuration from YAML file.
+
+        Args:
+            path: Path to YAML config file
+
+        Returns:
+            Configured LDAPConfig instance
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            yaml.YAMLError: If YAML is invalid
+        """
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"Config file not found: {path}")
+
+        with open(path) as f:
+            data = yaml.safe_load(f)
+
+        if not data:
+            raise ValueError("Empty config file")
+
+        return cls(**data)
+
+    @classmethod
+    def from_env(cls) -> "LDAPConfig":
+        """Load configuration from environment variables.
+
+        Expected format:
+        - LDAP__URL
+        - LDAP__BIND_DN
+        - LDAP__BIND_PASSWORD
+        - etc.
+
+        Returns:
+            Configured LDAPConfig instance
+        """
+        return cls()
+
+
+def load_config(yaml_path: str | Path | None = None) -> LDAPConfig:
+    """Load configuration from YAML or environment.
+
+    Args:
+        yaml_path: Optional path to YAML config file.
+                  If provided, loads from file. Otherwise uses environment vars.
+
+    Returns:
+        Configured LDAPConfig instance
+    """
+    if yaml_path:
+        return LDAPConfig.from_yaml(yaml_path)
+    return LDAPConfig.from_env()

ldapgate/ldap.py

@@ -0,0 +1,148 @@
+"""LDAP/AD authentication core using ldap3."""
+
+import asyncio
+import logging
+
+from ldap3 import BASE, NONE, SUBTREE, Connection, Server
+from ldap3.core.exceptions import LDAPException
+
+from ldapgate.config import LDAPSettings
+
+log = logging.getLogger(__name__)
+
+
+def _escape_ldap(value: str) -> str:
+    """Escape special characters in LDAP filter values (RFC 4515)."""
+    replacements = [
+        ("\\", "\\5c"),
+        ("*", "\\2a"),
+        ("(", "\\28"),
+        (")", "\\29"),
+        ("\x00", "\\00"),
+    ]
+    for char, escaped in replacements:
+        value = value.replace(char, escaped)
+    return value
+
+
+class LDAPAuthenticator:
+    """Authenticates users against LDAP/AD directory."""
+
+    def __init__(self, config: LDAPSettings):
+        """Initialize LDAP authenticator.
+
+        Args:
+            config: LDAP configuration with server details and filters
+        """
+        self.config = config
+        self.server = Server(config.url, connect_timeout=config.timeout, get_info=NONE)
+
+    async def authenticate(self, username: str, password: str) -> bool:
+        """Authenticate user against LDAP directory.
+
+        Process:
+        1. Bind as service account
+        2. Search for user DN matching user_filter
+        3. Re-bind with user DN + supplied password
+        4. Optionally check group membership
+
+        Args:
+            username: Username to authenticate
+            password: Password to verify
+
+        Returns:
+            True if authentication successful, False otherwise
+        """
+        return await asyncio.to_thread(
+            self._authenticate_sync, username, password
+        )
+
+    def _authenticate_sync(self, username: str, password: str) -> bool:
+        """Synchronous authentication logic (run in thread pool)."""
+        if not username or not password:
+            return False
+
+        try:
+            # Step 1: Bind as service account
+            with Connection(
+                self.server,
+                user=self.config.bind_dn,
+                password=self.config.bind_password,
+                raise_exceptions=True,
+            ) as conn:
+                # Step 2: Search for user DN
+                # Escape special LDAP characters to prevent injection
+                safe_username = _escape_ldap(username)
+                user_filter = self.config.user_filter.format(username=safe_username)
+                conn.search(
+                    search_base=self.config.base_dn,
+                    search_filter=user_filter,
+                    search_scope=SUBTREE,
+                )
+
+                if not conn.entries:
+                    return False
+
+                user_dn = conn.entries[0].entry_dn
+
+            # Step 3: Try to bind as the user with supplied password
+            with Connection(
+                self.server,
+                user=user_dn,
+                password=password,
+                raise_exceptions=True,
+            ) as conn:
+                # Connection successful = auth successful
+                pass
+
+            # Step 4: Optional group membership check
+            if self.config.group_dn:
+                if not self._check_group_membership(user_dn):
+                    return False
+
+            return True
+
+        except LDAPException as e:
+            log.debug("LDAP authentication failed: %s", e)
+            return False
+        except Exception as e:
+            log.warning("Unexpected error during LDAP authentication: %s", e)
+            return False
+
+    def _check_group_membership(self, user_dn: str) -> bool:
+        """Check if user is member of configured group.
+
+        Args:
+            user_dn: User's distinguished name
+
+        Returns:
+            True if user is in group (or no group configured), False otherwise
+        """
+        try:
+            with Connection(
+                self.server,
+                user=self.config.bind_dn,
+                password=self.config.bind_password,
+                raise_exceptions=True,
+            ) as conn:
+                # Use BASE scope to check a single group entry for membership.
+                # Supports both AD (member=) and OpenLDAP (uniqueMember=) via OR filter.
+                # Escape the DN for filter safety — DNs can contain (, ), *, \ chars.
+                safe_dn = _escape_ldap(user_dn)
+                group_filter = (
+                    f"(|(member={safe_dn})(uniqueMember={safe_dn}))"
+                )
+                conn.search(
+                    search_base=self.config.group_dn,
+                    search_filter=group_filter,
+                    search_scope=BASE,
+                    attributes=["cn"],
+                )
+                return bool(conn.entries)
+
+        except LDAPException as e:
+            log.debug("LDAP group membership check failed: %s", e)
+            return False
+        except Exception as e:
+            log.warning("Unexpected error during group membership check: %s", e)
+            return False

ldapgate/middleware.py

@@ -0,0 +1,113 @@
+"""Starlette middleware for FastAPI LDAP authentication."""
+
+from typing import Optional
+from urllib.parse import quote
+
+from fastapi import FastAPI
+from starlette.datastructures import MutableHeaders
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import RedirectResponse, Response
+
+from ldapgate.config import LDAPConfig
+from ldapgate.sessions import SessionManager
+
+
+class LDAPAuthMiddleware(BaseHTTPMiddleware):
+    """Starlette middleware for LDAP authentication in FastAPI apps.
+
+    Usage:
+        config = load_config("ldapgate.yaml")
+        app.add_middleware(LDAPAuthMiddleware, config=config)
+    """
+
+    def __init__(self, app: FastAPI, config: LDAPConfig):
+        """Initialize middleware.
+
+        Args:
+            app: FastAPI application instance
+            config: LDAPConfig with LDAP and session settings
+        """
+        super().__init__(app)
+        self.config = config
+        self.session_manager = SessionManager(
+            config.proxy.secret_key, config.proxy.session_ttl
+        )
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        """Middleware dispatch handler.
+
+        Checks session cookie. If valid, adds request.state.user and injects header.
+        If invalid, redirects to login form.
+
+        Args:
+            request: Incoming request
+            call_next: Next middleware/route handler
+
+        Returns:
+            Response
+        """
+        # Skip auth for login endpoints and static assets
+        if self._should_skip_auth(request.url.path):
+            return await call_next(request)
+
+        # Check session
+        session_cookie = request.cookies.get(SessionManager.COOKIE_NAME)
+        username = self.session_manager.verify_session(session_cookie)
+
+        if not username:
+            # Redirect to login with original URL as redirect target
+            redirect_url = request.url.path
+            if request.url.query:
+                redirect_url += f"?{request.url.query}"
+            return RedirectResponse(
+                url=f"{self.config.proxy.login_path}?redirect={quote(redirect_url, safe='')}",
+                status_code=302,
+            )
+
+        # Store username in request state for downstream use
+        request.state.user = username
+
+        # Inject user header into request scope (MutableHeaders modifies scope in place)
+        MutableHeaders(scope=request.scope)[self.config.proxy.user_header] = username
+
+        # Call next middleware/route
+        response = await call_next(request)
+
+        return response
+
+    def _should_skip_auth(self, path: str) -> bool:
+        """Check if path should skip authentication.
+
+        Args:
+            path: Request path
+
+        Returns:
+            True if auth should be skipped
+        """
+        # Skip login/logout endpoints
+        if path.startswith(self.config.proxy.login_path):
+            return True
+        if path.startswith(self.config.proxy.logout_path):
+            return True
+
+        # Skip common static asset paths
+        static_prefixes = ["/_static/", "/static/", "/assets/", "/favicon.ico", "/favicon.svg", "/robots.txt"]
+        return any(path.startswith(prefix) for prefix in static_prefixes)
+
+
+def add_ldap_auth(app: FastAPI, config: LDAPConfig, template_path: Optional[str] = None) -> None:
+    """Add LDAP auth to a FastAPI app: login routes + session middleware.
+
+    Registers the login form (GET/POST) on the app and attaches
+    LDAPAuthMiddleware so all other routes require a valid session.
+
+    Args:
+        app: FastAPI application
+        config: LDAPConfig instance
+        template_path: Optional path to a custom Jinja2 login template file.
+                       If omitted, uses the bundled ldapgate template.
+    """
+    from ldapgate.proxy import create_login_router
+    app.include_router(create_login_router(config, template_path=template_path))
+    app.add_middleware(LDAPAuthMiddleware, config=config)