WIP: 📝 Add SubjectMapping enhancement proposal

[zhujian7]

Summary

This enhancement proposes a SubjectMapping API that enables transparent authentication for hub subjects accessing managed clusters through cluster-proxy.

• Eliminates token storage on the hub cluster by generating tokens on-demand
• Simplifies RBAC requirements for applications accessing managed clusters
• Provides transparent authentication requiring zero code changes to existing applications
• Implements hub token validation via TokenReview API
• Supports conflict detection without validation webhooks

Implementation Phases

Alpha/Beta: ServiceAccount subject mapping (primary implementation)
Future: User subject mapping (designed but deferred)

Related Issue(s)

Enhancement #233

Key Design Decisions

• Implementation in cluster-proxy repository
• TokenReview-based hub token validation (reuses existing cluster-proxy pattern)
• On-demand token generation on managed clusters (via TokenRequest API)
• Distributed token caching on proxy-agents (80% of token lifetime)
• First-created-wins conflict resolution (no webhook required)
• ServiceAccount subjects use ManagedClusterSetBinding for cluster discovery
• User subjects (future) use Placement API for cluster selection

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: zhujian7
Once this PR has been reviewed and has the lgtm label, please assign deads2k for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[zhujian7]

Question: ServiceAccount-only vs. ServiceAccount + User subjects?

Should we support User subjects in addition to ServiceAccount subjects, or keep it ServiceAccount-only?

Option 1: ServiceAccount + User (current design)

• ✅ Covers both application and human user access
• ❌ More complexity: User subjects require explicit ClusterList, bearer tokens only, conflict resolution needed
• API: cluster-scoped SubjectMapping with hubSubject, clusters, conflict resolution

Option 2: ServiceAccount-only (simplified)

• ✅ Covers primary use case (application access, token storage elimination)
• ✅ Much simpler: namespace-scoped, no conflicts possible, no clusters field needed
• ✅ Natural 1:1 mapping via Kubernetes namespace/name uniqueness
• ❌ Missing human user access capability

Simplified API example:

apiVersion: authentication.open-cluster-management.io/v1alpha1
kind: ServiceAccountMapping  # Renamed from SubjectMapping
metadata:
  name: argocd-hub-sa       # Must match ServiceAccount name
  namespace: argocd          # Implicit: maps argocd/argocd-hub-sa
spec:
  managedServiceAccount:
    name: argocd-sa-for-hub
    tokenExpirationSeconds: 3600
  # No hubSubject - implicit from metadata
  # No clusters - always uses ManagedClusterSetBindings in namespace

Benefits:

• No duplicate mappings possible (Kubernetes enforces unique namespace/name)
• No conflict resolution logic needed
• Simpler API: just managedServiceAccount spec
• Cluster discovery automatic via ManagedClusterSetBindings in the namespace

@qiujian16 @xuezhaojun Do you see compelling use cases for User subjects? Or should we consider ServiceAccount-only (potentially as ServiceAccountMapping API)?

[zhujian7]

/cc @qiujian16 @xuezhaojun

[qiujian16]

can you also add clusterprofile part, it mitigate rbac issue for controller but introduce scalabaility concerns.

[qiujian16]

should note this is not the current managedserviceaccout, it does not need to create secret.

[qiujian16]

maybe not cluster scoped.

[qiujian16]

I think it should be namespace scoped .

[qiujian16]

if it is sa, namespace is not needed.

[qiujian16]

should not need a cluster list, it could be clusterset that bound to this namespace or placement.

[qiujian16]

could we have a spec field telling the agent that you do not need to map token to secret, just create the sa on the spoke.

[zhujian7]

Currently, we use an annotation, do you prefer a new spec field?

[qiujian16]

addin spiffe as another alternative

[qiujian16]

this might not be a drawback considering security.

[qiujian16]

we should also add a section on how cluster profile plugin should be updated accordingly.

[jnpacker]

Instead of individual cluster tokens leaking there is only the hub-sa token that needs to be secured, which at least lowers the blast radius to just a single secret to secure.

[jnpacker]

Will we include a CEL to try to enforce who can apply what annotations? Or is it consider allowed, if you have access to create a managedService account, you can reference an managedServiceAccountMappings?

[zhujian7]

Thanks @jnpacker very important catch!
Yes! We've implemented ValidatingAdmissionPolicy with CEL to prevent bypass attacks. Users cannot bypass SubjectMapping RBAC by directly creating/modifying ManagedServiceAccount resources with the hub-identities annotation.

How it works:

The policy validates that users have 'use' permission on the virtual subresource subjectmappings/managedserviceaccounts for:

• Resource name: The managed ServiceAccount name (being created)
• Namespace: The hub ServiceAccount's namespace (from the annotation)

Example: To create a ManagedServiceAccount mapping argocd:hub-sa → my-managed-sa, you need:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: allow-my-managed-sa
  namespace: argocd  # Hub SA namespace
rules:
- apiGroups: ["authentication.open-cluster-management.io"]
  resources: ["subjectmappings/managedserviceaccounts"]
  verbs: ["use"]
  resourceNames: ["my-managed-sa"]  # Managed SA name

Implementation:

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: managedserviceaccount-hub-identities-protection
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
    - apiGroups: ["authentication.open-cluster-management.io"]
      apiVersions: ["v1beta1"]
      operations: ["CREATE", "UPDATE"]
      resources: ["managedserviceaccounts"]
  validations:
  - expression: |
      (has(request.userInfo.username) &&
       request.userInfo.username == 'system:serviceaccount:open-cluster-management:subjectmapping-controller') ||
      !has(object.metadata.annotations) ||
      !('authentication.open-cluster-management.io/hub-identities' in object.metadata.annotations) ||
      object.metadata.annotations['authentication.open-cluster-management.io/hub-identities'] == '' ||
      object.metadata.annotations['authentication.open-cluster-management.io/hub-identities']
        .split('\n')
        .all(line, line == '' || (
          line.split(':').size() == 3 &&
          authorizer.group('authentication.open-cluster-management.io')
            .resource('subjectmappings/managedserviceaccounts')
            .namespace(line.split(':')[0])
            .name(object.metadata.name)
            .check('use').allowed()
        ))

[jnpacker]

Something interesting we should think about specifically because you used and ARGOCD example.

ArgoCD has the ability to allow for signed commits, you can post your public key into argocd to guarantee you are allowed to commit and push to the target server....

Maybe something that lends itself to this flow. If you send a signed commit to argocd on the hub and your public key is published to the argocd, we use that as the means to initiate a subject mapping.

In this way, there is actually NO credential at all stored on the hub or the spoke.
This is what I expect the user/group scenario will be more like down the road.

[zhujian7]

Thanks @jnpacker for this interesting idea! This provides a very meaningful scenario for mapping User subjects.

Current scope: ServiceAccount-only on both hub (source) and managed cluster (target) sides.

Future direction: The API is extensible for User subjects on the hub side (HubSubject.kind field). I think your GPG signing idea fits perfectly - verified user identity from signature → SubjectMapping → on-demand token generation (zero credentials stored).

Managed cluster targets remain ServiceAccounts because Kubernetes TokenRequest API requires them for token generation.

[kahirokunn]

#174

I believe one ManagedServiceAccount is required per cluster, but regarding Option 2: ServiceAccount-only (simplified), if I have the following situation, which cluster does it affect? Is it all of them?

apiVersion: authentication.open-cluster-management.io/v1beta1
kind: ManagedServiceAccount
metadata:
  name: my-sample
  namespace: spoke-1
---
apiVersion: authentication.open-cluster-management.io/v1beta1
kind: ManagedServiceAccount
metadata:
  name: my-sample
  namespace: spoke-2

[qiujian16]

#174

I believe one ManagedServiceAccount is required per cluster, but regarding Option 2: ServiceAccount-only (simplified), if I have the following situation, which cluster does it affect? Is it all of them?

apiVersion: authentication.open-cluster-management.io/v1beta1
kind: ManagedServiceAccount
metadata:
  name: my-sample
  namespace: spoke-1
---
apiVersion: authentication.open-cluster-management.io/v1beta1
kind: ManagedServiceAccount
metadata:
  name: my-sample
  namespace: spoke-2

each cluster will have one