Skip to content

identity-based-access.md

Latest commit

 

History

History
92 lines (66 loc) · 2.56 KB

identity-based-access.md

File metadata and controls

92 lines (66 loc) · 2.56 KB

Identity-Based Access

Live demo | Access Mode Comparison

Overview

Simplest access mode. The resource verifies the agent's signature and applies its own access control. No Person Server, no token exchange. The resource decides based on WHO signed the request.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant Resource
    Agent->>Resource: GET /data (signed, Signature-Key: sig=hwk or sig=jwks_uri)
    Resource->>Resource: Verify signature
    Resource-->>Agent: 200 OK (or 403 Forbidden)
Loading

Valid Signing Modes: hwk (pseudonymous) or jwks_uri (agent identity). NOT jwt — that requires a Person Server.

Code Example

Pseudonymous (hwk)

using AAuth.Crypto;
using AAuth;

var key = AAuthKey.Generate();

using var client = new AAuthClientBuilder(key)
    .UseHwk()
    .Build();

var response = await client.GetAsync("https://resource.example/data");
// 200 if resource's policy allows this key
// 403 if policy denies (signature valid, identity known, access denied)
// 401 if signature invalid (Signature-Error header explains why)

Agent Identity (jwks_uri)

using var client = new AAuthClientBuilder(key)
    .UseJwksUri("https://ap.example/.well-known/jwks.json", "key-1")
    .Build();

DI Registration

Pseudonymous (HWK)

using AAuth.Agent;
using AAuth.Crypto;

IKeyStore keyStore = FileKeyStore.Default();
var key = await keyStore.LoadAsync(configuration["AAuth:LocalKeyHandle"]!);

builder.Services.AddAAuthAgent("identity-hwk", options =>
{
    options.Key = key!;
});

Agent Identity (jwks_uri)

builder.Services.AddAAuthAgent("identity-jwks", options =>
{
    options.Key = key!;
    // No PersonServer → identity-only mode (no challenge handling)
});

Inject via IHttpClientFactory.CreateClient("identity-hwk"). See Dependency Injection for full reference.

Error Scenarios

Status Signature-Error Cause
401 invalid_signature Signature doesn't verify
401 unknown_key For jwks_uri: kid not found in JWKS
401 unsupported_algorithm Key uses wrong algorithm (only EdDSA supported)
403 (none) Signature valid but policy denies access

Further Reading