Skip to content

Shared Runtime Operator Authz Model v1

Purpose

Define the authorization contract for delegated shared-runtime operator identity used by tenant-owned shared app runtimes.

This document narrows the follow-on work after: - doc/architecture/App_Tenant_Shared_Attachment_Model_v1.md - doc/architecture/App_Tenant_Shared_Runtime_API_Direction_v1.md - doc/architecture/Tenant_Scoped_App_Machine_Identity_v1.md

Decision Summary

The delegated shared-runtime operator token is not a general tenant-admin token.

It is a machine token with authority limited to: 1. one tenant (org_id), 2. one shared runtime (shared_runtime_id), 3. one explicit allowlist of app-runtime control-plane actions.

It must not inherit: 1. generic tenant IAM administration, 2. generic tenant billing administration, 3. platform-admin powers, 4. arbitrary cross-project data visibility.

Actor Model

The token represents:

  1. a non-human delegated operator identity,
  2. bound to one tenant-owned shared runtime,
  3. acting on behalf of that runtime only.

Suggested actor semantics: 1. actor_type = shared_runtime_operator 2. org_id = <tenant> 3. shared_runtime_id = <runtime>

Claims Direction

The token should directionally carry:

  1. sub
  2. actor_type
  3. org_id
  4. shared_runtime_id
  5. scope
  6. exp
  7. iat
  8. iss
  9. aud
  10. jti

It should not require a consumer project_id claim because the owner resource is tenant-scoped, not project-scoped.

If a project-targeted operation is allowed, that project must be checked against: 1. the shared runtime attachment model, 2. the endpoint allowlist, 3. the target resource itself.

First Endpoint Allowlist

The initial allowlist should be narrow.

Allowed directionally

  1. GET /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}
  2. GET /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments
  3. GET /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments/{attachment_id}
  4. shared-runtime runtime/member report paths once those exist
  5. tenant-scoped credential delivery paths explicitly bound to the same runtime, if and only if that capability is introduced
  6. tenant-aware allocation read paths explicitly limited by attached-project and contribution policy, once those exist

Explicitly not allowed

  1. creating or deleting arbitrary shared runtimes outside the bound shared_runtime_id
  2. attaching or detaching arbitrary projects unless the specific endpoint is intentionally delegated to the operator
  3. generic tenant IAM or billing administration
  4. platform-admin endpoints
  5. unrestricted reads over all tenant projects or allocations

Authorization Rules

Evaluation should require all of:

  1. actor_type == shared_runtime_operator
  2. token org_id matches path org_id
  3. token shared_runtime_id matches target runtime resource
  4. endpoint is on the allowlist for this actor type
  5. any project-targeted resource is attached to that shared runtime

This means: - tenant scope alone is not enough, - runtime binding alone is not enough, - both identity scope and resource relationship must hold.

Audit Requirements

Every delegated shared-runtime operator action must record:

  1. actor_type
  2. actor_id
  3. org_id
  4. shared_runtime_id
  5. target resource type/id
  6. result
  7. correlation_id

If a specific project is involved, audit metadata should also include that project_id.

Relationship to Project Service Accounts

Project-scoped service accounts remain the correct model for: 1. project-scoped app controllers, 2. project-owned automation, 3. project-local access-credential delivery and placement flows.

Delegated shared-runtime operator identity is an additional model, not a replacement.

Non-Goals

  1. General tenant-wide machine admin.
  2. Broad cross-project read access by default.
  3. Replacing human tenant-admin flows.
  4. Final implementation in this slice.

Immediate Follow-On Work

  1. reserve the claim shape in OpenAPI,
  2. reserve or document the initial allowlist in OpenAPI descriptions,
  3. extend auth middleware to recognize actor_type = shared_runtime_operator,
  4. implement allowlist and resource binding checks in handlers/services.
  1. doc/architecture/Tenant_Scoped_App_Machine_Identity_v1.md
  2. doc/architecture/App_Tenant_Shared_Runtime_API_Direction_v1.md
  3. doc/architecture/App_Tenant_Shared_Attachment_Model_v1.md
  4. doc/architecture/Platform_IAM_Model_v1.md