Run grants and run tokens

A run grant is an IAM entity. It holds no secret.

The grant is a bitemporal row with the audit envelope of every entity. IAM owns it, so IAM never reads another component's table to check it. The owning component stores the grant id beside the work it authorises.

At create, IAM checks that the person holds every permission of the role in the party. A person cannot grant more than they hold. A second create for the same resource and grantor returns the active grant, so a retry is safe.

Source: run_grant_states.puml. Regenerate with plantuml -tpng doc/knowledge/security/run_grant_states.puml.

A revocation reaches a run in flight within one token lifetime. That bound is deliberate. A shorter bound needs a check on every request, and the cost of that grows with every call of every run.

A step service calls iam.v1.ops.exchange_run_grant with its own token. The request carries the grant id, the run id and the tenant from the step headers. IAM checks, in this order:

1. The caller holds iam::run_grants:exchange.
2. The caller's service name is in the grant's audience.
3. The grant exists, is not revoked, and is inside not_after and max_runs.
4. The grant's tenant equals the tenant in the request.
5. The grantor is active.

The caller's service name is the <Component>Service role its account holds, so the audience carries role names such as ReportingService and not host names. A grant's max_runs is the number of distinct run ids the issue log holds as issued for it, so an exchange that refreshes a token mid-run does not spend another run.

IAM then computes the permissions: the role's permissions, intersected with the permissions the grantor holds in the party now. A grantor who loses a permission loses it for their runs too, and a grantor who loses all of them makes the exchange answer forbidden with the reason grant_lapsed. IAM appends one row to the issue log and signs the token.

A run token creates no session row, so the sessions table does not grow with the number of runs.

Source: run_token_exchange.puml. Regenerate with plantuml -tpng doc/knowledge/security/run_token_exchange.puml.

The step sends the run token as a plain Authorization header. The token is an originated identity, not a relayed one.

The owner's handler calls make_request_context as it does for any caller. The context has the tenant, the party, the one visible party and the role's permissions. The handler checks the permission, and row-level security returns the party's rows and the shared rows of the system tenant. No owner has a code path for runs.

An owner that writes stamps modified_by with the grantor's username, as for any write by that person, and performed_by with its own service account, as for every write. The change reason names the run. An auditor sees who consented, which service wrote, and which run caused it. An owner that calls a further service relays the run token like any caller's token.

Each step service keeps one cache in memory per process. The cache is the composite's third part, and its rules are these:

• Key. The pair of grant id and run id. Two runs under one grant use two tokens, so the run_id claim stays exact.
• Lifetime. A token is used while it has more than 20% of its life left. The next request after that exchanges again. Concurrent misses share one exchange.
• Work longer than a token. A step whose work outlives its token keeps exchanging, so a run of hours lives through many tokens. An actor that cannot re-exchange holds no run token at all and acts under its own identity, as the grid's worker node does in Report execution at scale.
• Expiry in flight. An owner that answers token_expired causes one invalidation, one exchange and one retry of the same request. Any other refusal fails the request.
• Eviction. The cache drops a run's entries when the step completes and when the run reaches a terminal state. It is also a bounded LRU, so a missed event costs memory for at most one token lifetime.
• No persistence. The cache is never written to disk, a database, a message or a log. A restart empties it.
• Replicas. Replicas do not share the cache. Each replica exchanges on its first miss.

Source: run_token_cache_states.puml. Regenerate with plantuml -tpng doc/knowledge/security/run_token_cache_states.puml.

A run outlives many tokens, and the exchange bounds how long a revocation takes to reach it. The sequence below shows a step service exchanging again while it works, and the engine's own work acting without a run token.

Source: run_token_long_run.puml. Regenerate with plantuml -tpng doc/knowledge/security/run_token_long_run.puml.

A run makes one exchange per step service and per five minutes of that service's work. A run of four steps that lasts thirty minutes makes about seven exchanges. An exchange reads one grant and the grantor's permissions, then signs. IAM keeps grants and permissions in memory, and change events on those entities invalidate them. An RS256 signature costs about a millisecond, so one IAM replica serves thousands of exchanges a minute. IAM limits exchanges per service and per tenant, so a fault in one caller cannot exhaust it.

• The role, with each permission and why the run needs it.
• The resource name of its grants.
• The audience: the step services that exchange.
• When it creates, revokes and re-creates a grant, and what it does on grant_lapsed.