Feature: Register a ControlPlane as a trusted OIDC issuer via annotation

[ValentinGerlach]

What would you like to be added?

An annotation on the ControlPlane resource that causes the system to automatically register the ControlPlane's service account issuer as a trusted OIDC issuer in the onboarding cluster. This mirrors the Gardener garden-shoot-trust feature.

Annotation

apiVersion: core.open-control-plane.io/v2alpha1
kind: ControlPlane
metadata:
  name: my-controlplane
  namespace: project-my-team--ws-dev
  annotations:
    authentication.openmcp.cloud/trusted: "true"

Adding the annotation triggers the system to:

1. Discover the ControlPlane's service account issuer URL (from the ControlPlane's kube-apiserver OIDC discovery endpoint).
2. Register that issuer as trusted in the onboarding cluster using the same underlying mechanism as OIDCIssuer (see related feature).
3. Generate and expose a prefix in the ControlPlane's status that identifies identities originating from this ControlPlane.

Status

status:
  # ...existing fields...
  oidcIssuer:
    # Prefix assigned to identities from this ControlPlane's service account issuer.
    # Derived from the ControlPlane's UID (metadata.uid). Includes the trailing colon.
    prefix: "controlplane:9df9bcaf-8694-4b5d-aedc-eeaa54efd6a8:"

The prefix is derived from the ControlPlane's Kubernetes UID (metadata.uid), which ensures that recreating a ControlPlane with the same name in the same workspace produces a different prefix and does not inherit the trust of its predecessor.

Token audience

Tokens presented to the onboarding API must include the audience "onboarding". The ControlPlane must be configured to issue tokens with this audience (e.g., via a projected ServiceAccountToken volume with audience: onboarding).

Granting access

Once the annotation is set, ServiceAccount tokens issued by the ControlPlane with audience "onboarding" can authenticate to the onboarding API. A project/workspace admin grants specific identities access by adding members using the generated prefix:

apiVersion: core.openmcp.cloud/v1alpha1
kind: Project
metadata:
  name: my-team
spec:
  members:
    - kind: User
      name: controlplane:9df9bcaf-8694-4b5d-aedc-eeaa54efd6a8:system:serviceaccount:default:my-operator
      roles: [admin]

This enables use cases such as a ControlPlane-hosted operator that orders further ControlPlanes, manages Workspaces, or reads Project state via the onboarding API.

Constraints

• The annotation can be set by workspace admins (ControlPlane resources live in workspace namespaces).
• Removing the annotation revokes the trust registration.
• The ControlPlane's service account issuer URL must be publicly reachable for OIDC discovery. Whether this is always the case depends on the cluster provider and network topology.
• The registered issuer is trusted globally by the onboarding API (same as OIDCIssuer), so the generated prefix can be used in member lists of any Project or Workspace.

Acceptance criteria

• Adding the annotation to a ControlPlane causes its service account issuer to be trusted by the onboarding API.
• status.oidcIssuer.prefix is populated with the form controlplane:<uid>:.
• A ServiceAccount token from the ControlPlane with audience "onboarding" can authenticate to the onboarding API.
• Removing the annotation revokes the trust registration.
• The feature is a no-op when the ControlPlane's issuer URL is not publicly reachable, with a clear condition on the ControlPlane status.

Open question: implementation location

This feature shares the same infrastructure dependency as the OIDCIssuer feature: the mechanism for registering a trusted issuer in the onboarding cluster depends on the cluster flavor (Gardener OpenIDConnect CRD vs. vanilla AuthenticationConfiguration). The implementation location decision for both features should be made together.

Why is this needed?

Today, ordering a ControlPlane from another ControlPlane requires a human-in-the-loop step to establish trust between the two systems. There is no automated path for a ControlPlane-hosted operator to authenticate to the onboarding API and manage Projects, Workspaces, or further ControlPlanes on its own.

This feature enables fully automated, ControlPlane-to-onboarding-API workflows without requiring platform operator involvement. A workspace admin can self-service the trust registration by adding a single annotation, then grant the ControlPlane's service accounts the specific permissions they need via the existing member list mechanism.

Related

• Establish Trust Onboarding API <-> Provider from ManagedControlPlane #68 (would be solved by this feature)
• Feature: Register custom OIDC issuers at Project level #693 (companion OIDCIssuer feature, shares implementation infrastructure)