dagster-authentication 0.1.0__py3-none-any.whl

dagster_authentication/__init__.py

@@ -0,0 +1,74 @@
+"""Microsoft Entra ID authentication and role-based authorisation for Dagster OSS.
+
+Dagster OSS ships no authentication. This package adds Entra sign-in inside the
+webserver process - no reverse proxy, no extra service - and enforces a role on
+every request, including the GraphQL subscription WebSocket.
+
+Usual use is the console script, a drop-in for ``dagster-webserver``::
+
+    dagster-authentication -w workspace.yaml -h 0.0.0.0 -p 443 \\
+        --ssl-certfile cert.pem --ssl-keyfile key.pem
+
+To embed it in your own entrypoint instead, wrap the Dagster ASGI app
+yourself::
+
+    from dagster_authentication import AuthConfig, build_app, build_authorizer
+
+    config = AuthConfig.from_env()
+    app = build_app(context, config, build_authorizer("identity"))
+
+Authorisation is pluggable: implement the ``Authorizer`` protocol to gate on
+whatever store you already have.
+"""
+
+from typing import TYPE_CHECKING
+
+from dagster_authentication.authorizer import (
+    AllowListAuthorizer,
+    AuthorizationUnavailable,
+    Authorizer,
+    Decision,
+)
+from dagster_authentication.config import AuthConfig, ConfigError
+from dagster_authentication.rbac import Role
+
+# Importing these pulls in Dagster and Starlette, which is a second or two and
+# a large dependency tree. Deferring them keeps `dagster_authentication.rbac` and the
+# authorizers usable - and testable - on their own.
+_LAZY = {
+    "AuthGate": "dagster_authentication.gate",
+    "build_app": "dagster_authentication.serve",
+    "build_authorizer": "dagster_authentication.serve",
+    "main": "dagster_authentication.serve",
+}
+
+if TYPE_CHECKING:  # pragma: no cover
+    from dagster_authentication.gate import AuthGate
+    from dagster_authentication.serve import build_app, build_authorizer, main
+
+__all__ = [
+    "AllowListAuthorizer",
+    "AuthConfig",
+    "AuthGate",
+    "AuthorizationUnavailable",
+    "Authorizer",
+    "ConfigError",
+    "Decision",
+    "Role",
+    "build_app",
+    "build_authorizer",
+    "main",
+]
+
+
+def __getattr__(name: str):
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    return getattr(import_module(module_name), name)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

dagster_authentication/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m dagster_authentication`` - equivalent to the ``dagster-authentication`` script."""
+
+from dagster_authentication.serve import main
+
+if __name__ == "__main__":
+    main()

dagster_authentication/authorizer.py

@@ -0,0 +1,115 @@
+"""The authorisation boundary.
+
+Entra proves *who* signed in. An ``Authorizer`` decides what they may do, so a
+project can gate on whatever it already uses - a central identity app, a list of
+addresses in the environment, or something of its own - without touching the
+sign-in flow or the request gate.
+
+Two rules every implementation must follow:
+
+1. Return ``Decision.deny(...)`` when the user has no access.
+2. Raise :class:`AuthorizationUnavailable` when the answer cannot be
+   determined. Callers turn that into a 503. Treating an unreachable
+   authorisation store as "no access" is the only safe reading - the
+   alternative is that an outage silently opens the server to everyone who can
+   authenticate.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from dagster_authentication.config import DEFAULT_ENV_PREFIX, csv_env
+from dagster_authentication.rbac import Role
+
+logger = logging.getLogger("dagster_authentication")
+
+DEFAULT_DENIAL_MESSAGE = "You do not have access to this application."
+
+
+class AuthorizationUnavailable(RuntimeError):
+    """The authorisation store could not be consulted, so access is refused."""
+
+
+@dataclass(frozen=True)
+class Decision:
+    """The outcome of an authorisation check.
+
+    ``reason`` is for the service log and may name identifiers; ``message`` is
+    shown to the user and should stay free of internal detail.
+    """
+
+    role: Role | None
+    reason: str = ""
+    message: str = ""
+
+    @property
+    def allowed(self) -> bool:
+        return self.role is not None
+
+    @classmethod
+    def allow(cls, role: Role, reason: str = "") -> Decision:
+        return cls(role=role, reason=reason)
+
+    @classmethod
+    def deny(cls, reason: str, message: str = DEFAULT_DENIAL_MESSAGE) -> Decision:
+        return cls(role=None, reason=reason, message=message)
+
+
+@runtime_checkable
+class Authorizer(Protocol):
+    """Decides the role for an authenticated user."""
+
+    name: str
+
+    def decide(self, claims: Mapping[str, Any]) -> Decision:
+        """Map ID-token claims onto a role, or deny."""
+        ...
+
+
+class AllowListAuthorizer:
+    """Authorises against explicit lists of addresses or object ids.
+
+    For projects with no central access store. Entries are matched against the
+    Entra object id (``oid``) and the sign-in name (``preferred_username``),
+    case-insensitively, so either form works::
+
+        DAGSTER_AUTH_ADMINS=ada@example.com,3f2504e0-4f89-11d3-9a0c-0305e82c3301
+        DAGSTER_AUTH_VIEWERS=grace@example.com
+
+    Admin wins when an identifier appears in both lists.
+    """
+
+    name = "allowlist"
+
+    def __init__(self, admins: frozenset[str], viewers: frozenset[str] = frozenset()) -> None:
+        self.admins = frozenset(entry.casefold() for entry in admins)
+        self.viewers = frozenset(entry.casefold() for entry in viewers)
+        if not self.admins and not self.viewers:
+            # Guarded here as well as at startup: an empty allow-list authorises
+            # nobody, which is never what the operator meant.
+            raise ValueError("an allow-list authorizer needs at least one admin or viewer")
+
+    @classmethod
+    def from_env(cls, env_prefix: str = DEFAULT_ENV_PREFIX) -> AllowListAuthorizer:
+        return cls(csv_env(f"{env_prefix}_ADMINS"), csv_env(f"{env_prefix}_VIEWERS"))
+
+    def _identifiers(self, claims: Mapping[str, Any]) -> set[str]:
+        values = (claims.get("oid"), claims.get("preferred_username"), claims.get("email"))
+        return {str(value).casefold() for value in values if value}
+
+    def decide(self, claims: Mapping[str, Any]) -> Decision:
+        identifiers = self._identifiers(claims)
+        if not identifiers:
+            return Decision.deny(
+                "the ID token carried neither an oid nor a sign-in name",
+                "Sign-in succeeded, but the token did not identify your account.",
+            )
+        if identifiers & self.admins:
+            return Decision.allow(Role.ADMIN)
+        if identifiers & self.viewers:
+            return Decision.allow(Role.VIEWER)
+        return Decision.deny(f"none of {sorted(identifiers)} is on the allow-list")

dagster_authentication/config.py

@@ -0,0 +1,115 @@
+"""Environment-driven configuration for the authentication layer.
+
+Everything is read and validated once at startup: a misconfigured webserver
+should fail to boot loudly rather than come up serving unauthenticated traffic.
+
+This module covers *authentication* only. Authorisation - who may use Dagster
+and at what level - is decided by an :class:`~dagster_authentication.authorizer.Authorizer`.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+DEFAULT_ENV_PREFIX = "DAGSTER_AUTH"
+DEFAULT_SESSION_MAX_AGE = 8 * 3600
+DEFAULT_SESSION_COOKIE = "dagster_authentication_session"
+MIN_SESSION_SECRET_LEN = 32
+
+# Hosts for which Entra permits a plain-http redirect URI.
+LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+class ConfigError(RuntimeError):
+    """Raised at startup when configuration is missing or unusable."""
+
+
+def required_env(name: str) -> str:
+    value = os.environ.get(name, "").strip()
+    if not value:
+        raise ConfigError(f"{name} is not set - refusing to start without it")
+    return value
+
+
+def positive_int_env(name: str, default: int) -> int:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ConfigError(f"{name} must be an integer, got {raw!r}") from None
+    if value <= 0:
+        raise ConfigError(f"{name} must be positive, got {value}")
+    return value
+
+
+def csv_env(name: str) -> frozenset[str]:
+    """A comma-separated environment variable as a set of trimmed entries."""
+    return frozenset(part.strip() for part in os.environ.get(name, "").split(",") if part.strip())
+
+
+def _redirect_uri_allowed(uri: str) -> bool:
+    """Entra accepts https anywhere, and http only on the loopback host.
+
+    Mirroring that rule here means --allow-insecure-http is actually usable for
+    local development instead of failing validation before startup.
+    """
+    if uri.startswith("https://"):
+        return True
+    if not uri.startswith("http://"):
+        return False
+    return urlsplit(uri).hostname in LOOPBACK_HOSTS
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    tenant_id: str
+    client_id: str
+    client_secret: str
+    redirect_uri: str
+    session_secret: str
+    session_max_age: int
+    session_cookie: str
+    path_prefix: str
+    env_prefix: str = DEFAULT_ENV_PREFIX
+
+    @property
+    def authority(self) -> str:
+        return f"https://login.microsoftonline.com/{self.tenant_id}"
+
+    @classmethod
+    def from_env(cls, path_prefix: str = "", env_prefix: str = DEFAULT_ENV_PREFIX) -> AuthConfig:
+        """Read and validate the authentication settings.
+
+        ``env_prefix`` lets a project namespace its variables; the default
+        expects ``DAGSTER_AUTH_TENANT_ID`` and friends.
+        """
+        def var(suffix: str) -> str:
+            return f"{env_prefix}_{suffix}"
+
+        config = cls(
+            tenant_id=required_env(var("TENANT_ID")),
+            client_id=required_env(var("CLIENT_ID")),
+            client_secret=required_env(var("CLIENT_SECRET")),
+            redirect_uri=required_env(var("REDIRECT_URI")),
+            session_secret=required_env(var("SESSION_SECRET")),
+            session_max_age=positive_int_env(var("SESSION_MAX_AGE"), DEFAULT_SESSION_MAX_AGE),
+            session_cookie=os.environ.get(var("SESSION_COOKIE"), "").strip()
+            or DEFAULT_SESSION_COOKIE,
+            path_prefix=path_prefix.rstrip("/"),
+            env_prefix=env_prefix,
+        )
+
+        if len(config.session_secret) < MIN_SESSION_SECRET_LEN:
+            raise ConfigError(
+                f"{var('SESSION_SECRET')} must be at least {MIN_SESSION_SECRET_LEN} characters"
+            )
+        if not _redirect_uri_allowed(config.redirect_uri):
+            raise ConfigError(
+                f"{var('REDIRECT_URI')} must be https, or http on localhost - those are the "
+                f"only redirect URIs Entra accepts. Got {config.redirect_uri!r}"
+            )
+        return config

dagster_authentication/entra.py

@@ -0,0 +1,146 @@
+"""Entra ID (Azure AD) OpenID Connect sign-in, via MSAL.
+
+MSAL owns the parts of the authorisation-code flow that are easy to get subtly
+wrong - the state parameter, the nonce, and the PKCE verifier - so this module
+only persists the flow between the two requests and maps claims onto a session.
+
+Entra proves *who* the user is. What they may do is decided by the configured
+:class:`~dagster_authentication.authorizer.Authorizer`.
+
+The route handlers are deliberately synchronous. MSAL performs blocking network
+calls (OIDC discovery, the token exchange) and an authorizer may hit a
+database; Starlette runs non-async endpoints in a threadpool, so declaring them
+``async def`` would stall the event loop for every other request during a
+sign-in.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import msal
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, PlainTextResponse, RedirectResponse, Response
+from starlette.routing import Route, Router
+
+from dagster_authentication.authorizer import AuthorizationUnavailable, Authorizer
+from dagster_authentication.config import AuthConfig
+
+logger = logging.getLogger("dagster_authentication")
+
+# No groups claim is needed on the app registration: authorisation is the
+# authorizer's job, not a token claim. MSAL adds the reserved
+# openid/profile/offline_access scopes itself.
+SCOPES: list[str] = []
+
+_SIGNED_OUT_PAGE = """<!doctype html>
+<title>Signed out</title>
+<style>
+  body {{ font: 15px/1.6 system-ui, sans-serif; margin: 15vh auto; max-width: 28rem;
+         padding: 0 1.5rem; color: #1a1a1a; }}
+  a {{ color: #0b6bcb; }}
+</style>
+<h1>Signed out</h1>
+<p>Your session has ended.</p>
+<p><a href="{login}">Sign in again</a></p>
+<p style="color:#666;font-size:.9em">You are still signed in to Microsoft. Sign
+out of your Microsoft account too if you are on a shared machine.</p>
+"""
+
+
+def build_auth_router(config: AuthConfig, authorizer: Authorizer) -> Router:
+    """The /auth routes: the only unauthenticated surface of the server."""
+    # Built once. Constructing a ConfidentialClientApplication performs OIDC
+    # discovery, so doing it per request would add a round trip to every login.
+    client = msal.ConfidentialClientApplication(
+        config.client_id,
+        authority=config.authority,
+        client_credential=config.client_secret,
+    )
+
+    prefix = config.path_prefix
+    login_path = f"{prefix}/auth/login"
+    home_path = prefix or "/"
+
+    def login(request: Request) -> Response:
+        flow = client.initiate_auth_code_flow(SCOPES, redirect_uri=config.redirect_uri)
+        request.session.clear()
+        request.session["flow"] = flow
+        return RedirectResponse(url=flow["auth_uri"], status_code=302)
+
+    def callback(request: Request) -> Response:
+        flow = request.session.pop("flow", None)
+        if not isinstance(flow, dict):
+            # No flow in the session: a bookmarked callback, a replay, or the
+            # cookie expired mid-sign-in. Start over rather than erroring.
+            return RedirectResponse(url=login_path, status_code=302)
+
+        try:
+            result = client.acquire_token_by_auth_code_flow(flow, dict(request.query_params))
+        except ValueError as exc:
+            # MSAL raises this on a state mismatch or a replayed callback.
+            logger.warning("rejected auth callback: %s", exc)
+            return PlainTextResponse("Sign-in could not be verified. Please try again.", 400)
+
+        if "error" in result:
+            detail = result.get("error_description") or result["error"]
+            logger.warning("Entra returned an error: %s", detail)
+            return PlainTextResponse(f"Sign-in failed: {detail}", 403)
+
+        claims = result.get("id_token_claims") or {}
+        user = claims.get("preferred_username")
+
+        if claims.get("tid") != config.tenant_id:
+            logger.warning("rejected token from tenant %s", claims.get("tid"))
+            return PlainTextResponse("This account is from an unrecognised tenant.", 403)
+
+        try:
+            decision = authorizer.decide(claims)
+        except AuthorizationUnavailable as exc:
+            # Fail closed: an unreachable authorisation store must not mean
+            # "allow everyone who can authenticate".
+            logger.error("denied %s: %s", user, exc)
+            return PlainTextResponse(
+                "Your access could not be verified because the authorisation service is "
+                "unavailable. Please try again shortly.",
+                503,
+            )
+
+        if not decision.allowed:
+            logger.warning("denied %s via %s: %s", user, authorizer.name, decision.reason)
+            return PlainTextResponse(decision.message, 403)
+
+        assert decision.role is not None  # narrowed by decision.allowed
+        request.session.clear()
+        request.session.update(
+            {
+                "role": int(decision.role),
+                "sub": claims.get("sub"),
+                "oid": claims.get("oid"),
+                "email": user,
+                "name": claims.get("name"),
+            }
+        )
+        logger.info("signed in %s as %s", user, decision.role.name)
+        return RedirectResponse(url=home_path, status_code=302)
+
+    def logout(request: Request) -> Response:
+        user = request.session.get("email")
+        request.session.clear()
+        if user:
+            logger.info("signed out %s", user)
+        return HTMLResponse(_SIGNED_OUT_PAGE.format(login=login_path))
+
+    def health(_: Request) -> Response:
+        # Public by design so an uptime monitor can poll without a session.
+        # Returns nothing about versions or workspace contents.
+        return PlainTextResponse("ok")
+
+    return Router(
+        routes=[
+            Route(f"{prefix}/auth/login", login, methods=["GET"]),
+            Route(f"{prefix}/auth/callback", callback, methods=["GET"]),
+            Route(f"{prefix}/auth/logout", logout, methods=["GET"]),
+            Route(f"{prefix}/auth/health", health, methods=["GET"]),
+        ]
+    )