"""ServiceMap API authorization. Modes (``SERVICEMAP_AUTH_MODE``): * ``disabled`` - no authentication (v1.5 behaviour). Cross-site mutations are still refused by the Origin check below. * ``token`` - reads stay anonymous on the LAN (integrations such as ITWorx Forge and monitors keep working); every mutating request needs ``Authorization: Bearer ``. The token lives in a 0600 file next to the database and is generated on first start. * ``oidc`` - fail-closed bearer JWT validation with viewer/operator/admin roles mapped from claims or groups. """ from __future__ import annotations import hmac import logging import os import secrets from dataclasses import dataclass from functools import lru_cache from pathlib import Path from threading import Lock from urllib.parse import urlparse import httpx import jwt from fastapi import HTTPException, Request, status class AuthorizationError(RuntimeError): pass _ROLE_ORDER = {"viewer": 1, "operator": 2, "admin": 3} def _csv(name: str) -> set[str]: return {item.strip().casefold() for item in os.getenv(name, "").split(",") if item.strip()} @dataclass(frozen=True) class AuthConfig: mode: str issuer: str | None = None audience: str | None = None role_claims: tuple[str, ...] = ("groups", "roles") viewer_groups: frozenset[str] = frozenset() operator_groups: frozenset[str] = frozenset() admin_groups: frozenset[str] = frozenset() @classmethod def from_environment(cls) -> AuthConfig: mode = os.getenv("SERVICEMAP_AUTH_MODE", "disabled").strip().casefold() or "disabled" if mode in {"disabled", "token"}: return cls(mode=mode) if mode != "oidc": raise AuthorizationError("SERVICEMAP_AUTH_MODE must be 'disabled', 'token' or 'oidc'") issuer = os.getenv("SERVICEMAP_OIDC_ISSUER", "").strip().rstrip("/") audience = os.getenv("SERVICEMAP_OIDC_AUDIENCE", "").strip() parsed = urlparse(issuer) local_http = os.getenv("SERVICEMAP_AUTH_ALLOW_HTTP_FOR_LOCAL", "false").casefold() == "true" if ( not issuer or not audience or not parsed.netloc or (parsed.scheme != "https" and not local_http) ): raise AuthorizationError("OIDC mode requires a valid HTTPS issuer and audience") claims = tuple( item.strip() for item in os.getenv("SERVICEMAP_OIDC_ROLE_CLAIMS", "groups,roles").split(",") if item.strip() ) return cls( mode=mode, issuer=issuer, audience=audience, role_claims=claims or ("groups", "roles"), viewer_groups=frozenset(_csv("SERVICEMAP_OIDC_VIEWER_GROUPS")), operator_groups=frozenset(_csv("SERVICEMAP_OIDC_OPERATOR_GROUPS")), admin_groups=frozenset(_csv("SERVICEMAP_OIDC_ADMIN_GROUPS")), ) @lru_cache(maxsize=8) def _jwks_client(issuer: str) -> jwt.PyJWKClient: try: document = httpx.get(f"{issuer}/.well-known/openid-configuration", timeout=5.0).json() jwks_uri = str(document.get("jwks_uri", "")) if isinstance(document, dict) else "" except (httpx.HTTPError, ValueError) as exc: raise AuthorizationError("OIDC discovery is unavailable") from exc parsed = urlparse(jwks_uri) issuer_host = urlparse(issuer).hostname if not parsed.netloc or parsed.scheme != "https" or parsed.hostname != issuer_host: raise AuthorizationError("OIDC discovery returned an invalid JWKS URI") return jwt.PyJWKClient(jwks_uri, cache_keys=True, lifespan=300) def _claim_values(claims: dict[str, object], names: tuple[str, ...]) -> set[str]: values: set[str] = set() for name in names: raw = claims.get(name) if isinstance(raw, str): values.add(raw.casefold()) elif isinstance(raw, list): values.update(str(item).casefold() for item in raw if isinstance(item, (str, int))) return values def _roles_for(claims: dict[str, object], config: AuthConfig) -> set[str]: values = _claim_values(claims, config.role_claims) roles: set[str] = set() # Explicit role claims remain useful with a constrained issuer; group # mapping gives operators a stable least-privilege model in Authentik. roles.update(value for value in values if value in _ROLE_ORDER) if values & config.viewer_groups: roles.add("viewer") if values & config.operator_groups: roles.add("operator") if values & config.admin_groups: roles.add("admin") if "admin" in roles: roles.update({"operator", "viewer"}) elif "operator" in roles: roles.add("viewer") return roles def verify_bearer(token: str, config: AuthConfig) -> set[str]: if not config.issuer or not config.audience: raise AuthorizationError("OIDC configuration is incomplete") try: signing_key = _jwks_client(config.issuer).get_signing_key_from_jwt(token) claims = jwt.decode( token, signing_key.key, algorithms=[signing_key.algorithm_name], audience=config.audience, issuer=config.issuer, options={"require": ["exp", "sub", "iss", "aud"]}, ) except jwt.PyJWTError as exc: raise AuthorizationError("Bearer token verification failed") from exc if not isinstance(claims, dict): raise AuthorizationError("Bearer token claims are invalid") return _roles_for(claims, config) SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"}) # Reads that expose secrets need write access even where reads are open # (an ntfy topic is effectively a secret on a public server). SECRET_READ_PREFIXES = ("/api/v1/config", "/api/v1/settings", "/api/v1/backups") # A backup contains every record, so listing and downloading need the token too. TOKEN_READ_PREFIXES = ("/api/v1/settings", "/api/v1/backups") _MIN_TOKEN_LENGTH = 24 _logger = logging.getLogger("servicemap.auth") _token_lock = Lock() _token_cache: dict[str, str] = {} def admin_token_path() -> Path: configured = os.getenv("SERVICEMAP_ADMIN_TOKEN_FILE", "").strip() if configured: return Path(configured) database = Path(os.getenv("SERVICEMAP_DB", "data/servicemap.db")) return database.parent / "admin-token" def admin_token() -> str: """Read the admin token, generating it on first use. The value is never logged; only its location is. Read it on the host with e.g. ``docker exec servicemap cat /data/admin-token``. """ path = admin_token_path() key = str(path) with _token_lock: cached = _token_cache.get(key) if cached: return cached if not path.exists(): path.parent.mkdir(parents=True, exist_ok=True) generated = secrets.token_urlsafe(32) descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) with os.fdopen(descriptor, "w", encoding="utf-8") as handle: handle.write(generated + "\n") _logger.warning("Generated a new ServiceMap admin token at %s", path) token = path.read_text(encoding="utf-8").strip() if len(token) < _MIN_TOKEN_LENGTH: raise AuthorizationError( f"The admin token in {path} must be at least {_MIN_TOKEN_LENGTH} characters" ) _token_cache[key] = token return token def reset_token_cache() -> None: with _token_lock: _token_cache.clear() def required_role(request: Request) -> str: path = request.url.path if request.method in SAFE_METHODS: # A full configuration export contains every endpoint and target; # settings hold notification targets. return "admin" if path.startswith(SECRET_READ_PREFIXES) else "viewer" if path.startswith( ( "/api/v1/config", "/api/v1/discovery", "/api/v1/docker", "/api/v1/maintenance", # Demo replaces the whole live topology. "/api/v1/demo", "/api/v1/settings", "/api/v1/backups", ) ): return "admin" return "operator" _LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"}) def _host_name(value: str) -> str: value = value.strip().casefold() if value.startswith("["): # IPv6 literal with optional port return value[1:].split("]", 1)[0] return value.rsplit(":", 1)[0] if value.count(":") == 1 else value def check_request_origin(request: Request) -> None: """Refuse DNS-rebinding hosts and cross-site mutations. * ``SERVICEMAP_ALLOWED_HOSTS`` (comma separated, optional): when set, requests for any other Host are refused. Loopback is always allowed for the container healthcheck. * A mutating request whose ``Origin`` is not this server, or that a browser marks ``Sec-Fetch-Site: cross-site``, is refused. Requests without these headers (curl, integrations) are unaffected. """ host_header = request.headers.get("host", "") # Behind a reverse proxy the public name arrives as X-Forwarded-Host. forwarded = request.headers.get("x-forwarded-host", "").split(",")[0].strip() public_host = _host_name(forwarded or host_header) allowed = _csv("SERVICEMAP_ALLOWED_HOSTS") if allowed and public_host not in allowed | _LOOPBACK_HOSTS and _host_name(host_header) not in _LOOPBACK_HOSTS: raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Deze host is niet toegestaan") if request.method in SAFE_METHODS: return if request.headers.get("sec-fetch-site", "").casefold() == "cross-site": raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Verzoek van een andere site geweigerd") origin = request.headers.get("origin") if origin is not None: parsed = urlparse(origin) # Hostnames are compared without ports: proxies (nginx ``$host``, # NPM) commonly drop the port from Host while Origin keeps it. if origin == "null" or not parsed.hostname or parsed.hostname.casefold() != public_host: raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Verzoek van een andere origin geweigerd") def authorize_request(request: Request) -> None: """Authorize API requests; health and static content remain reachable. Disabled mode preserves v1.5 behavior intentionally. Enabling OIDC with incomplete configuration fails closed on the API while `/health` remains available for recovery and deployment diagnostics. """ check_request_origin(request) if request.url.path in {"/health", "/ready"} or not request.url.path.startswith("/api/"): return try: config = AuthConfig.from_environment() except AuthorizationError as exc: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc) ) from exc if config.mode == "disabled": return header = request.headers.get("Authorization", "") if config.mode == "token": if request.method in SAFE_METHODS and not request.url.path.startswith(TOKEN_READ_PREFIXES): return try: expected = admin_token() except (AuthorizationError, OSError) as exc: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="Het beheerderstoken is niet beschikbaar" ) from exc supplied = header.removeprefix("Bearer ").strip() if header.startswith("Bearer ") else "" if not supplied or not hmac.compare_digest(supplied.encode(), expected.encode()): raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Bewerken vraagt het ServiceMap-beheerderstoken", headers={"WWW-Authenticate": "Bearer"}, ) return if not header.startswith("Bearer "): raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Bearer-authenticatie is vereist" ) try: roles = verify_bearer(header.removeprefix("Bearer ").strip(), config) except AuthorizationError as exc: raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=str(exc)) from exc if ( _ROLE_ORDER.get(max(roles, key=lambda item: _ROLE_ORDER[item]) if roles else "", 0) < _ROLE_ORDER[required_role(request)] ): raise HTTPException( status_code=status.HTTP_403_FORBIDDEN, detail="Onvoldoende ServiceMap-rol" )