Rename OIDC auth to workload identity, add docs and fixes

Author: BaptisteCentreon

docs/admin/guides/_SUMMARY.md

@@ -3,6 +3,7 @@
     * [Using external service](auth/external.md)
     * [Using Keycloak](auth/keycloak.md)
     * [Using JSON Header](auth/json_header.md)
+    * [Using Workload Identity](auth/workload_identity.md)
     * auth/*.md
 * Configuration
     * [Introduction](configure-pulp/index.md)

docs/admin/guides/auth/workload_identity.md

@@ -0,0 +1,102 @@
+# Workload Identity Authentication
+
+A CI job can authenticate to Pulp with a short-lived OIDC token from a third-party provider (for
+example GitHub Actions) instead of a stored username and password. The token is verified against the
+provider's public keys, its claims are matched against a set of rules, and the request is granted
+roles for that request only. No user is created and nothing is written to the role tables.
+
+This suits supply-chain workflows where a pipeline pushes content and you want its permissions scoped
+to specific repositories without long-lived secrets.
+
+!!! note
+    The token is an OIDC token, but this is unrelated to the user-facing SSO login covered in
+    [Using external service](external.md). It identifies a workload, not a person.
+
+## How it works
+
+On each request the token is read from the `Authorization` header, either as a `Bearer` token or as
+the password of a `Basic` header (the way `docker login` sends a token). The `iss` claim selects a
+configured provider, the signature is verified against the provider's JWKS, and `iss`, `aud` and
+`exp` are checked. The remaining claims are matched against the provider's rules to compute the roles
+and scopes for the request. A token that matches no rule is rejected with a 401.
+
+## Enabling
+
+Add the authentication class to `DEFAULT_AUTHENTICATION_CLASSES`, before `BasicAuthentication` so the
+`docker login` path reaches it, then populate `WORKLOAD_IDENTITY`:
+
+```python title="settings.py"
+REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"] = [
+    "pulpcore.app.workload_identity.authentication.WorkloadIdentityAuthentication",
+    "pulpcore.app.authentication.BasicAuthentication",
+    "rest_framework.authentication.SessionAuthentication",
+]
+```
+
+No change to `AUTHENTICATION_BACKENDS` is needed. The feature stays off while `WORKLOAD_IDENTITY` is
+empty, so adding the class alone changes nothing.
+
+With the example below, a push from the `main` branch of `my-org/app` is granted the
+`file.filerepository_owner` role on the repository named `prod`, and nothing else. See the
+configuration reference at the end for every option.
+
+## Roles for asynchronous tasks
+
+Operations that dispatch a task, such as a sync, return a task the client polls. A workload identity
+request is not a database user, so it is not automatically granted a role on the tasks it creates.
+Grant a role carrying `core.view_task` when the CI needs to read its own tasks.
+
+## Configuration reference
+
+Every option of the `WORKLOAD_IDENTITY` setting, annotated:
+
+```python title="settings.py"
+WORKLOAD_IDENTITY = {
+    # How matching rules combine.
+    # "union" (default) collects the grants of every matching rule.
+    # "first-match" stops at the first matching rule.
+    "strategy": "union",
+
+    # One entry per trusted provider. The key is a name for your own reference.
+    "providers": {
+        "github": {
+            # Required. Expected "iss" claim. Selects the provider and is verified while decoding.
+            "issuer": "https://token.actions.githubusercontent.com",
+
+            # Required. URL of the provider's JWKS. Keys are fetched and cached.
+            "jwks_url": "https://token.actions.githubusercontent.com/.well-known/jwks",
+
+            # Required. Expected "aud" claim.
+            "audience": "https://pulp.example.com",
+
+            # Optional. Allowed signing algorithms. Default: ["RS256"].
+            "algorithms": ["RS256"],
+
+            # Rules are evaluated in order. Each maps claims to grants.
+            "rules": [
+                {
+                    # Claim name to expected value. Values support "*" globbing.
+                    # Every entry must match (AND). A missing claim never matches.
+                    "match": {"repository": "my-org/app", "ref": "refs/heads/main"},
+
+                    # Grants awarded when the rule matches.
+                    "grants": [
+                        {
+                            # Required. Name of a role that already exists in Pulp.
+                            # A role that does not exist confers no permission.
+                            "role": "file.filerepository_owner",
+
+                            # Required. Where the role applies. One of:
+                            #   {"type": "global"}                       everywhere
+                            #   {"type": "domain", "domain": "<name>"}   objects in a domain
+                            #   {"type": "object", "name": "<name>"}     one object by name
+                            #   {"type": "object", "prn": "<prn>"}       one object by PRN
+                            "scope": {"type": "object", "name": "prod"},
+                        },
+                    ],
+                },
+            ],
+        },
+    },
+}
+```

pulpcore/app/access_policy.py

@@ -15,6 +15,13 @@ class DefaultAccessPolicy(AccessPolicy):
     An AccessPolicy that takes default statements from the view(set).
     """
 
+    def get_user_group_values(self, user):
+        """Let a stateless principal supply its groups via ``group_names`` instead of the ORM."""
+        group_names = getattr(user, "group_names", None)
+        if group_names is not None:
+            return list(group_names)
+        return super().get_user_group_values(user)
+
     @classmethod
     def get_access_policy(cls, view):
         """

pulpcore/app/oidc/__init__.py

@@ -173,11 +173,10 @@ def get_objects_for_user(
     accept_domain_perms=True,
     accept_global_perms=True,
 ):
-    from pulpcore.app.oidc.principal import OIDCPrincipal
+    from pulpcore.app.workload_identity.principal import WorkloadIdentityPrincipal
 
-    if isinstance(user, OIDCPrincipal):
-        # Stateless OIDC principal: scope from its per-request grants, not the role tables.
-        from pulpcore.app.oidc.authz import grants_queryset
+    if isinstance(user, WorkloadIdentityPrincipal):
+        from pulpcore.app.workload_identity.authz import grants_queryset
 
         grants = user.grants
         if isinstance(perms, str):

pulpcore/app/role_util.py

@@ -316,11 +316,8 @@
 AUTHENTICATION_JSON_HEADER_JQ_FILTER = ""
 AUTHENTICATION_JSON_HEADER_OPENAPI_SECURITY_SCHEME = {}
 
-# OIDC authentication for CI clients. Empty by default (feature off). See
-# pulpcore.app.oidc.config for the schema. Enable by adding
-# "pulpcore.app.oidc.authentication.OIDCAuthentication" to
-# REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"] and populating this setting.
-OIDC_AUTH = {}
+# Workload identity authentication for CI clients. Off while empty.
+WORKLOAD_IDENTITY = {}
 
 ALLOWED_IMPORT_PATHS = []
 

pulpcore/app/settings.py

@@ -0,0 +1,5 @@
+"""Workload identity authentication for CI clients.
+
+A short-lived OIDC token from a third-party provider (for example GitHub Actions) becomes a
+stateless principal whose grants are computed per request from the ``WORKLOAD_IDENTITY`` setting.
+"""

pulpcore/app/workload_identity/__init__.py

@@ -1,12 +1,7 @@
-"""DRF authentication that validates third-party OIDC tokens.
+"""DRF authentication that validates a third-party OIDC token against its provider's JWKS.
 
-This authenticator accepts an OIDC token issued by a configured third-party
-provider (for example a GitHub Actions workflow token), verifies it against the
-provider's JWKS, maps its claims to grants and returns a stateless
-``OIDCPrincipal``. No database user is involved.
-
-The token may arrive either as a ``Bearer`` token or inside a ``Basic`` header
-(the way ``docker login`` passes a token, where the password field carries it).
+The token arrives as a ``Bearer`` token or as the password in a ``Basic`` header (``docker login``).
+On success its claims map to grants and a stateless ``WorkloadIdentityPrincipal`` is returned.
 """
 
 import base64
@@ -17,16 +12,16 @@
 from rest_framework.authentication import BaseAuthentication
 from rest_framework.exceptions import AuthenticationFailed
 
-from pulpcore.app.oidc import config, rules
-from pulpcore.app.oidc.principal import OIDCPrincipal
+from pulpcore.app.workload_identity import config, rules
+from pulpcore.app.workload_identity.principal import WorkloadIdentityPrincipal
 
-_logger = logging.getLogger("pulpcore.oidc")
+_logger = logging.getLogger("pulpcore.workload_identity")
 
 
-class OIDCAuthentication(BaseAuthentication):
+class WorkloadIdentityAuthentication(BaseAuthentication):
     """Authenticate requests bearing a third-party OIDC token.
 
-    On success this returns a stateless ``OIDCPrincipal`` whose permissions are
+    On success this returns a stateless ``WorkloadIdentityPrincipal`` whose permissions are
     derived entirely from the grants earned by the token's claims. When the
     request carries no token, or a token that is not meant for us, the
     authenticator returns ``None`` so that other authenticators may run.
@@ -49,19 +44,16 @@ def _get_token(self, request):
                 return None
             if ":" not in decoded:
                 return None
-            # docker login passes the token as the password; the username is ignored.
             _, _, password = decoded.partition(":")
             return password
         return None
 
     def authenticate(self, request):
-        """Validate an OIDC token and return ``(OIDCPrincipal, claims)``, or ``None`` if not ours."""
+        """Validate an OIDC token and return ``(WorkloadIdentityPrincipal, claims)``, or ``None`` if not ours."""
         token = self._get_token(request)
         if not token:
             return None
 
-        # Peek at the issuer without verifying the signature. If this is not a
-        # JWT at all, it is not meant for us.
         try:
             unverified = jwt.decode(token, options={"verify_signature": False})
         except jwt.PyJWTError:
@@ -72,7 +64,6 @@ def authenticate(self, request):
         if provider is None:
             return None
 
-        # Verify the token for real against the provider's JWKS.
         try:
             signing_key = config.jwks_client(provider).get_signing_key_from_jwt(token)
             claims = jwt.decode(
@@ -96,9 +87,7 @@ def authenticate(self, request):
             )
             raise AuthenticationFailed("No matching OIDC rule.")
 
-        # The username is intentionally empty: the container registry token
-        # subject must be empty for a principal with no database user.
-        return (OIDCPrincipal(grants, username=""), claims)
+        return (WorkloadIdentityPrincipal(grants, username=""), claims)
 
     def authenticate_header(self, request):
         """Return the ``WWW-Authenticate`` value so failures are 401, not 403."""

pulpcore/app/oidc/authentication.py …/app/workload_identity/authentication.pypulpcore/app/oidc/authentication.py renamed to pulpcore/app/workload_identity/authentication.py pulpcore/app/oidc/authentication.py renamed to pulpcore/app/workload_identity/authentication.py

@@ -6,9 +6,7 @@
 * ``{"type": "domain", "domain": "<name>"}``
 * ``{"type": "object", "name": "<name>"}`` (or ``"prn"``)
 
-This module is used both by the principal (single-object ``has_perm`` and the model-level
-permission set) and by ``get_objects_for_user`` (list filtering). Roles are read from the
-database to resolve their permissions; the grant assignment itself is never stored.
+Roles are read from the database to resolve their permissions; the grant assignment is never stored.
 """
 
 from django.db.models import Q
@@ -48,11 +46,19 @@ def _scope_matches(scope, obj):
         domain = getattr(obj, "pulp_domain", None)
         return domain is not None and domain.name == scope.get("domain")
     if stype == "object":
-        checks = (("prn", "prn"), ("name", "name"))
-        provided = [key for key, _ in checks if key in scope]
-        if not provided:
+        if "prn" not in scope and "name" not in scope:
             return False
-        return all(str(getattr(obj, attr, None)) == str(scope[key]) for key, attr in checks if key in scope)
+        if "prn" in scope:
+            from pulpcore.app.util import get_prn
+
+            try:
+                if get_prn(obj) != scope["prn"]:
+                    return False
+            except Exception:
+                return False
+        if "name" in scope and str(getattr(obj, "name", None)) != str(scope["name"]):
+            return False
+        return True
     return False
 
 
@@ -67,15 +73,26 @@ def has_grant_perm(grants, permission, obj=None):
     return False
 
 
-def permissions_for(grants):
-    """The set of ``app_label.codename`` the grants confer, for model-level ``get_all_permissions``."""
+def permissions_for(grants, obj=None):
+    """The set of ``app_label.codename`` the grants confer, scoped to ``obj`` when given."""
     from pulpcore.app.models.role import Role
 
     names = {g.get("role") for g in grants if g.get("role")}
-    perms = set()
+    if not names:
+        return set()
+    role_perms = {}
     for role in Role.objects.filter(name__in=names).prefetch_related("permissions__content_type"):
-        for perm in role.permissions.all():
-            perms.add(f"{perm.content_type.app_label}.{perm.codename}")
+        role_perms[role.name] = {
+            f"{perm.content_type.app_label}.{perm.codename}" for perm in role.permissions.all()
+        }
+    perms = set()
+    for grant in grants:
+        conferred = role_perms.get(grant.get("role"))
+        if not conferred:
+            continue
+        if obj is not None and not _scope_matches(grant.get("scope", {}), obj):
+            continue
+        perms |= conferred
     return perms
 
 
@@ -98,7 +115,12 @@ def grants_queryset(grants, permission, queryset):
             clause = Q(pulp_domain__name=scope.get("domain"))
         elif stype == "object":
             if "prn" in scope:
-                clause = Q(prn=scope["prn"])
+                from pulpcore.app.util import extract_pk
+
+                try:
+                    clause = Q(pk=extract_pk(scope["prn"], only_prn=True))
+                except Exception:
+                    clause = None
             elif "name" in scope:
                 clause = Q(name=scope["name"])
         if clause is not None:

pulpcore/app/oidc/authz.py pulpcore/app/workload_identity/authz.pypulpcore/app/oidc/authz.py renamed to pulpcore/app/workload_identity/authz.py

@@ -1,4 +1,4 @@
-"""Access to the ``OIDC_AUTH`` setting and per-provider JWKS clients."""
+"""Access to the ``WORKLOAD_IDENTITY`` setting and per-provider JWKS clients."""
 
 import functools
 
@@ -7,7 +7,7 @@
 
 
 def config():
-    return getattr(settings, "OIDC_AUTH", {}) or {}
+    return getattr(settings, "WORKLOAD_IDENTITY", {}) or {}
 
 
 def strategy():