feat: add generic OIDC integration type (#1007)

Add a new possible value for the field `kind` on the `OAuth2Client` class in `connected_services`.

This allows Renku to connect to third-party platforms which implement OAuth 2.0 via OpenID Connect, e.g. with Keycloak.

Other changes:
* Update `models.py` so that we do not import from `apispec.py` into `db.py` or `orm.py`.

Author: leafty

components/renku_data_services/connected_services/api.spec.yaml

@@ -274,6 +274,8 @@ components:
           $ref: "#/components/schemas/UsePKCE"
         image_registry_url:
           $ref: "#/components/schemas/ImageRegistryUrl"
+        oidc_issuer_url:
+          $ref: "#/components/schemas/OidcIssuerUrl"
       required:
         - id
         - kind
@@ -307,6 +309,8 @@ components:
           $ref: "#/components/schemas/UsePKCE"
         image_registry_url:
           $ref: "#/components/schemas/ImageRegistryUrl"
+        oidc_issuer_url:
+          $ref: "#/components/schemas/OidcIssuerUrl"
       required:
         - id
         - kind
@@ -336,6 +340,8 @@ components:
           $ref: "#/components/schemas/UsePKCE"
         image_registry_url:
           $ref: "#/components/schemas/ImageRegistryUrl"
+        oidc_issuer_url:
+          $ref: "#/components/schemas/OidcIssuerUrl"
     ConnectionList:
       type: array
       items:
@@ -410,6 +416,7 @@ components:
         - "drive"
         - "onedrive"
         - "dropbox"
+        - "generic_oidc"
       example: "gitlab"
     ApplicationSlug:
       description: |
@@ -480,6 +487,11 @@ components:
         This should contain no paths, just the domain for the registry and the scheme
         (http or https) to access the image registry API.
       example: https://registry.gitlab.com
+    OidcIssuerUrl:
+      type: string
+      description: |
+        The URL for OpenID Connect client discovery. Used for providers of kind 'generic_oidc'.
+      example: https://renkulab.io/auth/realms/Renku
     ErrorResponse:
       type: object
       properties:

components/renku_data_services/connected_services/apispec.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  api.spec.yaml
-#   timestamp: 2025-09-01T13:55:20+00:00
+#   timestamp: 2025-09-05T11:16:18+00:00
 
 from __future__ import annotations
 
@@ -34,6 +34,7 @@ class ProviderKind(Enum):
     drive = "drive"
     onedrive = "onedrive"
     dropbox = "dropbox"
+    generic_oidc = "generic_oidc"
 
 
 class ConnectionStatus(Enum):
@@ -125,6 +126,11 @@ class Provider(BaseAPISpec):
         description="This should contain no paths, just the domain for the registry and the scheme\n(http or https) to access the image registry API.\n",
         examples=["https://registry.gitlab.com"],
     )
+    oidc_issuer_url: Optional[str] = Field(
+        None,
+        description="The URL for OpenID Connect client discovery. Used for providers of kind 'generic_oidc'.\n",
+        examples=["https://renkulab.io/auth/realms/Renku"],
+    )
 
 
 class ProviderPost(BaseAPISpec):
@@ -169,6 +175,11 @@ class ProviderPost(BaseAPISpec):
         description="This should contain no paths, just the domain for the registry and the scheme\n(http or https) to access the image registry API.\n",
         examples=["https://registry.gitlab.com"],
     )
+    oidc_issuer_url: Optional[str] = Field(
+        None,
+        description="The URL for OpenID Connect client discovery. Used for providers of kind 'generic_oidc'.\n",
+        examples=["https://renkulab.io/auth/realms/Renku"],
+    )
 
 
 class ProviderPatch(BaseAPISpec):
@@ -208,6 +219,11 @@ class ProviderPatch(BaseAPISpec):
         description="This should contain no paths, just the domain for the registry and the scheme\n(http or https) to access the image registry API.\n",
         examples=["https://registry.gitlab.com"],
     )
+    oidc_issuer_url: Optional[str] = Field(
+        None,
+        description="The URL for OpenID Connect client discovery. Used for providers of kind 'generic_oidc'.\n",
+        examples=["https://renkulab.io/auth/realms/Renku"],
+    )
 
 
 class Connection(BaseAPISpec):

components/renku_data_services/connected_services/core.py

@@ -8,10 +8,18 @@
 
 def validate_oauth2_client_patch(patch: apispec.ProviderPatch) -> models.OAuth2ClientPatch:
     """Validate the update to a OAuth2 Client."""
-    if patch.image_registry_url is not None and len(patch.image_registry_url) > 0:
+    if patch.image_registry_url:
         validate_image_registry_url(patch.image_registry_url)
+    kind = models.ProviderKind(patch.kind.value) if patch.kind else None
+    if kind == models.ProviderKind.generic_oidc:
+        if not patch.oidc_issuer_url:
+            raise errors.ValidationError(
+                message=f"The field 'oidc_issuer_url' is required when kind is set to {models.ProviderKind.generic_oidc.value}.",  # noqa E501
+                quiet=True,
+            )
+        validate_oidc_issuer_url(patch.oidc_issuer_url)
     return models.OAuth2ClientPatch(
-        kind=patch.kind,
+        kind=kind,
         app_slug=patch.app_slug,
         client_id=patch.client_id,
         client_secret=patch.client_secret,
@@ -20,16 +28,30 @@ def validate_oauth2_client_patch(patch: apispec.ProviderPatch) -> models.OAuth2C
         url=patch.url,
         use_pkce=patch.use_pkce,
         image_registry_url=patch.image_registry_url,
+        oidc_issuer_url=patch.oidc_issuer_url,
     )
 
 
 def validate_unsaved_oauth2_client(clnt: apispec.ProviderPost) -> models.UnsavedOAuth2Client:
     """Validate the the creation of a new OAuth2 Client."""
     if clnt.image_registry_url is not None:
         validate_image_registry_url(clnt.image_registry_url)
+    kind = models.ProviderKind(clnt.kind.value)
+    if clnt.oidc_issuer_url and kind != models.ProviderKind.generic_oidc:
+        raise errors.ValidationError(
+            message=f"The field 'oidc_issuer_url' can only be set when kind is set to {models.ProviderKind.generic_oidc.value}.",  # noqa E501
+            quiet=True,
+        )
+    if kind == models.ProviderKind.generic_oidc:
+        if not clnt.oidc_issuer_url:
+            raise errors.ValidationError(
+                message=f"The field 'oidc_issuer_url' is required when kind is set to {models.ProviderKind.generic_oidc.value}.",  # noqa E501
+                quiet=True,
+            )
+        validate_oidc_issuer_url(clnt.oidc_issuer_url)
     return models.UnsavedOAuth2Client(
         id=clnt.id,
-        kind=clnt.kind,
+        kind=kind,
         app_slug=clnt.app_slug or "",
         client_id=clnt.client_id,
         client_secret=clnt.client_secret,
@@ -38,6 +60,7 @@ def validate_unsaved_oauth2_client(clnt: apispec.ProviderPost) -> models.Unsaved
         url=clnt.url,
         use_pkce=clnt.use_pkce or False,
         image_registry_url=clnt.image_registry_url,
+        oidc_issuer_url=clnt.oidc_issuer_url,
     )
 
 
@@ -55,3 +78,19 @@ def validate_image_registry_url(url: str) -> None:
             message=f"The scheme for the image registry url {url} is not valid, expected one of {accepted_schemes}",
             quiet=True,
         )
+
+
+def validate_oidc_issuer_url(url: str) -> None:
+    """Validate an OpenID Connect Issuer URL."""
+    parsed = urlparse(url)
+    if not parsed.netloc:
+        raise errors.ValidationError(
+            message=f"The host for the 'oidc_issuer_url' {url} is not valid, expected a non-empty value.",
+            quiet=True,
+        )
+    accepted_schemes = ["https"]
+    if parsed.scheme not in accepted_schemes:
+        raise errors.ValidationError(
+            message=f"The scheme for the 'oidc_issuer_url' {url} is not valid, expected one of {accepted_schemes}",
+            quiet=True,
+        )

components/renku_data_services/connected_services/db.py

@@ -19,7 +19,6 @@
 from renku_data_services.base_api.pagination import PaginationRequest
 from renku_data_services.connected_services import models
 from renku_data_services.connected_services import orm as schemas
-from renku_data_services.connected_services.apispec import ConnectionStatus, ProviderKind
 from renku_data_services.connected_services.provider_adapters import (
     GitHubAdapter,
     ProviderAdapter,
@@ -93,6 +92,7 @@ async def insert_oauth2_client(
             use_pkce=new_client.use_pkce or False,
             created_by_id=user.id,
             image_registry_url=new_client.image_registry_url,
+            oidc_issuer_url=new_client.oidc_issuer_url or None,
         )
 
         async with self.session_maker() as session, session.begin():
@@ -150,6 +150,13 @@ async def update_oauth2_client(
             elif patch.image_registry_url == "":
                 # Patching with "", removes the value
                 client.image_registry_url = None
+            if patch.oidc_issuer_url:
+                client.oidc_issuer_url = patch.oidc_issuer_url
+            elif patch.oidc_issuer_url == "":
+                client.oidc_issuer_url = None
+            # Unset oidc_issuer_url when the kind has been changed to a value other than 'generic_oidc'
+            if client.kind != models.ProviderKind.generic_oidc:
+                client.oidc_issuer_url = None
 
             await session.flush()
             await session.refresh(client)
@@ -222,14 +229,14 @@ async def authorize_client(
                         client_id=client.id,
                         token=None,
                         state=state,
-                        status=schemas.ConnectionStatus.pending,
+                        status=models.ConnectionStatus.pending,
                         code_verifier=code_verifier,
                         next_url=next_url,
                     )
                     session.add(connection)
                 else:
                     connection.state = state
-                    connection.status = schemas.ConnectionStatus.pending
+                    connection.status = models.ConnectionStatus.pending
                     connection.code_verifier = code_verifier
                     connection.next_url = next_url
 
@@ -284,7 +291,7 @@ async def authorize_callback(self, state: str, raw_url: str, callback_url: str)
 
                 connection.token = self._encrypt_token_set(token=token, user_id=connection.user_id)
                 connection.state = None
-                connection.status = schemas.ConnectionStatus.connected
+                connection.status = models.ConnectionStatus.connected
                 connection.next_url = None
 
                 return next_url
@@ -381,7 +388,7 @@ async def get_docker_client(
             conn = await session.scalar(stmt)
         if not conn:
             return None, None
-        if conn.client.kind != ProviderKind.gitlab:
+        if conn.client.kind != models.ProviderKind.gitlab:
             # NOTE: Only Gitlab is currently supported for this
             return None, None
         url = conn.client.image_registry_url
@@ -406,7 +413,7 @@ async def get_oauth2_app_installations(
             adapter,
         ):
             # NOTE: App installations are only available from GitHub
-            if connection.client.kind == ProviderKind.github and isinstance(adapter, GitHubAdapter):
+            if connection.client.kind == models.ProviderKind.github and isinstance(adapter, GitHubAdapter):
                 request_url = urljoin(adapter.api_url, "user/installations")
                 params = dict(page=pagination.page, per_page=pagination.per_page)
                 try:
@@ -450,7 +457,7 @@ async def get_async_oauth2_client(
                     message=f"OAuth2 connection with id '{connection_id}' does not exist or you do not have access to it."  # noqa: E501
                 )
 
-            if connection.status != ConnectionStatus.connected or connection.token is None:
+            if connection.status != models.ConnectionStatus.connected or connection.token is None:
                 raise errors.UnauthorizedError(message=f"OAuth2 connection with id '{connection_id}' is not valid.")
 
             client = connection.client

components/renku_data_services/connected_services/external_models.py

@@ -5,7 +5,6 @@
 from pydantic import BaseModel
 
 from renku_data_services.connected_services import models
-from renku_data_services.connected_services.apispec import RepositorySelection
 
 
 class GitLabConnectedAccount(BaseModel):
@@ -35,7 +34,7 @@ class GitHubAppInstallation(BaseModel):
 
     id: int
     account: GitHubConnectedAccount
-    repository_selection: RepositorySelection
+    repository_selection: models.RepositorySelection
     suspended_at: datetime | None = None
 
     def to_app_installation(self) -> models.AppInstallation:
@@ -101,3 +100,23 @@ def to_connected_account(self) -> models.ConnectedAccount:
         return models.ConnectedAccount(
             username=" ".join(filter(None, [self.given_name, self.family_name])), web_url=f"mailto:{self.email}"
         )
+
+
+class GenericOIDCConnectedAccount(BaseModel):
+    """OAuth2 connected account model for generic OpenID Connect."""
+
+    # Reference: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
+    sub: str
+    name: str | None
+    preferred_username: str | None
+
+    def to_connected_account(self) -> models.ConnectedAccount:
+        """Returns the corresponding ConnectedAccount object."""
+
+        return models.ConnectedAccount(
+            username=self._get_username(),
+            web_url="",
+        )
+
+    def _get_username(self) -> str:
+        return self.preferred_username or self.name or self.sub

components/renku_data_services/connected_services/models.py

@@ -2,11 +2,35 @@
 
 from dataclasses import dataclass
 from datetime import UTC, datetime
+from enum import StrEnum
 from typing import Any
 
 from ulid import ULID
 
-from renku_data_services.connected_services.apispec import ConnectionStatus, ProviderKind, RepositorySelection
+
+class ProviderKind(StrEnum):
+    """The kind of platform we connnect to."""
+
+    gitlab = "gitlab"
+    github = "github"
+    drive = "drive"
+    onedrive = "onedrive"
+    dropbox = "dropbox"
+    generic_oidc = "generic_oidc"
+
+
+class ConnectionStatus(StrEnum):
+    """The status of a connection."""
+
+    connected = "connected"
+    pending = "pending"
+
+
+class RepositorySelection(StrEnum):
+    """The repository selection for GitHub applications."""
+
+    all = "all"
+    selected = "selected"
 
 
 @dataclass(frozen=True, eq=True, kw_only=True)
@@ -23,6 +47,7 @@ class UnsavedOAuth2Client:
     url: str
     use_pkce: bool
     image_registry_url: str | None = None
+    oidc_issuer_url: str | None = None
 
 
 @dataclass(frozen=True, eq=True, kw_only=True)
@@ -47,6 +72,7 @@ class OAuth2ClientPatch:
     url: str | None
     use_pkce: bool | None
     image_registry_url: str | None
+    oidc_issuer_url: str | None
 
 
 @dataclass(frozen=True, eq=True, kw_only=True)

components/renku_data_services/connected_services/orm.py

@@ -10,7 +10,6 @@
 from ulid import ULID
 
 from renku_data_services.connected_services import models
-from renku_data_services.connected_services.apispec import ConnectionStatus, ProviderKind
 from renku_data_services.utils.sqlalchemy import ULIDType
 
 JSONVariant = JSON().with_variant(JSONB(), "postgresql")
@@ -32,7 +31,7 @@ class OAuth2ClientORM(BaseORM):
     client_id: Mapped[str] = mapped_column("client_id", String(500), repr=False)
     display_name: Mapped[str] = mapped_column("display_name", String(99))
     created_by_id: Mapped[str] = mapped_column("created_by_id", String())
-    kind: Mapped[ProviderKind]
+    kind: Mapped[models.ProviderKind]
     scope: Mapped[str] = mapped_column("scope", String())
     url: Mapped[str] = mapped_column("url", String())
     use_pkce: Mapped[bool] = mapped_column("use_pkce", Boolean(), server_default=false())
@@ -50,6 +49,7 @@ class OAuth2ClientORM(BaseORM):
         nullable=False,
     )
     image_registry_url: Mapped[str | None] = mapped_column(default=None, nullable=True, server_default=None)
+    oidc_issuer_url: Mapped[str | None] = mapped_column(default=None, nullable=True, server_default=None)
 
     def dump(self, user_is_admin: bool = False) -> models.OAuth2Client:
         """Create an OAuth2 Client model from the OAuth2ClientORM.
@@ -70,6 +70,7 @@ def dump(self, user_is_admin: bool = False) -> models.OAuth2Client:
             creation_date=self.creation_date,
             updated_at=self.updated_at,
             image_registry_url=self.image_registry_url,
+            oidc_issuer_url=self.oidc_issuer_url,
         )
 
 
@@ -83,7 +84,7 @@ class OAuth2ConnectionORM(BaseORM):
     client: Mapped[OAuth2ClientORM] = relationship(init=False, repr=False)
     token: Mapped[dict[str, Any] | None] = mapped_column("token", JSONVariant)
     state: Mapped[str | None] = mapped_column("state", String(), index=True, unique=True)
-    status: Mapped[ConnectionStatus]
+    status: Mapped[models.ConnectionStatus]
     code_verifier: Mapped[str | None] = mapped_column("code_verifier", String())
     next_url: Mapped[str | None] = mapped_column("next_url", String())
     creation_date: Mapped[datetime] = mapped_column(