Skip to content

Implement org-owned service accounts with space entitlements and workload identity - #5520

Open
rkoster wants to merge 207 commits into
cloudfoundry:mainfrom
rkoster:service-accounts-poc
Open

rkoster wants to merge 207 commits into
cloudfoundry:mainfrom
rkoster:service-accounts-poc

Conversation

@rkoster

@rkoster rkoster commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Implement the Cloud Controller portion of Service Accounts for Cloud Foundry Workload Identity (community #1645), aligned with the RFC document at its merged revision.

Service accounts are org-owned identities, shared by apps only in explicitly entitled spaces of the same org. Each org has an admin-allocated, immutable, foundation-unique service_account_prefix; account names are immutable and unique within that org. Both use lowercase RFC 1123 labels of 3–63 characters.

For prefix acme-payments and account payments-worker:

Identity Value
UAA client ID / token subject cf:service-account:acme-payments:payments-worker
Instance-certificate DNS SAN payments-worker.acme-payments.svc.identity
Route-policy source cf:svc:acme-payments:payments-worker

One app has at most one account; many apps can share an account. Assignment grants no permissions: account use, CAPI roles, external grants and route policies remain explicit and independent.

Intentional RFC divergence: independent CAPI user lifecycle

Unlike RFC Appendix D, first bind provisions only the managed UAA client; it does not create a roleless CAPI user. CAPI users and their role grants remain independently managed. The existing CAPI authentication flow can lazily create a roleless OAuth user on its first API request; explicit roles are still required for resource access. No new explicit-user-creation command or authentication behavior is introduced here.

Disable, enable and service-account retirement do not create, disable or delete CAPI users or their roles, nor do they change external WIF identities/grants. Account deletion removes the managed UAA client and account resource. Ordinary space/org deletion still removes roles on deleted resources. If an identity is explicitly reused, independently retained CAPI roles can apply to the same client ID, just as retained external grants can; remove those grants independently when retiring access. This avoids coupling workload identity lifecycle to CAPI user lifecycle and requires no account-to-principal ownership field.

Proposed RFC amendment: nested attribution

Following Draft RFC amendments #1709, new managed registrations map attribution to cf.instance_guid, cf.app_guid, cf.space_guid and cf.org_guid, emitted by UAA as one nested cf object. The owning-org certificate requirement uses the same cf.org_guid mapping key. Issuer/subject identity and role authorization remain unchanged. Operators configure token lifetime through cc.service_accounts.token_validity_in_seconds: a positive integer defaulting to 300, with no CAPI-imposed five-minute ceiling. UAA must still enforce certificate expiry and its applicable token-policy limits. Existing managed registrations receive validity-only updates on their next provisioning/enable reconciliation; configuration deployment alone does not immediately update them, and issued tokens are unaffected. Identity/trust/authority drift still fails closed. The amendment is still proposed. Existing flat-claim UAA registrations are not silently rewritten and require deliberate reconciliation/retirement before using the new profile.

Cloud Controller implementation

Accounts, namespaces and permissions

  • Add /v3/service_accounts lifecycle, metadata, filtering, app listing and space-entitlement APIs, plus GET/PATCH /v3/apps/:guid/relationships/service_account.
  • Add organization service_account_prefix on creation or one-time unset-to-value update. Allocation is admin-only and atomic; an allocated prefix cannot be renamed, cleared or automatically released on org deletion. An unset prefix prevents account creation, entitlement expansion and assignment.
  • Space Developers create accounts with an initial entitlement to their space. Org Managers/admins oversee all accounts in the org, including accounts with no entitled spaces. Developers manage accounts entitled to their active spaces; sharing requires management authority or Developer access to an existing entitled space and the destination space. Cross-org entitlements are rejected; app writers assign only in entitled spaces. No new roles are introduced.
  • Add service_accounts.total_service_accounts to org quotas and an optional rolling seven-day creation budget per authenticated user/client across spaces. Admins are exempt from the budget; failed creation rolls back consumption and deletion does not refund it. Concurrent creation and first-bind provisioning are serialized, including MySQL repeatable-read handling.
  • Keep org-local deleted-name reservations and timestamped deletion history independently of audit retention. Explicit Org Manager/admin reuse_name creates a new UUID, is audited, and warns that external grants and still-valid old certificates may apply. Live collisions and quotas remain enforced.

Lifecycle, UAA registration and runtime identity

  • Provision a secretless UAA client on first bind through retryable pollable jobs, without creating a CAPI user. Reuse active provisioning jobs, reject registration collisions and human-user shadowing, and reconcile enable, disable and deletion. Independently managed OAuth users and their roles are left untouched.
  • Register the exact qualified SAN and owning-org claim restriction, reference an operator-defined UAA CA trust bundle, request bearer issuance with tls_client_certificate_bound_access_tokens: false, configure operator-selected token validity (default 300 seconds), and map nested instance/app/space/org attribution claims. Support the named allowed-resource-policy reference for federation audiences; developers do not control registration inputs.
  • Add typed BBS account name/prefix properties and generated Ruby bindings. Preserve existing certificate attribution; expose only non-secret discovery through VCAP_SERVICE_ACCOUNT. Snapshot process identity until explicit restart; new runtime tasks use the current assignment; staging excludes account identity.
  • Retain accounts when spaces are deleted, removing their entitlements. Org deletion cleans up accounts and managed UAA clients retryably; ordinary resource deletion removes roles on deleted orgs/spaces, while CAPI user records remain independently managed. Failures retain the parent for retry. Direct deletion/unentitlement checks desired and active process/task references and identity-bearing service bindings.
  • Create the final org-owned schema directly, with required prefix-qualified identities. There are no compatibility paths, identity fallbacks or backfill migrations for intermediate unpublished POC models. Retain deletion timestamps for future ad hoc operational queries; no reservation-statistics collection is implemented.

Explicit authorization and integrations

  • Resolve qualified service-account principals locally for existing CAPI role APIs. Binding does not grant resource roles.
  • Support qualified cf:svc:<prefix>:<name> route-policy sources, account resolution and domain org/space restrictions while preserving existing source semantics.
  • Snapshot account identity on service bindings and add { issuer, subject } to the CF platform context.service_account of broker bind requests for ready accounts; service keys do not receive it. Identity-based bindings must be removed before app reassignment. Existing bindings require rebind to adopt the account. Broker-side shared-grant lifecycle remains the broker's responsibility.
  • Add lifecycle, prefix allocation, entitlement, assignment and name-reuse audit evidence, API documentation, migrations and regression coverage.

Verification

  • All 18 GitHub checks pass at 498d40b4c, including normal and backward-compatibility suites on MySQL 8.0/8.2 and PostgreSQL 14/15/17, OpenAPI request conformance, docs, RuboCop, CodeQL and CLA. Main test run · backward compatibility.
  • Full local OpenAPI request-conformance run: 8,164 examples, zero failures before the final database-specific corrections; subsequent CI OpenAPI conformance also passes at the current head.
  • Full migration/creation-budget regression runs on MySQL 8.2 and PostgreSQL 17 passed with platform-specific pending examples; additional MySQL creation, quota, assignment and entitlement regressions passed 68 examples. Meaningful failing-test RED and passing-implementation GREEN commits are preserved, including deterministic concurrency and FK/index rollback regressions.
  • Lab validation with the companion native CLI/CATs demonstrates shared qualified account identity across apps in entitled spaces, independent instance keys, bearer HTTPS CAPI access with explicit roles, wrong/unbound identity denials, disable/enable, restart-sensitive assignment, current-identity tasks, staging exclusion, and Org Manager recovery after deletion of the last entitled space. Account-routing cases exercise certificate-only access/denials, disable semantics and domain space scope. Companion acceptance tests.
  • UAA lab checks demonstrate attribution claims, bearer tokens without cnf, named resource-policy audience selection/denials, and policy-only updates without re-registering account clients. These are integration evidence, not proof of every external provider's token requirements.

Dependencies, rollout and remaining validation

  • Companion changes: capi-release #702, BBS #168, Diego #1216, CLI #3875, and CATs #2193. Generated BBS consumers and deployment/module pins must agree on the qualified account contract.
  • UAA mTLS baseline is merged in UAA #4109, superseding the earlier build(deps): bump json_pure from 2.7.6 to 2.8.1 #4076 baseline. Named federation resource policies are tracked by UAA #4125 / implementation #4137; build(deps-dev): bump rubocop from 1.69.1 to 1.69.2 #4137 is the tested lab baseline.
  • Service-account activation uses one default-off setting: cc.service_accounts.enabled in BOSH, rendered as service_accounts_enabled for API, worker, clock and deployment updater. Deploy compatible UAA/BBS/Diego and routing components before enabling it; there is no numeric contract-version setting. The app-facing token endpoint must support reachable, trusted mTLS, either directly or through UAA's authenticated trusted-proxy mode.
  • Deploy compatible routing enforcement before enabling CAPI account route-policy producers. There is no router-version configuration gate; parallel release updates do not establish this ordering.
  • Remaining integration criteria include the near-leaf-expiry token lifetime cap, long-running credential renewal, real cloud-provider federation (including AWS azp/audience semantics), broker-managed shared grants end to end, Windows runtime, and namespace-limited UAA client administration. CAPI registration alone does not demonstrate these UAA/provider/broker properties.
  • Disable stops new token issuance when effective; unbind/restart, entitlement changes and deletion are not immediate cryptographic revocation of existing certificates, JWTs or exchanged provider credentials. Certificate-only route access requires removal of the relevant route policy to withdraw its grant.

The RFC document's recorded status is Draft, although community #1645 is merged. This PR implements the CAPI scope and records its cross-component dependencies; it does not claim complete end-to-end RFC acceptance.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Potential foundation-wide entitlement scans and repeated UAA discovery while bind transactions hold locks warrant human assessment of scalability and availability risks.

No open issues 🎉

4 resolved since last review

Review effort: Balanced

@rkoster

rkoster commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Potential foundation-wide entitlement scans

Addressed in f2903b3 (RED 58a04f1): added a space-first (space_guid, service_account_guid) index to the entitlement schema, with creation/rollback coverage. Account-first lookups retain the primary key. This addresses the space-filtered lookup path noted in review #5520 (review).

@rkoster

rkoster commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

repeated UAA discovery while bind transactions hold locks

Addressed in e4a087a (RED 2f0f042): broker clients now use shared, synchronized issuer discovery with a five-minute cache instead of constructing a token decoder per bind. Tests cover reuse across clients, concurrent callers, expiry, retry after failure, and refusal to use expired data. Cold/expired discovery still requires a UAA request. Combined migration/discovery/broker/V2 suites pass 216 examples on each of PostgreSQL 17 and MySQL 8.2; changed-file lint passes. Review: #5520 (review).

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because a critical edge case involving role grants before provisioning can reject unclassified client users, blocking provisioning and retries before the first token is issued.

No open issues 🎉

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants