| Internet-Draft | AAuth-Bootstrap | May 2026 |
| Hardt | Expires 7 November 2026 | [Page] |
This document provides informational guidance for agent providers (APs) on enrolling agents and issuing AAuth agent tokens defined in [I-D.hardt-oauth-aauth-protocol]. It covers per-platform key handling, optional platform attestation, agent identifier strategies, and refresh patterns. The mechanisms described here are not normative protocol — they are common patterns that interoperable AP implementations can adopt or adapt.¶
Note: This section is to be removed before publishing as an RFC.¶
Discussion of this document takes place on GitHub at https://github.com/dickhardt/AAuth. Issues, comments, and pull requests are welcome there. Source for this draft is in the same repository.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 7 November 2026.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The AAuth Protocol [I-D.hardt-oauth-aauth-protocol] establishes that every agent has its own cryptographic identity — an agent identifier of the form aauth:local@domain, bound to a signing key, and attested by an agent token issued by an agent provider (AP). The protocol defines the agent token format and how agents present that identity to person servers (PSes), resources, and access servers (ASes). It does not specify how an agent comes to hold an agent token in the first place. That step is bootstrap, and it is the subject of this document.¶
Bootstrapping is the AP-side ceremony by which an instance of an agent acquires an agent token. The agent generates a signing key on the device or in the browser where it will run, presents whatever evidence the AP requires (a signed-in account, an attested device, a published JWKS, etc.), and receives an agent token whose cnf.jwk is bound to that key and whose sub is an aauth:local@domain identifier the AP has chosen.¶
After bootstrap the agent can participate in AAuth: it can sign HTTP messages per [I-D.hardt-httpbis-signature-key], identify itself at resources, and present its agent token to a PS so the user can bind the agent to themselves on first interaction.¶
sub claim's local part Section 6.¶
Throughout, when this document refers to "the durable key" and "the ephemeral key" it means the keys defined in Section 4. The ephemeral key's public part appears in agent_token.cnf.jwk and signs HTTP messages from the agent per [I-D.hardt-httpbis-signature-key]; the durable key serves as the AP's stable enrollment anchor and signs only at refresh. APs that use a single durable key for all signatures Section 4 can read references to "the ephemeral key" as referring to that same durable key.¶
{::boilerplate bcp14-tagged}¶
This document is informational guidance and does not itself impose normative requirements. Normative requirements relevant to bootstrap are defined in [I-D.hardt-oauth-aauth-protocol]; this document references them where helpful but uses lowercase "should" / "must" in its own descriptive prose.¶
Terms defined in [I-D.hardt-oauth-aauth-protocol] are used here with the same meaning. In particular:¶
iss, sub, cnf.jwk, optionally ps, and other claims.¶
This document additionally uses:¶
agent_token.cnf.jwk. The agent uses it to sign HTTP messages for the agent token's lifetime, then discards it on the next refresh.¶
On web, mobile, and desktop, APs should use a two-key pattern: a durable key that serves as the AP's stable enrollment anchor and is presented only to the AP at refresh, plus an ephemeral key generated fresh per agent-token issuance whose public part appears in agent_token.cnf.jwk and which signs HTTP messages for the agent token's lifetime. Refresh chains the new ephemeral key to the durable key via the jkt-jwt scheme [I-D.hardt-httpbis-signature-key]; see Section 8.¶
This pattern bounds the blast radius of an ephemeral-key leak to one agent token's lifetime, narrows the durable key's attack surface to the AP refresh path (it never signs requests to PSes, resources, or ASes), and accommodates hardware-backed durable keys on platforms that have them today and on platforms that may expose them in the future without protocol change. APs may use a single durable key for all signatures where simplicity outweighs these properties — receivers cannot distinguish the two patterns, since they only verify cnf.jwk against the HTTP signature.¶
Self-hosted agents Section 4.3 use a single key — the JWKS-published key serves as both the AP signing key and the agent's signing key, since there is no separate AP to refresh against.¶
The durable key is a non-extractable [WebCryptoAPI] key generated with extractable: false and stored in IndexedDB scoped to the AP's origin. The ephemeral key is also a non-extractable WebCrypto key, regenerated on each refresh and discarded when the next refresh produces its replacement.¶
Properties of the durable key:¶
Both keys are software-protected (browser sandbox) rather than hardware-protected. The two-key pattern still applies: the durable key signs only the periodic refresh (once per agent-token lifetime), while the ephemeral key signs every HTTP request and rotates on each refresh. APs that want the additional assurance of a WebAuthn ceremony at enrollment time can layer one on top; see Section 5. If browsers later expose hardware-backed credentials suitable for use as the durable key, the pattern accommodates them with no protocol change.¶
The durable key is generated and stored in the platform's hardware-backed keystore: the Secure Enclave on iOS or StrongBox on Android (or the Android Keystore where StrongBox is unavailable). The ephemeral key is a software key in app memory, regenerated on each refresh.¶
Properties of the durable key:¶
The AP typically also requires an attestation ceremony at enrollment to confirm the durable key is real keystore-bound material rather than software-generated. See Section 5. Because the durable key signs only at refresh, any per-op cost (keystore round-trip, optional user verification) is incurred at most once per agent-token lifetime, not on every request.¶
A self-hosted agent runs under a domain the user controls. The agent publishes its AP metadata document at /.well-known/aauth-agent.json per [I-D.hardt-oauth-aauth-protocol]; the JWKS itself is hosted at any HTTPS URL referenced by the metadata's jwks_uri. The corresponding private key should be hardware-bound where the platform supports it: macOS Keychain (Secure Enclave on supported hardware), Windows TPM, or Linux Secret Service.¶
Self-hosted agents act as their own AP — they self-issue agent tokens signed by the JWKS-published key. There is no separate AP to refresh against, so the two-key pattern does not apply: the JWKS-published key serves both as the AP signing key (signing self-issued agent tokens) and as the key whose public part appears in agent_token.cnf.jwk (signing HTTP messages). Because the trust anchor is a key the user controls and publishes, no platform attestation step exists. Other parties verify the agent token signature against the published JWKS, exactly as they would for any other AP.¶
TBD. Future revisions will cover key handling for native desktop applications, where the durable key would live in a hardware-backed store (macOS Keychain with Secure Enclave on supported hardware, Windows TPM via CNG, Linux Secret Service / TPM2) and the ephemeral key in process memory, following the same pattern as mobile.¶
Platform attestation gives the AP cryptographic evidence about the runtime context in which the durable key was generated. It is optional — the AAuth Protocol does not require it. APs choose whether to require attestation based on their threat model.¶
Common reasons an AP might require attestation:¶
Common reasons an AP might not require attestation:¶
[WebAuthn] provides user-verification and a hardware-rooted credential on web. APs that require it perform a registration ceremony at enrollment and an assertion ceremony at later sensitive operations. The credential is stored in the user's authenticator (TPM, Secure Enclave, security key, or platform syncing fabric).¶
Tradeoffs:¶
[AppAttest] attests to two things: that the durable key was generated in the device's Secure Enclave, and that the request originates from the AP's published app on a genuine Apple device. The AP receives an attestation object at enrollment which it verifies against Apple's attestation root, then accepts subsequent assertions signed by the same enclave key.¶
[PlayIntegrity] provides a device, app, and account integrity verdict signed by Google. The AP nominates a nonce, the agent invokes the Play Integrity API, and the AP verifies the resulting integrity token. Subsequent assertions can be signed by an Android Keystore (or StrongBox) key that the AP enrolled at the same time.¶
A practical rule of thumb:¶
The agent token's sub is an aauth:local@domain identifier. The domain part is the AP. The local part identifies the agent install at the AP — it must be stable for the lifetime of the install so PSes and other parties can recognize a returning agent.¶
APs are free to choose any opaque scheme for the local part: a random string assigned at enrollment, a deterministic derivation from the durable key's thumbprint, a sequential identifier, or a human-readable handle. When deriving from a thumbprint, use the durable key's thumbprint — the ephemeral key rotates on each refresh and is not a stable identifier. Receivers treat the identifier as opaque.¶
Each install's durable key is the basis for one agent identity. A returning user on a new device is a new agent. This keeps the AP minimal — it has no user-account system, no (user, durable_jkt) mappings, and no ability to correlate a single user's activity across their devices.¶
Multi-device users will see multiple agent entries in their PS dashboard. Grouping or merging those entries belongs at the PS, which already authenticates the user and is the correct layer for cross-device correlation. Rotation of the durable key produces a new agent identity; rotation of the ephemeral key (on every refresh) does not — the agent's sub is stable across ephemeral rotations. PS-side regrouping is the recovery path for durable-key changes.¶
A typical agent token issued by an AP, illustrating the claims described in [I-D.hardt-oauth-aauth-protocol] and the identifier strategies in Section 6.¶
JWT header:¶
{ "alg": "EdDSA", "typ": "aa-agent+jwt", "kid": "..." }
¶
JWT payload:¶
{
"iss": "https://ap.example",
"dwk": "aauth-agent.json",
"sub": "aauth:k7q3p9n2@ap.example",
"ps": "https://ps.example",
"cnf": { "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." } },
"iat": 1746316800,
"exp": 1746320400,
"jti": "..."
}
¶
Agent token lifetime is the AP's policy re-evaluation cadence — every refresh is the AP's chance to re-check device posture, attestation freshness, and account status before issuing a new token. A typical lifetime is 1 hour, matching common practice for proof-of-possession-bound access tokens. APs may use shorter lifetimes (e.g., 5–15 minutes) for higher-assurance deployments where attestation must be refreshed often, or longer lifetimes up to the AAuth Protocol's 24-hour ceiling for low-policy-churn deployments where refresh chattiness is undesirable.¶
On web, mobile, and desktop, refresh chains the new ephemeral key to the durable key via the jkt-jwt scheme [I-D.hardt-httpbis-signature-key]:¶
Signature-Key header under scheme=jkt-jwt.¶
cnf.jwk is the ephemeral public key.¶
Example refresh request:¶
POST /refresh HTTP/1.1
Host: ap.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority"
"@path" "signature-key");created=1746316800
Signature: sig=:...ephemeral-key signature bytes...:
Signature-Key: sig=jkt-jwt;jwt="eyJhbGc..."
{}
¶
The jwt parameter value is a JWT signed by the durable key with payload including the ephemeral public key (typically as cnf.jwk) and a jti for replay protection. The HTTP signature is produced by the ephemeral key. The AP correlates the two keys via the naming JWT's payload.¶
APs that opt for the single-durable pattern Section 4 sign the refresh request directly with the durable key under the hwk scheme [I-D.hardt-httpbis-signature-key]. The AP verifies the signature, looks up the enrollment by the key's thumbprint, and issues a fresh agent token with a new exp. The same cnf.jwk is carried through; the agent's key is unchanged.¶
APs that required platform attestation at enrollment typically do not re-attest on every refresh — the durable-key signature on the naming JWT (or the durable-key HTTP signature in the single-key pattern) is sufficient proof that the same enclave-resident key is making the request. APs that want periodic re-attestation can require a fresh App Attest assertion or Play Integrity verdict on a schedule (e.g., every 30 days) by including a server nonce in the refresh challenge.¶
Self-hosted agents self-issue agent tokens. There is no separate refresh ceremony — the agent generates a new agent token signed by its JWKS-published key whenever needed. The two-key pattern does not apply Section 4.3.¶
Refresh issues a new agent token bound to a fresh ephemeral key (or, in the single-key pattern, to the same durable key). Durable key rotation generates a new durable key and is a separate, rare event. Under the per-install identity model Section 6.1, a new durable key is a new agent — the PS treats it as new on first interaction, and any cross-device or cross-rotation continuity is handled at the PS by the user.¶
This section sketches a typical end-to-end enrollment for each platform. The sketches are illustrative; APs are free to vary them.¶
hwk scheme).¶
(ap_user, durable_jkt) and is now ready to issue agent tokens.¶
ps=PS_X, signed via jkt-jwt chaining the durable key to the ephemeral key Section 8. The AP returns an agent token with sub derived per the AP's identifier strategy Section 6 (using the durable key's thumbprint when derivation is used), ps = PS_X, cnf.jwk = the ephemeral public key, and any AP-attested claims.¶
(ap_user, durable_jkt, attestation) and is ready to issue agent tokens.¶
jkt-jwt.¶
/.well-known/aauth-agent.json per [I-D.hardt-oauth-aauth-protocol], with jwks_uri pointing to a JWKS containing the public part of that key.¶
There is no separate enrollment step — publication of the JWKS is the enrollment.¶
Every AP-attested claim in the agent token is only as trustworthy as the AP that signed the token. Receivers should apply policy proportional to their trust in the AP. An unfamiliar AP making strong attestation claims may warrant additional caution at the PS consent screen.¶
An ephemeral-key leak — via memory disclosure, in-page attacker, side channel, or similar — exposes only the signatures the agent makes during the current agent token's lifetime. At the recommended 1-hour lifetime, the blast radius is bounded to roughly that window before natural expiry forces replacement. Agents that detect compromise can decline to refresh, aging out the ephemeral key without explicit revocation. This bounding is the primary security argument for the two-key pattern Section 4.¶
Compromise of the durable key compromises the install's agent identity for the durable key's lifetime. The durable key signs only at refresh and is presented only to the AP, so its attack surface is much narrower than the ephemeral key's — but a successful compromise lets the attacker mint refresh requests indefinitely until the AP revokes the enrollment. APs should detect anomalous refresh patterns and provide a way for users to revoke a durable enrollment.¶
A non-extractable WebCrypto durable key cannot be exfiltrated by page-level attackers, but it can be used by them while they hold execution in the page. APs should pair WebCrypto-only enrollment with normal web hygiene (CSP, subresource integrity, dependency review) and should not treat the non-extractable property as a substitute for keeping the page's JavaScript clean. A hardware-backed durable key (Secure Enclave, StrongBox, TPM) cannot be exfiltrated at all, only used in-place — narrowing the threat to malicious code running in the agent application itself.¶
Platform attestation results (App Attest, Play Integrity, WebAuthn ceremonies) should be bound to a server-nominated nonce that is single-use and short-lived (5 minutes is a reasonable upper bound). The AP should verify that the attestation includes the nonce it issued; without this binding, a captured attestation can be replayed across enrollments.¶
Compromise of the self-hosted JWKS key allows the attacker to mint agent tokens for that user's domain. Users running self-hosted agents should use hardware-backed keys (Secure Enclave / TPM / StrongBox) and rotate the published JWKS if compromise is suspected.¶
An agent's sub is the same value at every PS the agent contacts, not a per-PS pairwise identifier. A stable sub lets each PS reliably re-identify the agent across sessions — that is the intended property — but it also means colluding PSes (or any party with cross-PS telemetry) can correlate the agent's activity across them. Under per-install identity Section 6.1, durable-key rotation produces a new sub, giving users a natural "fresh start" capability.¶
The AP that issued an agent token does not see the agent's subsequent traffic to PSes, resources, or ASes (they verify against the AP's published JWKS, not by calling the AP). The AP's view is limited to enrollment and refresh requests. APs should document their data retention practices for those events.¶
This document is informational and registers no new media types, JWT claim names, or metadata fields.¶
Note: This section is to be removed before publishing as an RFC.¶
This section records the status of known implementations of the patterns described in this document at the time of posting of this Internet-Draft, and is based on a proposal described in [RFC7942]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs.¶
TBD¶
Note: This section is to be removed before publishing as an RFC.¶
draft-hardt-aauth-bootstrap-01¶
/bootstrap endpoint, bootstrap_token, bootstrap announcement, agent server [now Agent Provider] bootstrap_endpoint / refresh_endpoint / webauthn_endpoint) has been removed. PS-side binding to a person now happens lazily on the agent's first interaction with the PS per the AAuth Protocol; the bootstrap document covers AP-side enrollment patterns only.¶
platform and device parameters are defined and described in the AAuth Protocol.¶
draft-hardt-aauth-bootstrap-00¶
TBD.¶