Skip to content

Tenant-Scoped App Machine Identity v1

Purpose

Define the machine-identity direction for app controllers that operate tenant-owned shared runtimes.

This is the follow-on identity contract required by: - doc/architecture/App_Tenant_Shared_Attachment_Model_v1.md - doc/architecture/App_Tenant_Shared_Runtime_API_Direction_v1.md

Current State

The current implemented machine-identity model is project-scoped:

  1. service accounts belong to one project,
  2. tokens carry project-bounded authority,
  3. this is the correct model for project-scoped app controllers.

That model should not be stretched to mean tenant-owned shared runtime control.

Decision Summary

Tenant-owned shared runtimes need tenant-bounded machine identity.

Requirements: 1. authority must be scoped to one tenant, 2. identity must not become platform-global, 3. actions must remain auditable, 4. permissions must still be explicit and allowlisted, 5. project-scoped service accounts must remain intact for project-scoped apps.

Why Project-Scoped Service Accounts Are Not Enough

For a tenant-owned shared runtime, the controller may need to:

  1. read the tenant-owned runtime object,
  2. read and manage attached projects,
  3. resolve placement across eligible tenant projects,
  4. act on behalf of the tenant-owned runtime rather than one consumer project.

If a project-scoped service account is reused here, one of two bad things happens:

  1. one arbitrary project becomes the fake owner of a tenant-owned runtime,
  2. the project-scoped token is widened until it no longer behaves like a project-scoped identity.

Both are the wrong boundary.

The first tenant-shared model should use a delegated shared-runtime operator identity with these properties:

  1. bound to one org_id,
  2. bound to one shared_runtime_id,
  3. not bound to one consumer project_id,
  4. explicit allowlist of tenant-scoped app-runtime actions,
  5. auditable as actor_type = shared_runtime_operator or equivalent,
  6. separate from human tenant-admin tokens,
  7. separate from the existing project-scoped service-account model.

Contract Direction

The platform should reserve a distinct identity concept rather than overloading the current project-scoped service-account object.

Direction: 1. delegated app-operator identity issued for one tenant-owned shared runtime

This model is preferred over a generic tenant-wide service account because it keeps authority narrow and tied to one runtime owner object.

Invariants: 1. tenant-bounded authority 2. no cross-tenant operation 3. no platform-global privilege 4. explicit allowlisted endpoints 5. audit-safe attribution

Token Semantics Direction

A delegated shared-runtime operator token should directionally include:

  1. sub
  2. actor_type
  3. org_id
  4. shared_runtime_id
  5. explicit permission scope
  6. exp, iat, iss, aud, jti

It should not require a project_id claim when the owning resource is tenant-scoped.

If project-local actions are needed, those actions should be authorized through: 1. attachment policy, 2. endpoint allowlist, 3. tenant-bounded runtime ownership, 4. explicit target-project checks.

Authorization Direction

The first allowlist should likely include only:

  1. tenant-shared runtime read/write paths for the bound tenant,
  2. attachment read/write paths for the bound tenant,
  3. tenant-eligible allocation read paths where policy allows,
  4. tenant-scoped credential delivery paths when required,
  5. runtime status/member reporting paths for the bound shared runtime.

It should not include:

  1. generic tenant IAM administration,
  2. billing administration,
  3. platform-admin endpoints,
  4. cross-tenant reads or writes.

Audit Direction

Every tenant-scoped machine action should record:

  1. actor type
  2. actor id
  3. org_id
  4. target resource type/id
  5. result
  6. correlation_id

If a tenant-scoped action affects one consumer project, the audit trail should also capture that project_id in target or details fields where appropriate.

Credential Custody Direction

Tenant-scoped machine identity does not imply a new secret-custody model by itself.

But if the controller needs bootstrap or runtime credentials, the platform will need tenant-scoped custody and delivery semantics that match the chosen identity scope.

This should remain generic app-platform capability, not a Slurm-only exception.

Non-Goals

  1. Platform-global machine identity.
  2. Replacing project-scoped service accounts.
  3. Broadening human tenant-admin tokens into automation tokens.
  4. Final implementation in this slice.

Immediate Follow-On Work

  1. Add the delegated shared-runtime operator token model to the OpenAPI contract.
  2. Define endpoint allowlist for shared-runtime operator tokens.
  3. Align credential-delivery semantics with the chosen scope.
  4. Only then implement tenant-owned shared app controllers.
  1. doc/architecture/Service_Account_Model.md
  2. doc/architecture/App_Tenant_Shared_Attachment_Model_v1.md
  3. doc/architecture/App_Tenant_Shared_Runtime_API_Direction_v1.md
  4. doc/architecture/App_Control_Plane_v1.md
  5. doc/architecture/Shared_Runtime_Operator_Authz_Model_v1.md