LWS 1.0 Authentication Suite: Self-signed Identity using did:key

Self-issued identity is important for cases where applications act on their own behalf. This includes autonomous bots as well as server-side scripts, among others. In these cases, the agent is able to securely manage the private portion of a keypair, which it uses to generate signed JSON Web Tokens (JWT). This specification describes how this class of agents can generate authentication credentials that can be used with a Linked Web Storage while using agent identifers with the did:key: method.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and MUST NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The terms "authorization server" and "client" are defined by The OAuth 2.0 Authorization Framework [RFC6749].

The terms "JSON Web Token (JWT)" and "claim" are defined by JSON Web Token [RFC7519].

The terms "authentication credential" and "authentication suite" are defined by Linked Web Storage Protocol [LWS-PROTOCOL]

A self-issued authentication credential is serialized as a signed JSON Web Token (JWT). In order to use a JWT as an LWS authentication credential, the following additional requirements apply.

• The JWT MUST NOT use "none" as the signing algorithm.
• The JWT MUST use the sub (subject) claim for the LWS subject identifier. The subject identifier MUST use a did:key: URI.
• The JWT MUST use the iss (issuer) claim for the LWS issuer identifier.
• The JWT MUST use the client_id (client ID) claim for the LWS client identifier.
• The claims sub, iss, and client_id MUST all use the same URI value.
• Any audience restriction in the ID Token MUST use the aud (audience) claim. The aud claim MUST include the target authorization server.
• The JWT MUST include an exp (expiration) claim, indicating the time the token expires.
• The JWT MUST include an iat (issued at) claim, indicating the time the token was issued.

An example JWT that is also an LWS authentication credential is included below.

{
  "kty": "EC",
  "alg": "ES256",
  "typ": "JWT",
  "crv": "P-256"
}
.
{
  "sub": "did:key:zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv",
  "iss": "did:key:zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv",
  "client_id": "did:key:zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv",
  "aud": ["https://as.example"],
  "iat": 1761313600,
  "exp": 1761313900
}
.
signature

For subject identifiers that use the did:key method, a verifier will extract a public key from the identifier itself, as described in Section 3.1.3 of "The did:key Method" [did-key]. Using this public key, the signature of the JWT MUST be validated as described in [RFC7515], Section 5.2.

A verifier MUST validate all claims described by the authentication credential data model.

A verifier MUST ensure that the current time is before the time represented by the exp claim. Implementers MAY provide for some small leeway to account for clock skew.

A self-issued JSON Web Token used as an authentication credential MUST use the urn:ietf:params:oauth:token-type:jwt URI when interacting with an authorization server.