This document defines an authentication suite for the Linked Web Storage (LWS) protocol, enabling clients that are able to sign their own identity tokens to integrate with LWS.

This is an unofficial proposal.

Introduction

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 identifiers with the `did:key:` method.

Terminology

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 "agent", "authentication credential", and "authentication suite" are defined by Linked Web Storage Protocol [[!LWS10-CORE]]

Authentication Credential Serialization

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
      

Authentication Credential Validation

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.

Token Type Identifier

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.