trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/sso/models.py

@@ -0,0 +1,148 @@
+"""SSO policy side-model (ADR-0517 §3.1).
+
+ADR-0517 adopts ``allauth.socialaccount`` as the provider registry: each
+configured IdP is an allauth :class:`~allauth.socialaccount.models.SocialApp`
+(``provider``, ``provider_id``, ``client_id``, ``settings.server_url``) and each
+per-user binding is a :class:`~allauth.socialaccount.models.SocialAccount`
+(``provider``, ``uid=subject``, ``extra_data={"iss": issuer}``). The two models
+this app owned under ADR-0187 (``OIDCProvider`` / ``OIDCIdentity``) are dropped by
+the migration and replaced by those allauth models plus :class:`SsoProviderPolicy`
+— a 1:1 *side row* that carries the TruePPM policy fields ``SocialApp`` has no
+home for, and, critically, the **Fernet-encrypted client secret**.
+
+Why a side row rather than allauth's own columns:
+
+- ``SocialApp.secret`` is stored **plaintext** — below our secret-at-rest bar
+  (ADR-0049 §3). We hold the bar by leaving ``SocialApp.secret`` **empty** and
+  storing the real secret Fernet-encrypted in
+  :attr:`SsoProviderPolicy.secret_ciphertext`, decrypted only at token-exchange
+  time by our own egress-backed service (never handed to an allauth network path).
+- ``enabled`` / ``allowed_email_domains`` / ``auto_create_members`` /
+  ``default_role`` / ``allow_password_signin`` are TruePPM policy with no
+  ``SocialApp`` field.
+
+Like ``OIDCProvider`` before it, this is admin, secret-bearing configuration read
+only over the ``IsWorkspaceAdminStrict`` API — it is *not* a ``VersionedModel``,
+carries no ``server_version``, and never enters the WatermelonDB sync delta.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from allauth.socialaccount.models import SocialApp
+from django.contrib.postgres.fields import ArrayField
+from django.db import models
+
+from trueppm_api.apps.integrations.encryption import decrypt_secret, encrypt_secret
+from trueppm_api.apps.workspace.models import Workspace, WorkspaceRole
+
+
+class SsoProviderPolicy(models.Model):
+    """TruePPM policy + encrypted client secret for one allauth ``SocialApp`` (ADR-0517 §3.1).
+
+    One row per configured provider (1:1 to ``SocialApp``). The community edition
+    is single-workspace, so the ``workspace`` FK is effectively installation-wide;
+    it is retained to keep enterprise multi-tenancy open without an OSS schema
+    change. Multiple policies (Google **and** GitHub **and** a Keycloak realm) can
+    be enabled simultaneously — the capability the ADR-0187 singleton lacked.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    # CASCADE: the policy belongs to its SocialApp and has no meaning without it —
+    # deleting the provider config removes both rows together.
+    social_app = models.OneToOneField(
+        SocialApp,
+        on_delete=models.CASCADE,
+        related_name="trueppm_policy",
+    )
+    # CASCADE (not the PROTECT default): SSO config belongs to its workspace and
+    # has no meaning without it — mirrors the retired OIDCProvider FK.
+    workspace = models.ForeignKey(
+        Workspace,
+        on_delete=models.CASCADE,
+        related_name="sso_provider_policies",
+    )
+    # Fail-closed default: a freshly created provider is disabled until an admin
+    # supplies credentials and explicitly enables it. Every flow endpoint re-checks
+    # ``enabled`` so a disabled provider fails closed.
+    enabled = models.BooleanField(default=False)
+    # The registry id (ADR-0517 §2). For OIDC IdPs this equals the openid_connect
+    # ``provider_id`` on the linked SocialApp (``generic``/``keycloak``/…); for
+    # GitHub it is ``github``. It is also the SocialAccount ``provider`` value used
+    # for durable identity resolution, so distinct OIDC IdPs never collide on
+    # allauth's ``(provider, uid)`` key.
+    slug = models.CharField(max_length=64)
+    # Gates both account-linking and auto-create. Empty list = no domain permitted
+    # → fail closed. Stored lower-cased by the serializer.
+    allowed_email_domains = ArrayField(models.CharField(max_length=255), default=list, blank=True)
+    auto_create_members = models.BooleanField(default=False)
+    # Single role granted to auto-created members. Restricted to MEMBER/ADMIN by
+    # the serializer — SSO must never auto-grant OWNER. Claim→role mapping is an
+    # enterprise extension (``oidc_role_for``); OSS always assigns this role.
+    default_role = models.PositiveSmallIntegerField(
+        choices=WorkspaceRole.choices,
+        default=WorkspaceRole.MEMBER,
+    )
+    # An ENFORCEMENT setting Enterprise owns (ADR-0517 §4 / ADR-0187 §4). Enterprise
+    # registers a ``local_login_allowed`` provider that enforces the OFF state; OSS
+    # ships the column, never the lock. The column exists so an enterprise install
+    # needs no OSS schema change — but in OSS it is never *written* either: the write
+    # serializer **rejects** the field outright rather than persisting a value nothing
+    # reads (#2025), so it stays at its ``True`` default. (An earlier version of this
+    # comment said "stored but never enforced", which described the pre-#2025 shape
+    # and contradicted the serializer.)
+    allow_password_signin = models.BooleanField(default=True)
+    # GitHub only: optional org-membership restriction. Empty = any GitHub user
+    # whose verified primary email clears the domain gate may sign in. When set,
+    # the service fails closed unless the user is a member of this org (ADR-0517
+    # §3.2). Ignored for OIDC providers.
+    github_org = models.CharField(max_length=255, blank=True, default="")
+    # Fernet ciphertext (ADR-0049 §3). Write-only: never serialized back to any
+    # client. ``default=b""`` keeps the AddField migration non-interactive and
+    # models "no secret set yet". ``editable=False`` keeps it out of ModelForms /
+    # the Django admin; the API write path goes through ``set_client_secret``.
+    secret_ciphertext = models.BinaryField(default=b"", blank=True, editable=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    # Declared explicitly (codebase convention) so the default manager is typed
+    # under django-stubs strict mode.
+    objects: models.Manager[SsoProviderPolicy] = models.Manager()
+
+    class Meta:
+        db_table = "sso_provider_policy"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["workspace", "slug"], name="uniq_sso_policy_workspace_slug"
+            ),
+        ]
+
+    def __str__(self) -> str:
+        state = "enabled" if self.enabled else "disabled"
+        return f"SsoProviderPolicy({self.slug}, {state})"
+
+    @property
+    def secret_set(self) -> bool:
+        """Whether a client secret is stored (the only thing exposed about it)."""
+        return bool(self.secret_ciphertext)
+
+    def set_client_secret(self, plaintext: str) -> None:
+        """Fernet-encrypt and store the client secret (write path only).
+
+        Storing a new value is the rotation path: the previous ciphertext is
+        overwritten. The plaintext is never persisted or logged, and — because our
+        own token-exchange code makes the outbound call — is never injected into an
+        allauth-owned network path (ADR-0517 §3.1).
+        """
+        self.secret_ciphertext = encrypt_secret(plaintext)
+
+    def get_client_secret(self) -> str:
+        """Decrypt the stored client secret for use in the token-exchange request.
+
+        Server-side only — the result is sent to the IdP token endpoint and never
+        returned to a client.
+        """
+        if not self.secret_ciphertext:
+            return ""
+        return decrypt_secret(self.secret_ciphertext)

trueppm_api/apps/sso/serializers.py

@@ -0,0 +1,446 @@
+"""Serializers for the multi-provider SSO config + flow responses (ADR-0517 §3.4).
+
+Each provider is an allauth ``SocialApp`` (``provider``, ``provider_id``,
+``client_id``, ``settings.server_url``) + a :class:`SsoProviderPolicy` side row.
+The serializers span both models by hand (a plain ``Serializer``, not a
+``ModelSerializer``) so the two rows are written atomically and the client sees a
+single flat provider object.
+
+Security-relevant shapes preserved from ADR-0187:
+
+- the client secret is **never** exposed: the read serializer reports only
+  ``secret_set: bool``; the write serializer accepts ``client_secret`` as a
+  write-only field and providing it is the rotation path;
+- ``scopes`` is server-fixed (``openid email profile`` / GitHub
+  ``read:user user:email``) and read-only — the admin cannot widen it;
+- ``default_role`` is restricted to MEMBER/ADMIN here so SSO never auto-grants OWNER,
+  and is further capped by an actor ceiling in the view (#3626,
+  ``sso.views._refuse_default_role_at_or_above_actor``) so a workspace ADMIN cannot
+  use it to self-service-provision a peer ADMIN;
+- ``allow_password_signin`` is rejected in OSS (a set-but-ignored no-op, #2025);
+- the composed ``server_url`` is re-validated as an absolute https URL, and a
+  pasted ``.well-known`` discovery URL is rejected (ADR-0187 issuer rules);
+- the ``server_url`` of a provider that already has linked ``SocialAccount`` rows
+  cannot be changed (#2874) — see
+  :meth:`SsoProviderWriteSerializer._refuse_issuer_repoint_with_linked_accounts`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlparse
+
+from allauth.socialaccount.models import SocialApp
+from django.conf import settings
+from django.db import transaction
+from rest_framework import serializers
+
+from trueppm_api.apps.sso import services
+from trueppm_api.apps.sso.models import SsoProviderPolicy
+from trueppm_api.apps.workspace.models import Workspace, WorkspaceRole
+
+# SSO auto-create must never mint an OWNER. Members and Admins only.
+_ALLOWED_DEFAULT_ROLES = (WorkspaceRole.MEMBER, WorkspaceRole.ADMIN)
+
+
+class SsoProviderReadSerializer(serializers.Serializer[SsoProviderPolicy]):
+    """Read shape for one configured provider — secret reduced to a boolean.
+
+    ``redirect_uri`` is the value the operator must allow-list in their IdP; it is
+    derived (never stored) and passed via serializer context by the view — the
+    callback path is **unchanged** for every provider (ADR-0517 §3.5).
+    ``allow_password_signin_enforced`` is **always False in OSS**.
+    """
+
+    slug = serializers.CharField(read_only=True)
+    provider = serializers.SerializerMethodField()
+    kind = serializers.SerializerMethodField()
+    display_name = serializers.SerializerMethodField()
+    enabled = serializers.BooleanField(read_only=True)
+    client_id = serializers.SerializerMethodField()
+    server_url = serializers.SerializerMethodField()
+    github_org = serializers.CharField(read_only=True)
+    scopes = serializers.SerializerMethodField()
+    allowed_email_domains = serializers.ListField(child=serializers.CharField(), read_only=True)
+    auto_create_members = serializers.BooleanField(read_only=True)
+    default_role = serializers.IntegerField(read_only=True)
+    allow_password_signin = serializers.BooleanField(read_only=True)
+    allow_password_signin_enforced = serializers.SerializerMethodField()
+    secret_set = serializers.BooleanField(read_only=True)
+    redirect_uri = serializers.SerializerMethodField()
+    linked_account_count = serializers.SerializerMethodField()
+    locked_out_account_count = serializers.SerializerMethodField()
+    created_at = serializers.DateTimeField(read_only=True)
+    updated_at = serializers.DateTimeField(read_only=True)
+
+    def get_provider(self, obj: SsoProviderPolicy) -> str:
+        return str(obj.social_app.provider)
+
+    def get_kind(self, obj: SsoProviderPolicy) -> str:
+        entry = services.registry_entry(obj.slug)
+        return entry.kind if entry else ""
+
+    def get_display_name(self, obj: SsoProviderPolicy) -> str:
+        return str(obj.social_app.name)
+
+    def get_client_id(self, obj: SsoProviderPolicy) -> str:
+        return str(obj.social_app.client_id)
+
+    def get_server_url(self, obj: SsoProviderPolicy) -> str:
+        return str(obj.social_app.settings.get("server_url", ""))
+
+    def get_scopes(self, obj: SsoProviderPolicy) -> list[str]:
+        entry = services.registry_entry(obj.slug)
+        if entry and entry.allauth_provider == services.ALLAUTH_GITHUB:
+            return services.GITHUB_SCOPES
+        return services.OIDC_SCOPES
+
+    def get_allow_password_signin_enforced(self, _obj: SsoProviderPolicy) -> bool:
+        # OSS never enforces the OFF state; always False. Enterprise's serializer
+        # would compute this from its registered policy provider.
+        return False
+
+    def get_redirect_uri(self, _obj: SsoProviderPolicy) -> str:
+        return str(self.context.get("redirect_uri", ""))
+
+    def _impact(self, obj: SsoProviderPolicy) -> services.RemovalImpact:
+        """Removal impact for this provider, from the view's pre-computed context map.
+
+        Read from context rather than queried per instance so listing the whole
+        collection stays at a fixed two queries (see ``services.removal_impact``).
+        Falls back to zeros when a caller renders the serializer without the map —
+        the counts are advisory UI copy, and the DELETE endpoint recomputes them
+        itself, so a missing map must not raise.
+        """
+        impacts: dict[str, services.RemovalImpact] = self.context.get("removal_impact") or {}
+        return impacts.get(obj.slug, services.RemovalImpact(0, 0))
+
+    def get_linked_account_count(self, obj: SsoProviderPolicy) -> int:
+        return self._impact(obj).linked_accounts
+
+    def get_locked_out_account_count(self, obj: SsoProviderPolicy) -> int:
+        """Members who would have no way to sign in if this provider were removed.
+
+        No local password and no binding to another configured provider. Non-zero
+        means removal is unrecoverable for those members without self-service, so
+        the delete endpoint requires an explicit acknowledgement.
+        """
+        return self._impact(obj).locked_out_accounts
+
+
+class SsoProviderWriteSerializer(serializers.Serializer[SsoProviderPolicy]):
+    """Create/update shape for one provider (POST create / PUT update).
+
+    ``slug`` selects the registry type (required + immutable on create).
+    ``client_secret`` is write-only; omitting it preserves the stored secret and
+    providing a non-empty value rotates it. ``scopes`` is not writable (server-fixed).
+    """
+
+    slug = serializers.CharField(required=False)
+    display_name = serializers.CharField(required=False, allow_blank=True)
+    client_id = serializers.CharField(required=False, allow_blank=True)
+    client_secret = serializers.CharField(write_only=True, required=False, allow_blank=False)
+    server_url = serializers.CharField(required=False, allow_blank=True)
+    github_org = serializers.CharField(required=False, allow_blank=True)
+    enabled = serializers.BooleanField(required=False)
+    allowed_email_domains = serializers.ListField(child=serializers.CharField(), required=False)
+    auto_create_members = serializers.BooleanField(required=False)
+    default_role = serializers.IntegerField(
+        required=False,
+        help_text=(
+            "Workspace role auto-created members are granted. Must be Member (100) or "
+            "Admin (300) — SSO auto-create can never mint an Owner. Also capped to a "
+            "role strictly below the acting user's own workspace role: an Admin may set "
+            "this to Member but not Admin, matching the ceiling on member-role grants "
+            "and invites. Only an Owner can set it to Admin (#3626)."
+        ),
+    )
+    allow_password_signin = serializers.BooleanField(required=False)
+
+    def validate_slug(self, value: str) -> str:
+        value = value.strip().lower()
+        if value not in services.REGISTRY:
+            raise serializers.ValidationError(f"Unknown provider type: {value!r}.")
+        return value
+
+    def validate_server_url(self, value: str) -> str:
+        value = value.strip()
+        if not value:
+            return value
+        parsed = urlparse(value)
+        if parsed.scheme not in ("http", "https") or not parsed.netloc:
+            raise serializers.ValidationError("Issuer must be an absolute http(s) URL.")
+        # Outside DEBUG, require https: an http issuer would carry the client secret
+        # (token exchange) and the ID token over cleartext. Local dev may use http.
+        if parsed.scheme == "http" and not settings.DEBUG:
+            raise serializers.ValidationError("Issuer must use https.")
+        if parsed.query or parsed.fragment:
+            raise serializers.ValidationError("Issuer URL must not contain a query or fragment.")
+        # The discovery path is appended by the server; reject a pasted well-known URL.
+        if parsed.path.rstrip("/").endswith("/.well-known/openid-configuration"):
+            raise serializers.ValidationError(
+                "Enter the issuer URL, not the .well-known discovery URL."
+            )
+        return value
+
+    def validate_default_role(self, value: int) -> int:
+        if value not in _ALLOWED_DEFAULT_ROLES:
+            raise serializers.ValidationError("default_role must be Member or Admin.")
+        return value
+
+    def validate_allow_password_signin(self, value: bool) -> bool:
+        """Reject the field in OSS instead of persisting a set-but-ignored no-op (#2025).
+
+        ``allow_password_signin`` is an *enforcement* setting: only an edition that
+        registers a local-login policy provider (Enterprise) actually blocks password
+        login when it is ``False``. In OSS nothing enforces it, so silently storing a
+        client's value would be a footgun. A field-level validator fires only when the
+        client actually sends the key, so an untouched provider save is unaffected.
+        """
+        from trueppm_api.apps.sso.extensions import local_login_policy_enforced
+
+        if not local_login_policy_enforced():
+            raise serializers.ValidationError(
+                "Enforcing password sign-in on/off is an Enterprise-governed setting "
+                "and is not honored in the community edition, so it cannot be set here."
+            )
+        return value
+
+    def validate_allowed_email_domains(self, value: list[str]) -> list[str]:
+        cleaned: list[str] = []
+        for raw in value:
+            domain = raw.strip().lower().lstrip("@")
+            if not domain or "@" in domain or "/" in domain or " " in domain:
+                raise serializers.ValidationError(f"Invalid email domain: {raw!r}")
+            if domain not in cleaned:
+                cleaned.append(domain)
+        return cleaned
+
+    def _effective_slug(self, attrs: dict[str, Any]) -> str:
+        if self.instance is not None:
+            return str(self.instance.slug)
+        return str(attrs.get("slug", ""))
+
+    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
+        instance = self.instance
+        if instance is None and not attrs.get("slug"):
+            raise serializers.ValidationError({"slug": "This field is required."})
+
+        slug = self._effective_slug(attrs)
+        entry = services.REGISTRY.get(slug)
+        is_github = bool(entry and entry.allauth_provider == services.ALLAUTH_GITHUB)
+
+        self._refuse_issuer_repoint_with_linked_accounts(attrs, slug=slug)
+
+        # Enabling SSO requires a complete configuration — refuse to enable a
+        # half-configured provider that would fail at the first login.
+        enabled = attrs.get("enabled", getattr(instance, "enabled", False))
+        if enabled:
+            missing = self._missing_enable_requirements(attrs, is_github=is_github)
+            if missing:
+                raise serializers.ValidationError(
+                    {
+                        "enabled": (
+                            f"Cannot enable SSO until configured: missing {', '.join(missing)}."
+                        )
+                    }
+                )
+        return attrs
+
+    def _refuse_issuer_repoint_with_linked_accounts(
+        self, attrs: dict[str, Any], *, slug: str
+    ) -> None:
+        """Refuse repointing a provider that already has linked accounts (#2874).
+
+        This refusal has been documented as a security property since the feature
+        landed (``administration/single-sign-on.md``, "Re-pointing a provider to a
+        new issuer") and nothing implemented it — ``update()`` wrote ``server_url``
+        unconditionally.
+
+        Rewriting the issuer under live ``SocialAccount`` rows is not a config edit,
+        it is a silent mass lockout. Those rows keep the **old**
+        ``extra_data["iss"]``, so on the next login ``resolve_user`` matches the
+        durable ``(provider, uid)`` key, sees the issuer mismatch, and fails closed
+        with ``OIDCNoMember`` — the cross-issuer ``sub``-collision defense. It
+        cannot fall through to the verified-email path either, because allauth's
+        ``(provider, uid)`` unique key forbids a second binding for the same
+        subject. Every federated user is locked out at once, and the completion page
+        tells them to ask an admin for an invite they already have.
+
+        Remove-and-re-add is the supported migration precisely because the DELETE
+        purges the stale bindings, so those users re-link by verified email against
+        the new issuer on their next sign-in.
+
+        Scoped to a genuine *change*: re-submitting the stored issuer (which the
+        admin form does on every save, since the field is populated) must stay a
+        no-op, or editing an unrelated field would be impossible once anyone had
+        signed in.
+        """
+        from allauth.socialaccount.models import SocialAccount
+
+        if self.instance is None or "server_url" not in attrs:
+            return
+        new_issuer = str(attrs.get("server_url") or "").strip()
+        if new_issuer == self._current_server_url().strip():
+            return
+        if not SocialAccount.objects.filter(provider=slug).exists():
+            return
+        raise serializers.ValidationError(
+            {
+                "server_url": (
+                    "This provider already has linked accounts, so its issuer cannot be "
+                    "changed — every existing sign-in is bound to the current issuer and "
+                    "would stop working. Remove the provider and add it again with the new "
+                    "issuer; users then re-link by their verified email on the next sign-in."
+                )
+            }
+        )
+
+    def _missing_enable_requirements(self, attrs: dict[str, Any], *, is_github: bool) -> list[str]:
+        """Names of required config still absent when the client wants SSO enabled.
+
+        Enabling refuses a half-configured provider, so this collects every
+        required field that is neither in ``attrs`` nor already stored on the
+        instance. GitHub derives its endpoints from constants and so is exempt
+        from the issuer (``server_url``) requirement.
+        """
+        instance = self.instance
+        client_id = attrs.get("client_id") or self._current_client_id()
+        has_secret = bool(attrs.get("client_secret")) or bool(
+            getattr(instance, "secret_set", False)
+        )
+        domains = attrs.get("allowed_email_domains", getattr(instance, "allowed_email_domains", []))
+        server_url = attrs.get("server_url") or self._current_server_url()
+        missing: list[str] = []
+        if not client_id:
+            missing.append("client_id")
+        if not has_secret:
+            missing.append("client_secret")
+        if not domains:
+            missing.append("allowed_email_domains")
+        # OIDC needs an issuer; GitHub derives its endpoints from constants.
+        if not is_github and not server_url:
+            missing.append("server_url")
+        return missing
+
+    def _current_client_id(self) -> str:
+        return self.instance.social_app.client_id if self.instance is not None else ""
+
+    def _current_server_url(self) -> str:
+        if self.instance is None:
+            return ""
+        return str(self.instance.social_app.settings.get("server_url", ""))
+
+    @transaction.atomic
+    def create(self, validated_data: dict[str, Any]) -> SsoProviderPolicy:
+        slug = validated_data["slug"]
+        entry = services.REGISTRY[slug]
+        secret = validated_data.pop("client_secret", None)
+
+        app = SocialApp.objects.create(
+            provider=entry.allauth_provider,
+            # provider_id is the slug for OIDC apps (so distinct IdPs coexist under
+            # the shared openid_connect type); GitHub keeps it as the slug too for a
+            # stable SocialAccount ``provider`` key. SocialApp.secret stays EMPTY —
+            # the real secret lives Fernet-encrypted on the policy (control 2).
+            provider_id=slug,
+            name=validated_data.get("display_name", "") or entry.display,
+            client_id=validated_data.get("client_id", ""),
+            secret="",
+            settings={"server_url": validated_data.get("server_url", "")},
+        )
+        app.sites.add(_current_site_id())
+
+        policy = SsoProviderPolicy(
+            social_app=app,
+            workspace=Workspace.load(),
+            slug=slug,
+            enabled=validated_data.get("enabled", False),
+            allowed_email_domains=validated_data.get("allowed_email_domains", []),
+            auto_create_members=validated_data.get("auto_create_members", False),
+            default_role=validated_data.get("default_role", WorkspaceRole.MEMBER),
+            github_org=validated_data.get("github_org", ""),
+        )
+        if secret:
+            policy.set_client_secret(secret)
+        policy.save()
+        return policy
+
+    @transaction.atomic
+    def update(
+        self, instance: SsoProviderPolicy, validated_data: dict[str, Any]
+    ) -> SsoProviderPolicy:
+        secret = validated_data.pop("client_secret", None)
+        app = instance.social_app
+
+        if "display_name" in validated_data:
+            app.name = validated_data["display_name"]
+        if "client_id" in validated_data:
+            app.client_id = validated_data["client_id"]
+        if "server_url" in validated_data:
+            app.settings = {**app.settings, "server_url": validated_data["server_url"]}
+        app.save()
+
+        for field in (
+            "enabled",
+            "allowed_email_domains",
+            "auto_create_members",
+            "default_role",
+            "github_org",
+        ):
+            if field in validated_data:
+                setattr(instance, field, validated_data[field])
+        if secret:
+            # Providing a secret rotates it; the plaintext is encrypted and never
+            # stored or returned in clear.
+            instance.set_client_secret(secret)
+        instance.save()
+        return instance
+
+
+def _current_site_id() -> int:
+    """The Site id a SocialApp is bound to (the singleton install → SITE_ID).
+
+    A SocialApp is an M2M to Site; we bind every provider to the configured
+    ``SITE_ID`` so allauth's on-site lookups resolve.
+    """
+    return int(getattr(settings, "SITE_ID", 1))
+
+
+class SsoDiscoverResponseSerializer(serializers.Serializer[Any]):
+    """Response for ``GET /auth/oidc/discover`` — domain-level only, no enumeration."""
+
+    provider_present = serializers.BooleanField()
+    providers = serializers.ListField(child=serializers.DictField(), required=False)
+
+
+class SsoTestConnectionResponseSerializer(serializers.Serializer[Any]):
+    """Structured result of the admin "Test connection" probe.
+
+    ``reason`` is a narrower, stable machine code than ``error`` (which already
+    varies per failure mode — ``jwks_unreachable``, ``github_unreachable``, an
+    :class:`~trueppm_api.apps.sso.services.OIDCError` ``code`` like
+    ``provider_unreachable``). It is present only when the underlying cause is
+    specifically the outbound SSRF/egress guard, so the SPA can offer the
+    allow-list remedy without substring-matching ``detail`` (#3947).
+    """
+
+    ok = serializers.BooleanField()
+    issuer = serializers.CharField(required=False, allow_blank=True)
+    endpoints = serializers.DictField(required=False)
+    error = serializers.CharField(required=False, allow_blank=True)
+    reason = serializers.CharField(required=False, allow_blank=True)
+    detail = serializers.CharField(required=False, allow_blank=True)
+
+
+class SsoRedirectUriResponseSerializer(serializers.Serializer[Any]):
+    """Response for ``GET /workspace/sso/redirect-uri/``.
+
+    The redirect URI is derived from server config, not from any saved provider
+    row (ADR-0517 §3.5) — this lets the Add-provider panel show it *before* the
+    first provider is saved, which is required to break the setup order (#3690):
+    the operator needs this value to register the OAuth application with their
+    IdP, and the IdP only issues a client id/secret once that app exists.
+    """
+
+    redirect_uri = serializers.CharField()