ark-oauth-client 2.0.4__py3-none-any.whl

ark_oauth_client/__init__.py

@@ -0,0 +1,180 @@
+"""
+ark-oauth-client — the OAuth 2.1 / OpenID Connect client for Python applications talking to an Ark
+identity server.
+
+There is one URL to configure: the issuer, ``{BaseUrl}/{TenantId}``. Every endpoint, signing key and
+capability is read from the provider's discovery document, so an application does not need to be
+redeployed when the provider rotates a key or moves an endpoint.
+
+    from flask import Flask
+    from ark_oauth_client.flask import add_ark_oidc_client, current_ark
+
+    app = Flask(__name__)
+    app.secret_key = os.environ["ARK_SESSION_SECRET"]
+
+    auth = add_ark_oidc_client(app, {
+        "authority": "https://idp.example.com/my_idp",
+        "client_id": "my-app",
+    })
+
+    @app.get("/billing")
+    @auth.require_claims("billing.admin")
+    def billing():
+        return f"hello {current_ark.user['name']}"
+
+The Flask integration is one way in; :class:`ArkOAuthClient` is the whole protocol on its own, for
+CLIs, workers, Django, FastAPI and every flow without a browser.
+"""
+
+from .access import (
+    ArkAccessDeniedContext,
+    ArkAccessDeniedPage,
+    ArkAccessDeniedReasons,
+    ArkAccessDeniedState,
+    ArkAccessEvaluationContext,
+    ArkAccessGate,
+    ArkAccountSwitchOptions,
+    ArkChallengeProperties,
+    ArkClientEvents,
+    ArkClientOptions,
+    ArkDeniedAccount,
+    local_or_default,
+)
+from .auth_config import ArkAuthConfig, ArkCert, AUser, AUserInfo
+from .client import ArkOAuthClient, AuthorizationRequest, create_ark_client
+from .config import ArkConfig, DEFAULT_SCOPES, PrivateKeyJwt, normalize_config
+from .context import ArkAuthContext
+from .crypto import base64url_decode, base64url_encode, left_half_hash, random_token
+from .diagnostics import ArkClaimReader, ArkJson, ArkJwt
+from .discovery import ArkDiscoveryCache, MetadataResolver, discovery_urls
+from .errors import (
+    ArkCallbackError,
+    ArkConfigError,
+    ArkError,
+    ArkNetworkError,
+    ArkOAuthError,
+    ArkTokenError,
+)
+from .flows import ArkClientCredentials, ArkRegistration, ArkRegistrationResult, ArkTokenResult
+from .helper import AuthClientHelper
+from .jwks import JwksCache
+from .jwt import (
+    decode_jwt,
+    sign_jwt,
+    validate_claims,
+    validate_token_hashes,
+    verify_jwt,
+    verify_signature,
+)
+from .pkce import (
+    PkcePair,
+    code_challenge_for,
+    create_code_verifier,
+    create_nonce,
+    create_pkce_pair,
+    create_state,
+)
+from .probe import ArkProviderMetadata, ArkSetupModel, ArkSetupProbe
+from .session import (
+    MemorySessionStore,
+    SessionStore,
+    create_session_id,
+    sign_session_id,
+    unsign_session_id,
+)
+from .tokens import TokenSet
+
+__version__ = "2.0.4"
+
+#: The PKCE helpers under the name the .NET package gives them.
+PkceHelper = type(
+    "PkceHelper",
+    (),
+    {
+        "generate_code_verifier": staticmethod(create_code_verifier),
+        "generate_code_challenge": staticmethod(code_challenge_for),
+        "__doc__": "PKCE helpers, under the .NET client's name for them.",
+    },
+)
+
+__all__ = [
+    "__version__",
+    # protocol client
+    "ArkOAuthClient",
+    "AuthorizationRequest",
+    "create_ark_client",
+    "TokenSet",
+    # configuration
+    "ArkConfig",
+    "ArkAuthConfig",
+    "ArkCert",
+    "AUser",
+    "AUserInfo",
+    "PrivateKeyJwt",
+    "normalize_config",
+    "DEFAULT_SCOPES",
+    # discovery and keys
+    "MetadataResolver",
+    "ArkDiscoveryCache",
+    "discovery_urls",
+    "JwksCache",
+    # tokens
+    "decode_jwt",
+    "verify_jwt",
+    "verify_signature",
+    "validate_claims",
+    "validate_token_hashes",
+    "sign_jwt",
+    # pkce
+    "PkcePair",
+    "PkceHelper",
+    "create_code_verifier",
+    "code_challenge_for",
+    "create_pkce_pair",
+    "create_state",
+    "create_nonce",
+    "base64url_encode",
+    "base64url_decode",
+    "left_half_hash",
+    "random_token",
+    # sessions
+    "SessionStore",
+    "MemorySessionStore",
+    "create_session_id",
+    "sign_session_id",
+    "unsign_session_id",
+    # diagnostics
+    "ArkSetupProbe",
+    "ArkSetupModel",
+    "ArkProviderMetadata",
+    "ArkJwt",
+    "ArkJson",
+    "ArkClaimReader",
+    "ArkAuthContext",
+    # flows
+    "ArkClientCredentials",
+    "ArkTokenResult",
+    "ArkRegistration",
+    "ArkRegistrationResult",
+    "AuthClientHelper",
+    # account switching
+    "ArkAccountSwitchOptions",
+    "ArkAccessDeniedReasons",
+    "ArkAccessDeniedContext",
+    "ArkAccessEvaluationContext",
+    "ArkAccessDeniedPage",
+    "ArkAccessDeniedState",
+    "ArkAccessGate",
+    "ArkChallengeProperties",
+    "ArkClientEvents",
+    "ArkClientOptions",
+    "ArkDeniedAccount",
+    "local_or_default",
+    # errors
+    "ArkError",
+    "ArkConfigError",
+    "ArkOAuthError",
+    "ArkTokenError",
+    "ArkCallbackError",
+    "ArkNetworkError",
+]

ark_oauth_client/access/__init__.py

@@ -0,0 +1,39 @@
+"""
+Account switching on a shared browser, and the access-denied page that makes it recoverable.
+
+Mirrors the ``Access/`` folder of the .NET client: the options, the entitlement gate, the encrypted
+denial cookie, the built-in page and the guards its two POST endpoints need. The endpoints are
+served by :mod:`ark_oauth_client.flask`.
+"""
+
+from .denied_page import ArkAccessDeniedPage
+from .endpoints import check_same_origin, local_or_default, read_field
+from .gate import ArkAccessGate
+from .options import (
+    ArkAccessDeniedContext,
+    ArkAccessDeniedReasons,
+    ArkAccessEvaluationContext,
+    ArkAccountSwitchOptions,
+    ArkChallengeProperties,
+    ArkClientEvents,
+    ArkClientOptions,
+    ArkDeniedAccount,
+)
+from .state import ArkAccessDeniedState
+
+__all__ = [
+    "ArkAccessDeniedContext",
+    "ArkAccessDeniedPage",
+    "ArkAccessDeniedReasons",
+    "ArkAccessDeniedState",
+    "ArkAccessEvaluationContext",
+    "ArkAccessGate",
+    "ArkAccountSwitchOptions",
+    "ArkChallengeProperties",
+    "ArkClientEvents",
+    "ArkClientOptions",
+    "ArkDeniedAccount",
+    "check_same_origin",
+    "local_or_default",
+    "read_field",
+]

ark_oauth_client/access/denied_page.py

@@ -0,0 +1,102 @@
+"""
+The built-in dead end.
+
+Self-contained HTML with inlined styles and no script: it has to render in an application that has
+no template directory, no static files and a strict Content-Security-Policy, and it is the one page
+a stuck user sees, so it cannot itself depend on anything.
+
+Replace it by pointing ``access_denied_path`` at your own route and setting ``serve_default_page``
+to false; ``ark_denied_account()`` gives your page the same information, and the two POST endpoints
+keep working.
+"""
+
+from __future__ import annotations
+
+from html import escape
+from typing import Optional
+
+from .endpoints import local_or_default
+from .options import ArkAccountSwitchOptions
+
+__all__ = ["ArkAccessDeniedPage"]
+
+_STYLE = (
+    ":root{--bg:#f7f7f8;--surface:#fff;--border:#e2e2e6;--fg:#17171a;--muted:#6a6a73;"
+    "--accent:#4f46e5;--accent-fg:#fff}"
+    "@media(prefers-color-scheme:dark){:root{--bg:#111114;--surface:#1a1a1f;--border:#313139;"
+    "--fg:#ececf1;--muted:#9a9aa5;--accent:#8b85ff;--accent-fg:#16161c}}"
+    "*{box-sizing:border-box}body{margin:0;min-height:100vh;display:flex;align-items:center;"
+    "justify-content:center;padding:24px;background:var(--bg);color:var(--fg);"
+    'font:15px/1.55 ui-sans-serif,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif}'
+    ".card{width:100%;max-width:480px;background:var(--surface);border:1px solid var(--border);"
+    "border-radius:12px;padding:28px}"
+    "h1{margin:0 0 10px;font-size:19px;font-weight:640}p{margin:0 0 14px;color:var(--muted)}"
+    "p.lede{color:var(--fg)}"
+    "form{margin:0}.actions{display:flex;flex-direction:column;gap:10px;margin-top:20px}"
+    "button{width:100%;padding:11px 14px;border-radius:8px;border:1px solid var(--accent);"
+    "background:var(--accent);color:var(--accent-fg);font:inherit;font-weight:560;cursor:pointer}"
+    "button.secondary{background:transparent;color:var(--fg);border-color:var(--border)}"
+    ".foot{margin-top:18px;padding-top:14px;border-top:1px solid var(--border);font-size:13px;"
+    "color:var(--muted)}.foot a{color:var(--accent)}"
+)
+
+
+class ArkAccessDeniedPage:
+    """Renders the page. Returns HTML; the caller decides the status and the headers."""
+
+    @staticmethod
+    def build(
+        options: ArkAccountSwitchOptions,
+        app: Optional[str],
+        account: Optional[str],
+        return_url: str,
+    ) -> str:
+        app_name = escape(app.strip() if app and app.strip() else "this application")
+        target = escape(return_url)
+        home = escape(local_or_default(options.home_path, "/"))
+
+        lede = (
+            f"The account you are signed in with does not have access to {app_name}."
+            if account is None
+            else (
+                f"You are signed in as <strong>{escape(account)}</strong>, and that account does "
+                f"not have access to {app_name}."
+            )
+        )
+
+        parts = [
+            '<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">',
+            '<meta name="viewport" content="width=device-width, initial-scale=1">',
+            f"<title>No access — {app_name}</title><style>{_STYLE}</style></head>",
+            '<body><main class="card">',
+            f"<h1>You do not have access to {app_name}</h1>",
+            f'<p class="lede">{lede}</p>',
+            "<p>If somebody else was using this browser, their sign-in is still active and it is "
+            f"the one being offered to {app_name}. Choose “Sign in as a different user” "
+            "to enter your own credentials.</p>",
+            '<div class="actions">',
+            f'<form method="post" action="{escape(options.switch_user_path)}">',
+            f'<input type="hidden" name="returnUrl" value="{target}">',
+            '<button type="submit">Sign in as a different user</button></form>',
+        ]
+
+        if options.allow_full_sign_out:
+            parts += [
+                f'<form method="post" action="{escape(options.sign_out_path)}">',
+                f'<input type="hidden" name="returnUrl" value="{home}">',
+                '<button class="secondary" type="submit">Sign out completely</button></form>',
+            ]
+
+        parts.append("</div>")
+
+        if options.support_url or options.support_email:
+            parts.append(f'<p class="foot">Need access to {app_name}? ')
+            if options.support_url:
+                parts.append(f'<a href="{escape(options.support_url)}">Request it here</a>')
+            else:
+                address = escape(options.support_email or "")
+                parts.append(f'<a href="mailto:{address}">{address}</a>')
+            parts.append("</p>")
+
+        parts.append("</main></body></html>")
+        return "".join(parts)

ark_oauth_client/access/endpoints.py

@@ -0,0 +1,82 @@
+"""
+The guards the three account endpoints need, kept away from any one web framework.
+
+The endpoints themselves are registered by :mod:`ark_oauth_client.flask`; what lives here is the
+part that has to be right no matter who serves them — the open-redirect guard on a return URL, and
+the same-origin check on the two POSTs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Tuple
+
+__all__ = ["local_or_default", "check_same_origin", "read_field"]
+
+
+def local_or_default(url: Optional[str], fallback: Optional[str]) -> str:
+    """
+    Keeps a return URL inside this application. Echoing an arbitrary one would turn the
+    access-denied page into an open redirect, which is a phishing primitive.
+    """
+    home = fallback if fallback and fallback.strip() else "/"
+    if not url or not url.strip():
+        return home
+    candidate = url.strip()
+    if not candidate.startswith("/"):
+        return home
+    if candidate.startswith("//"):  # protocol-relative
+        return home
+    if candidate.startswith("/\\"):  # backslash variant
+        return home
+    if any(ord(c) < 32 or ord(c) == 127 for c in candidate):
+        return home
+    return candidate
+
+
+def check_same_origin(
+    method: str,
+    headers: Mapping[str, str],
+    origin_of_this_request: str,
+) -> Tuple[bool, int, str]:
+    """
+    POST, from this origin.
+
+    Neither endpoint is a security boundary — the worst a forged request achieves is an unwanted
+    sign-out — but a cross-site page should not be able to end a user's session, and requiring a
+    POST from the same origin costs nothing. Returns ``(ok, status, message)``.
+    """
+    if method.upper() != "POST":
+        return False, 405, "POST required."
+
+    def header(name: str) -> str:
+        for key, value in headers.items():
+            if key.lower() == name:
+                return value or ""
+        return ""
+
+    fetch_site = header("sec-fetch-site")
+    if fetch_site:
+        if fetch_site not in ("same-origin", "none"):
+            return False, 400, "cross-site request rejected."
+        return True, 200, ""
+
+    origin = header("origin")
+    if not origin:
+        return True, 200, ""  # not a browser form post
+    if origin.rstrip("/").lower() == origin_of_this_request.rstrip("/").lower():
+        return True, 200, ""
+    return False, 400, "cross-site request rejected."
+
+
+def read_field(form: Optional[Mapping[str, Any]], query: Optional[Mapping[str, Any]], name: str):
+    """
+    Form first, then the query string.
+
+    A null-coalescing chain would stop at an empty form value and never look at the query, which is
+    how the return URL goes missing on the one request that needs it.
+    """
+    value = (form or {}).get(name)
+    if value:
+        return str(value)
+    value = (query or {}).get(name)
+    return str(value) if value else None

ark_oauth_client/access/gate.py

@@ -0,0 +1,111 @@
+"""
+Decides, once per sign-in, whether the account the provider authenticated is entitled to this
+application.
+
+The check belongs at the callback rather than at each protected view. An entitlement failure is not
+"this user may not open that page", it is "this user may not use this application at all", and the
+difference is visible in what happens next: refuse at the callback and no session cookie is ever
+written, so the person at the keyboard is not left holding somebody else's session while every page
+they open answers 403.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Mapping, Optional, Sequence
+
+from ..diagnostics import ArkClaimReader
+from .options import (
+    ArkAccessDeniedContext,
+    ArkAccessEvaluationContext,
+    ArkAccountSwitchOptions,
+    ArkClientEvents,
+    ArkDeniedAccount,
+)
+
+__all__ = ["ArkAccessGate"]
+
+
+class ArkAccessGate:
+    """The entitlement decision and the shape of the denial that follows it."""
+
+    @staticmethod
+    def allowed(
+        options: ArkAccountSwitchOptions,
+        events: Optional[ArkClientEvents],
+        claims: Optional[Mapping[str, Any]],
+        ark_claims: Sequence[str],
+        *,
+        tokens: Any = None,
+    ) -> bool:
+        required = options.required_claims or []
+        allowed = (not options.require_ark_claims) or (
+            any(c.lower() in {r.lower() for r in required} for c in ark_claims)
+            if required
+            else len(ark_claims) > 0
+        )
+
+        if events is None or events.on_evaluate_access is None:
+            return allowed
+
+        # The host's rule replaces the configured one outright rather than being ANDed with it — a
+        # handler that wants both can read allowed_by_configuration and say so.
+        return bool(
+            events.on_evaluate_access(
+                ArkAccessEvaluationContext(
+                    claims=dict(claims or {}),
+                    ark_claims=list(ark_claims),
+                    allowed_by_configuration=allowed,
+                    tokens=tokens,
+                )
+            )
+        )
+
+    @staticmethod
+    def describe(
+        reason: str,
+        claims: Optional[Mapping[str, Any]],
+        ark_claims: Sequence[str],
+        return_url: Optional[str],
+    ) -> ArkAccessDeniedContext:
+        """Builds the denial context, reading the account off whatever identity we do have."""
+
+        def first(*names: str) -> Optional[str]:
+            for name in names:
+                value = (claims or {}).get(name)
+                if value:
+                    return str(value)
+            return None
+
+        return ArkAccessDeniedContext(
+            reason=reason,
+            subject=first("sub"),
+            email=first("email", "preferred_username"),
+            name=first("name"),
+            ark_claims=list(ark_claims),
+            return_url=return_url,
+        )
+
+    @staticmethod
+    def to_account(denied: ArkAccessDeniedContext) -> ArkDeniedAccount:
+        return ArkDeniedAccount(
+            subject=denied.subject,
+            email=denied.email,
+            name=denied.name,
+            reason=denied.reason,
+            return_url=denied.return_url,
+        )
+
+    @staticmethod
+    def read_claims(access_token: Optional[str]) -> List[str]:
+        """The authorization claims Ark issued for this client, read off the access token."""
+        return ArkClaimReader.read_ark_claims(access_token)
+
+    @staticmethod
+    def denied_url(options: ArkAccountSwitchOptions, return_url: Optional[str]) -> str:
+        from urllib.parse import quote
+
+        path = options.access_denied_path or "/ark/no-access"
+        if not return_url:
+            return path
+        separator = "&" if "?" in path else "?"
+        return f"{path}{separator}returnUrl={quote(return_url, safe='')}"