167 lines
8.3 KiB
Markdown
167 lines
8.3 KiB
Markdown
# Identity for users, agents and external agents — decision
|
|
|
|
**Status:** Draft
|
|
**Date:** 2026-09-22
|
|
**Authority:** `docs/architecture/organisation.md` for placement;
|
|
`docs/architecture/migration-decisions.md` §3 for the attribution semantics this
|
|
document implements; `docs/prds/agent2agent-protocol.md` for the A2A surface that
|
|
consumes it.
|
|
|
|
## Decision
|
|
|
|
One identity record covers every actor archie has: users, agents, external agents,
|
|
service accounts and the system. Authentication is delegated to the estate's OIDC
|
|
provider, and attribution stays archie's.
|
|
|
|
Authentication and authorisation are OSS archie integrates; a design that
|
|
hand-rolls either fails this document.
|
|
|
|
## The provider
|
|
|
|
**Authelia is the only identity provider**, because the estate already runs it in
|
|
front of the dashboard and it issues credentials for both kinds of caller: humans
|
|
use the authorisation code flow, and machines use the `client_credentials` grant,
|
|
which yields a token whose subject is the client's own identifier.
|
|
|
|
**Each agent is its own provider client.** A shared client would make two agents
|
|
indistinguishable in the audit trail and revocable only together, which is the
|
|
property attribution needs and the reason per-client registration is a
|
|
requirement.
|
|
|
|
**A person's client and an agent's client are registered separately**, because the
|
|
two token shapes differ and a shared registration would collapse the distinction
|
|
the attribution rests on. A person's token names them in `sub`. A machine's token
|
|
carries no `sub` at all and names its client instead, so a machine identity is keyed
|
|
on its client registration and exists one per client. A token asserting neither is
|
|
refused.
|
|
|
|
**A person's token requests the audience at the authorisation endpoint**, not only
|
|
at the token endpoint. A provider that otherwise returns the audience empty
|
|
produces a valid token archie must refuse, and that refusal looks like a signing
|
|
fault rather than a missing request parameter.
|
|
|
|
**SPIFFE/SPIRE is not adopted.** It is adopted and maintained, and its attestation
|
|
is strictly stronger than a secret: a workload proves what it is rather than what
|
|
it holds. It is rejected here on operational fit, not on quality: it adds a
|
|
control plane archie does not have, and the property it buys — identity attested
|
|
from the platform rather than from a presented secret — answers a threat archie
|
|
does not face, because archie's agents run as containers the operator launches and
|
|
already receive their credentials from the daemon that owns them. It is the right
|
|
answer when agents run on infrastructure the operator does not control.
|
|
|
|
## What archie owns
|
|
|
|
- **The identity record.** `internal/domain/identity` survives as archie's own
|
|
record of an actor and is not replaced by the provider's directory, because the
|
|
record carries what the directory does not: the lifecycle, the bindings and the
|
|
attribution below.
|
|
- **The lifecycle.** Active, suspended and retired, with rename, suspend,
|
|
reactivate and retire, remain archie's. Suspending an identity must stop it
|
|
acting whether or not the provider still authenticates it.
|
|
- **The subject binding.** An identity that proves itself is bound to the provider
|
|
subject that asserts it. This is the same bridge `identity_aliases` already
|
|
provides from a legacy name to an identity, so the second binding is the same
|
|
mechanism rather than a new one.
|
|
- **Attribution.** Who acted, and under whose authority.
|
|
- **The audit trail of identity changes**, which already records an actor, a source
|
|
and a request identifier for every mutation.
|
|
|
|
## What archie never owns
|
|
|
|
A credential, a password, a session, a token, a signing key, a second-factor
|
|
enrolment, or a permission rule.
|
|
|
|
## How an agent proves who it is
|
|
|
|
**An agent authenticates by presenting a token the provider issued to its own
|
|
client**, and archie validates it against the provider's published signing keys and
|
|
takes its subject as the acting identity. The agent holds a client secret; archie
|
|
holds only the public keys, so a compromised archie cannot mint an identity.
|
|
|
|
**A WebMCP tool call is not a proof of agent identity and cannot be made one.** A
|
|
page can invoke its own tools, so an agent's call and a page script's call arrive
|
|
at archie identically. No field, header or convention distinguishes them, because
|
|
the difference does not exist on the wire.
|
|
|
|
**A WebMCP tool call is therefore attributed to the identity the request
|
|
presented, with its source recorded as a hint.** It may record that the request
|
|
came from the dashboard; it never records that an agent acted, and it never
|
|
records that a human approved. A tool call that a page script can forge must not
|
|
be the thing an audit trail rests on.
|
|
|
|
**Agent-initiated action therefore arrives on a surface that carries a credential**
|
|
— the A2A surface, or an authenticated agent call — because that is the only place
|
|
an agent's identity is verifiable. An approval an agent makes is recorded as an
|
|
agent's action.
|
|
|
|
## The two attributions
|
|
|
|
Every task action records two identities, and `taskactions` gains both:
|
|
|
|
- **The acting identity**: the identity that performed the action, derived from
|
|
the credential the request presented and never from a string the request
|
|
supplied.
|
|
- **The authorising principal**: the identity whose authority the action used.
|
|
|
|
**The event kind describes the actor.** An action performed by an agent is
|
|
recorded as an agent's action even when a human's standing approval permitted it,
|
|
so `KindHumanApproved` is recorded only when the acting identity is a human. An
|
|
agent acting under a standing approval records itself as the actor and the human
|
|
as the authorising principal.
|
|
|
|
**An action with no authorising principal is recorded as unattributed rather than
|
|
attributed to the actor's own authority.** An agent's own decision and an agent
|
|
executing a human's delegation are different facts, and a record that collapsed
|
|
them would answer the audit question "approved by whom" with the wrong identity.
|
|
|
|
**The review gate's approver is the authorising principal of the approval on that
|
|
task's action record.** A task parked for a person names that person, not the
|
|
surface they used.
|
|
|
|
## External agents
|
|
|
|
**External agents are first-class, not a special case.** A peer is an identity of
|
|
kind `service_account`, bound to its own provider client, with the same lifecycle
|
|
as any other identity.
|
|
|
|
The cost is a provider client per peer, a subject binding, and a client secret
|
|
whose rotation is the peer's responsibility — and retiring a peer is two
|
|
operations rather than one, because its record and its provider client are retired
|
|
separately.
|
|
|
|
**A peer's identity is attributed like any other.** The acting identity is the
|
|
peer; the authorising principal is the identity that delegated to it, so an
|
|
external agent acting for a user records both.
|
|
|
|
## Authorisation is deferred
|
|
|
|
**No authorisation engine is built, deployed or configured.** The credential's
|
|
scopes are the only permission input, and they are verified by the same provider
|
|
that issued them, so the interim authorisation is OSS archie does not maintain.
|
|
|
|
**Two things are not built now**: a policy language, and a decision point that
|
|
answers per-skill or per-task questions beyond a scope.
|
|
|
|
**When a caller must be limited to a subset of what a scope permits** — A2A's
|
|
per-skill model, where a peer may invoke some skills and not others — the decision
|
|
point is added behind a single archie interface that takes a subject, an action and
|
|
a resource. The engine behind it is an in-process library or a policy service, and
|
|
the choice waits for that requirement rather than being made now.
|
|
|
|
## Verification
|
|
|
|
- An agent obtains a token from the provider with its own client credentials and
|
|
acts; its identity is recorded as the acting identity.
|
|
- A call with no credential is refused, and a call with an expired or
|
|
wrongly-signed token is refused.
|
|
- A token issued to one agent is not accepted as another agent's identity.
|
|
- A suspended identity cannot act, with a valid provider token.
|
|
- A WebMCP tool call records the presented identity and its source, and never
|
|
records an agent as the actor or a human as the approver.
|
|
- An agent's approval records the agent as the acting identity and the human whose
|
|
authority it used as the authorising principal, and does not record the human as
|
|
the actor.
|
|
- An approval with no authorising principal is recorded as unattributed.
|
|
- No password, session, token, signing key or permission rule exists in archie's
|
|
storage.
|