keepup-admin 0.1.0__py3-none-any.whl

keepup/auth/oidc_routes.py

@@ -0,0 +1,288 @@
+"""The two endpoints of the external sign-in, and what happens between them.
+
+``/api/auth/oidc/login`` sends the browser to the provider;
+``/api/auth/oidc/callback`` receives it back, checks everything
+(:mod:`keepup.auth.oidc`), decides whether somebody unknown may have an account
+(:mod:`keepup.auth.oidc_policy`), and ends by issuing the ordinary session of
+this application -- the same token and the same cookie a local sign-in gives,
+so the panel, the renewal and the logout know nothing about how the person got
+in.
+
+Registered only when the application configured a provider. Without one the
+paths do not exist: the possibility is off, not broken, and a 404 there is the
+truthful answer.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from fastapi import HTTPException, Request, Response, status
+from fastapi.responses import RedirectResponse
+
+from keepup.auth import oidc, oidc_policy, panel_session
+from keepup.auth.dependencies import issue_session_token
+from keepup.db import DatabaseManager, DatabaseManagerV2, db_config
+from keepup.roles import ROLE_ADMIN, ROLE_CLIENT
+
+logger = logging.getLogger(__name__)
+
+#: Permissions that make somebody an administrator here. Mapping a claim onto
+#: one of them is how a provider's role becomes a role in this application.
+ADMIN_PERMISSIONS = ("admin", "manage_users", "manage_settings")
+
+
+def _refuse(reason: str) -> HTTPException:
+    """One answer for every failed check; the reason stays in the log.
+
+    Telling the caller which check failed says which ones they passed, and that
+    is a map for whoever is probing.
+    """
+    logger.warning(f"OIDC sign-in refused: {reason}")
+    return HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=oidc.REFUSAL)
+
+
+# --- the account behind the claims --------------------------------------------
+
+def find_account(issuer: str, subject: str) -> Optional[Dict[str, Any]]:
+    """The account tied to this provider's subject, if there is one.
+
+    Looked up by subject rather than by email: an address at a provider changes
+    hands, and matching on it would let a new employee into the account of the
+    person whose address they inherited.
+    """
+    rows = DatabaseManagerV2.execute(
+        "SELECT id, username, status, role FROM users "
+        "WHERE auth_source = :source AND external_id = :subject",
+        {"source": issuer, "subject": str(subject)},
+    )
+    return dict(rows[0]) if rows else None
+
+
+def propose_username(claims: Dict[str, Any]) -> str:
+    """A name for the new account, taken from what the provider said."""
+    for claim in ("preferred_username", "email", "sub"):
+        value = claims.get(claim)
+        if value:
+            return str(value).strip().lower()
+    return "user"
+
+
+def free_username(proposed: str) -> str:
+    """The proposed name, or the first free variant of it.
+
+    Names are unique here and come from somewhere else entirely; two providers,
+    or two people at one provider, can propose the same one.
+    """
+    candidate = proposed
+    suffix = 1
+    while DatabaseManagerV2.execute_one(
+            "SELECT id FROM users WHERE username = :name", {"name": candidate}):
+        suffix += 1
+        candidate = f"{proposed}-{suffix}"
+    return candidate
+
+
+def create_account(issuer: str, claims: Dict[str, Any],
+                   decision: oidc_policy.AccountDecision) -> Dict[str, Any]:
+    """Create the account the application's policy agreed to.
+
+    The password column is filled with an unusable value rather than left
+    empty: this account has no password here, and a blank one is something a
+    local sign-in might one day accept.
+    """
+    username = free_username(propose_username(claims))
+    DatabaseManagerV2.execute_commit(
+        "INSERT INTO users (username, password_hash, status, role, email, full_name, "
+        "auth_source, external_id, agree_terms) "
+        "VALUES (:username, :password_hash, :status, :role, :email, :full_name, "
+        ":source, :subject, :agree_terms)",
+        {
+            "username": username,
+            "password_hash": "!external",
+            "status": decision.status,
+            "role": decision.role,
+            "email": claims.get("email"),
+            "full_name": claims.get("name"),
+            "source": issuer,
+            "subject": str(claims["sub"]),
+            "agree_terms": False,
+        },
+    )
+    logger.info(f"OIDC account created for {issuer} subject: {username} ({decision.reason})")
+    account = find_account(issuer, claims["sub"])
+    if account is None:
+        raise _refuse("the account was created but cannot be read back")
+    return account
+
+
+# --- roles out of the claims ---------------------------------------------------
+
+def external_roles(claims: Dict[str, Any], roles_claim: str) -> List[str]:
+    """The provider's roles, however this provider chose to shape them."""
+    value = claims.get(roles_claim)
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [part for part in value.replace(",", " ").split() if part]
+    if isinstance(value, (list, tuple)):
+        return [str(part) for part in value if part]
+    return []
+
+
+def permissions_for(issuer: str, roles: List[str]) -> Dict[str, bool]:
+    """Map the provider's roles onto permissions here.
+
+    Through the same table the directory provider used, keyed by the issuer:
+    which outside role means what is a property of the deployment, not of the
+    code.
+    """
+    granted: Dict[str, bool] = {}
+    for role in roles:
+        rows = DatabaseManagerV2.execute(
+            "SELECT internal_permission_name FROM external_role_mappings "
+            "WHERE auth_source = :source AND external_role_name = :role",
+            {"source": issuer, "role": role},
+        )
+        for row in rows:
+            granted[row["internal_permission_name"]] = True
+    return granted
+
+
+def apply_permissions(user_id: int, permissions: Dict[str, bool]) -> None:
+    """Write this sign-in's permissions, replacing what was there.
+
+    Replaced rather than added to: a permission taken away at the provider has
+    to disappear here as well, and that is the whole reason a central sign-in
+    is worth having.
+    """
+    DatabaseManagerV2.execute_commit(
+        "DELETE FROM user_permissions WHERE user_id = :user_id", {"user_id": user_id})
+    for name, granted in permissions.items():
+        DatabaseManagerV2.execute_commit(
+            "INSERT INTO user_permissions (user_id, permission_name, granted) "
+            "VALUES (:user_id, :name, :granted)",
+            {"user_id": user_id, "name": name, "granted": bool(granted)},
+        )
+
+
+def role_from_permissions(permissions: Dict[str, bool], default_role: str) -> str:
+    """An administrator is somebody holding an administrative permission."""
+    if any(permissions.get(name) for name in ADMIN_PERMISSIONS):
+        return ROLE_ADMIN
+    return default_role or ROLE_CLIENT
+
+
+def sync_roles(account: Dict[str, Any], issuer: str, claims: Dict[str, Any],
+               settings) -> str:
+    """Recompute what this person may do, from what the provider said just now."""
+    permissions = permissions_for(issuer, external_roles(claims, settings.roles_claim))
+    apply_permissions(account["id"], permissions)
+
+    role = role_from_permissions(permissions, settings.default_role)
+    if role != account.get("role"):
+        DatabaseManagerV2.execute_commit(
+            "UPDATE users SET role = :role WHERE id = :user_id",
+            {"role": role, "user_id": account["id"]},
+        )
+        logger.info(f"OIDC role for {account['username']}: {account.get('role')} -> {role}")
+    return role
+
+
+# --- the endpoints -------------------------------------------------------------
+
+def register_oidc_routes(app, settings) -> None:
+    """Register external sign-in, if this application configured a provider."""
+    if settings.oidc is None:
+        return
+
+    provider = settings.oidc
+    directory = oidc.ProviderDirectory(provider)
+    app.state.oidc_directory = directory
+
+    @app.get("/api/auth/oidc/login", include_in_schema=False)
+    async def oidc_login(request: Request):
+        """Send the browser to the provider to have the person identified.
+
+        Takes the request only to decide whether the flow cookie may be marked
+        Secure -- the same question the session cookie asks.
+        """
+        try:
+            metadata = await directory.metadata()
+        except Exception as error:
+            logger.error(f"OIDC provider unreachable: {error}")
+            raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                                detail="The identity provider is unavailable")
+
+        state = oidc.secrets.token_urlsafe(16)
+        nonce = oidc.secrets.token_urlsafe(16)
+        verifier, challenge = oidc.make_pkce_pair()
+
+        response = RedirectResponse(
+            oidc.authorization_url(metadata, provider, state, nonce, challenge),
+            status_code=status.HTTP_303_SEE_OTHER,
+        )
+        response.set_cookie(
+            oidc.FLOW_COOKIE,
+            oidc.issue_flow_token(state, nonce, verifier),
+            max_age=oidc.FLOW_COOKIE_MAX_AGE,
+            path="/api/auth/oidc",
+            httponly=True,
+            samesite="lax",
+            # It carries the PKCE verifier, the nonce and the state. This was
+            # False unconditionally -- not even asking, the way the session
+            # cookie does -- so on an HTTPS deployment it still went out over a
+            # forced plain request to the same host (task keepup-14).
+            secure=panel_session.is_https(request),
+        )
+        return response
+
+    @app.get("/api/auth/oidc/callback", include_in_schema=False)
+    async def oidc_callback(request: Request, code: str = None, state: str = None,
+                            error: str = None):
+        """Receive the person back and, if everything checks out, let them in."""
+        if error:
+            raise _refuse(f"the provider answered with an error: {error}")
+        if not code or not state:
+            raise _refuse("the return carries no code or no state")
+
+        try:
+            flow = oidc.read_flow_token(request.cookies.get(oidc.FLOW_COOKIE))
+            if flow.get("state") != state:
+                raise oidc.SignInRefused("the state does not belong to this attempt")
+
+            tokens = await oidc.exchange_code(directory, provider, code, flow["verifier"])
+            claims = await oidc.verify_id_token(directory, provider,
+                                                tokens["id_token"], flow["nonce"])
+        except oidc.SignInRefused as refusal:
+            raise _refuse(str(refusal))
+        except Exception as error:
+            raise _refuse(f"the exchange failed: {error}")
+
+        issuer = (await directory.metadata()).issuer
+        account = find_account(issuer, claims["sub"])
+
+        if account is None:
+            decision = oidc_policy.decide(settings.oidc_account_policy, claims)
+            if not decision.admit:
+                raise _refuse(f"policy refused a new account: {decision.reason}")
+            account = create_account(issuer, claims, decision)
+
+        if account.get("status") != "active":
+            # Proving who you are is not the same as being allowed in.
+            raise _refuse(f"the account {account['username']} is not active")
+
+        sync_roles(account, issuer, claims, provider)
+
+        issued = issue_session_token(account["id"], account["username"])
+        response = RedirectResponse(provider.after_login_path,
+                                    status_code=status.HTTP_303_SEE_OTHER)
+        panel_session.set_cookies(response, request, issued["access_token"],
+                                  issued["expires_in"])
+        # One attempt, one use: the cookie is spent, so a replayed return finds
+        # nothing to check itself against.
+        response.delete_cookie(oidc.FLOW_COOKIE, path="/api/auth/oidc")
+
+        logger.info(f"OIDC sign-in: {account['username']} via {issuer}")
+        if settings.record_login is not None:
+            await settings.record_login(dict(account))
+        return response

keepup/auth/panel_session.py

@@ -0,0 +1,220 @@
+"""The panel session: a server-side record, carried in an httpOnly cookie.
+
+The token used to live in localStorage, where any script on the page could read
+it and take the whole session away with it; logging out only forgot it in that
+one browser, and a copied token stayed good for a day. Now a session is a row,
+the token names it (`sid`), and every request looks the row up -- so a logout, a
+password change or a block takes effect on every replica at once.
+
+The browser never sees the token: it sits in `ss_session` (HttpOnly). The panel
+keeps the non-secret marker `cookie` where the token used to be, so the many
+sections that check "is there a token" and send `Bearer <token>` keep working;
+the server reads such a header as no header at all and falls back to the cookie.
+
+A cookie is sent by the browser on its own, so a request authenticated by it must
+also prove it came from the panel: the double-submit `ss_csrf` cookie, readable by
+the page, echoed in `X-CSRF-Token`. A real `Authorization: Bearer` (an agent, a
+script) needs no such proof -- another site cannot set that header.
+"""
+
+import logging
+import os
+import secrets
+from datetime import datetime, timedelta
+from typing import Optional
+from urllib.parse import urlparse
+
+from fastapi import HTTPException, Request
+from sqlalchemy import Column, DateTime, Index, Integer, String, Text
+from starlette import status
+
+from keepup import tables
+from keepup.db import DatabaseManagerV2
+
+logger = logging.getLogger(__name__)
+
+TABLE = "auth_session"
+SESSION_CLAIM = "sid"
+SESSION_COOKIE = "ss_session"
+CSRF_COOKIE = "ss_csrf"
+CSRF_HEADER = "X-CSRF-Token"
+
+#: What the panel keeps in localStorage instead of the token, and the values a
+#: section sends when it had nothing there. None of them is a credential.
+BEARER_PLACEHOLDERS = frozenset({"", "cookie", "null", "undefined"})
+SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+REASON_LOGOUT = "logout"
+REASON_PASSWORD_CHANGED = "password_changed"
+REASON_ACCOUNT_BLOCKED = "account_blocked"
+
+
+AUTH_SESSION = tables.table(
+    TABLE,
+    Column("sid", String(64).with_variant(Text(), "sqlite"), primary_key=True, nullable=True),
+    Column("user_id", Integer, nullable=False),
+    Column("created_at", DateTime, nullable=False),
+    Column("expires_at", DateTime, nullable=False),
+    Column("revoked_at", DateTime),
+    Column("revoked_reason", String(64).with_variant(Text(), "sqlite")),
+    Index(f"idx_{TABLE}_user", "user_id"),
+)
+
+
+def init_table() -> None:
+    tables.ensure_tables(AUTH_SESSION)
+    # Each start is often enough: a row past its end is only kept for inquiry.
+    purge_expired()
+
+
+# --- the record ------------------------------------------------------------------------------
+
+def open_session(user_id: int, lifetime: timedelta, now: Optional[datetime] = None) -> str:
+    now = now or datetime.utcnow()
+    sid = secrets.token_urlsafe(32)
+    DatabaseManagerV2.execute_commit(
+        f"INSERT INTO {TABLE} (sid, user_id, created_at, expires_at) "
+        f"VALUES (:sid, :user_id, :now, :expires_at)",
+        {"sid": sid, "user_id": user_id, "now": now, "expires_at": now + lifetime})
+    return sid
+
+
+def extend(sid: str, lifetime: timedelta, now: Optional[datetime] = None) -> None:
+    """A renewal keeps the session and moves its end, like the token it renews."""
+    now = now or datetime.utcnow()
+    DatabaseManagerV2.execute_commit(
+        f"UPDATE {TABLE} SET expires_at = :expires_at WHERE sid = :sid AND revoked_at IS NULL",
+        {"sid": sid, "expires_at": now + lifetime})
+
+
+def is_active(sid: str, user_id: Optional[int] = None) -> bool:
+    row = DatabaseManagerV2.execute_one(
+        f"SELECT user_id, revoked_at FROM {TABLE} WHERE sid = :sid", {"sid": sid})
+    if not row or row.get("revoked_at") is not None:
+        return False
+    # A session is somebody's: a token whose name and session disagree was not
+    # issued by this server.
+    return user_id is None or int(row["user_id"]) == int(user_id)
+
+
+def revoke(sid: str, reason: str = REASON_LOGOUT) -> int:
+    return DatabaseManagerV2.execute_commit(
+        f"UPDATE {TABLE} SET revoked_at = :now, revoked_reason = :reason "
+        f"WHERE sid = :sid AND revoked_at IS NULL",
+        {"sid": sid, "now": datetime.utcnow(), "reason": reason})
+
+
+def revoke_all(user_id: int, reason: str) -> int:
+    return DatabaseManagerV2.execute_commit(
+        f"UPDATE {TABLE} SET revoked_at = :now, revoked_reason = :reason "
+        f"WHERE user_id = :u AND revoked_at IS NULL",
+        {"u": user_id, "now": datetime.utcnow(), "reason": reason})
+
+
+def purge_expired(now: Optional[datetime] = None, keep: timedelta = timedelta(days=7)) -> int:
+    """Rows past their end serve nothing; a week is kept for whoever investigates."""
+    return DatabaseManagerV2.execute_commit(
+        f"DELETE FROM {TABLE} WHERE expires_at < :cutoff",
+        {"cutoff": (now or datetime.utcnow()) - keep})
+
+
+# --- where the token comes from --------------------------------------------------------------
+
+def real_bearer(value: Optional[str]) -> Optional[str]:
+    """The bearer token, or None when the header only carries a placeholder."""
+    if value is None or value.strip() in BEARER_PLACEHOLDERS:
+        return None
+    return value.strip()
+
+
+def token_from_request(request: Request, bearer: Optional[str]) -> Optional[str]:
+    """The token of this request: a real bearer first, the session cookie second.
+
+    A cookie-authenticated request that changes something must carry the CSRF
+    header; without it the answer is 403, not a quiet fall-through to anonymous.
+    """
+    token = real_bearer(bearer)
+    if token:
+        return token
+    token = request.cookies.get(SESSION_COOKIE)
+    if not token:
+        return None
+    if request.method.upper() not in SAFE_METHODS and not csrf_matches(request):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN,
+                            detail="CSRF token missing or invalid")
+    return token
+
+
+def csrf_matches(request: Request) -> bool:
+    expected = request.cookies.get(CSRF_COOKIE)
+    presented = request.headers.get(CSRF_HEADER)
+    return bool(expected and presented and secrets.compare_digest(expected, presented))
+
+
+def websocket_token(query_token: Optional[str], cookies) -> Optional[str]:
+    """A websocket has no CSRF header to send; `same_origin` stands in for it."""
+    return real_bearer(query_token) or (cookies or {}).get(SESSION_COOKIE)
+
+
+def same_origin(headers) -> bool:
+    """Whether the page that opened a websocket is served from this server.
+
+    Compared with the host the request names and with the public address: a proxy
+    that does not pass `Host` on still leaves the public address to match.
+    """
+    origin = urlparse((headers.get("origin") or "").strip()).netloc.lower()
+    if not origin:
+        return False
+    names = {(headers.get("x-forwarded-host") or "").split(",")[0].strip().lower(),
+             (headers.get("host") or "").strip().lower()}
+    api_host = (os.environ.get("API_HOST") or "").strip().lower()
+    if api_host:
+        names.add(urlparse(api_host if "://" in api_host else f"//{api_host}").netloc)
+    return origin in names - {""}
+
+
+# --- the cookies -----------------------------------------------------------------------------
+
+#: Set on a deployment behind a proxy that terminates TLS and does not say so.
+#: Without it the cookie goes out without Secure and travels over plain HTTP
+#: the first time somebody types the address without the scheme -- and there
+#: was no way to insist (task keepup-14).
+FORCE_SECURE_COOKIES_ENV = "FORCE_SECURE_COOKIES"
+
+
+def is_https(request: Request) -> bool:
+    """Whether the browser reached us over HTTPS -- the proxy says so, or the socket.
+
+    Not guessed from API_HOST: a direct http visit on the local network would then
+    get a Secure cookie the browser refuses to keep, and never stay signed in.
+    A deployment that knows better says so with FORCE_SECURE_COOKIES.
+
+    Args:
+        request: the incoming request.
+
+    Returns:
+        Whether the cookie may be marked Secure.
+    """
+    if os.getenv(FORCE_SECURE_COOKIES_ENV, "false").lower() == "true":
+        return True
+    forwarded = (request.headers.get("x-forwarded-proto") or "").split(",")[0].strip().lower()
+    if forwarded:
+        return forwarded == "https"
+    return request.url.scheme == "https"
+
+
+def set_cookies(response, request: Request, token: str, max_age: int) -> str:
+    secure = is_https(request)
+    response.set_cookie(SESSION_COOKIE, token, max_age=max_age, path="/",
+                        httponly=True, secure=secure, samesite="lax")
+    # Kept across renewals: a panel tab holding the old value would otherwise
+    # have its next change refused.
+    csrf = request.cookies.get(CSRF_COOKIE) or secrets.token_urlsafe(32)
+    response.set_cookie(CSRF_COOKIE, csrf, max_age=max_age, path="/",
+                        httponly=False, secure=secure, samesite="lax")
+    return csrf
+
+
+def clear_cookies(response) -> None:
+    response.delete_cookie(SESSION_COOKIE, path="/")
+    response.delete_cookie(CSRF_COOKIE, path="/")

keepup/auth/permissions.py

@@ -0,0 +1,59 @@
+"""Finer-grained rights than the two roles.
+
+`keepup.roles` has ADMIN and CLIENT, which is enough to decide who may reach an
+administrative route and not enough for anything else. A permission is checked
+per action, by decorator or by dependency, so a route can be opened to a
+non-administrator without opening the section around it.
+"""
+
+from functools import wraps
+from fastapi import HTTPException, status, Depends
+
+from keepup.roles import ROLE_ADMIN
+from keepup.auth.dependencies import get_all_users, get_current_user
+
+
+def require_permission(permission_name: str):
+    """Decorator checking that the user holds the given permission."""
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            current_user = kwargs.get('current_user')
+
+            if not current_user:
+                for arg in args:
+                    if isinstance(arg, dict) and 'username' in arg:
+                        current_user = arg
+                        break
+
+            if not current_user:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Authentication required"
+                )
+
+            permissions = current_user.get('permissions', {})
+
+            if not permissions.get(permission_name, False):
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=f"Permission '{permission_name}' required"
+                )
+
+            return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+# Example of how this is used on an endpoint:
+#@app.get("/api/admin/users")
+@require_permission(ROLE_ADMIN)
+async def get_all_users_endpoint(
+        current_user: dict = Depends(get_current_user)
+):
+    users = (
+get_all_users())
+    return users