ProxyToken Authentication

For cross-instance requests, ProxyTokens authenticate the requesting instance.

ProxyToken Structure

{
  "iss": "alice.example.com",      // Requesting instance
  "aud": "bob.example.com",         // Target instance
  "sub": "alice.example.com",       // User identity
  "exp": 1738400000,                // Short-lived (5-60 min)
  "iat": 1738396800,
  "action": "read_file",            // Requested operation
  "resource": "f1~abc123...",       // Resource identifier
  "k": "20250205"                   // Signing key ID
}

Creation

Algorithm: Create ProxyToken

Input: requester id_tag, target_instance, action, resource
Output: JWT token string

1. Retrieve latest signing key:
   - Query latest key_id for tenant
   - Load private key from AuthAdapter

2. Build JWT claims:
   - iss: Requester's id_tag
   - aud: Target instance domain
   - sub: Requester's id_tag
   - exp: Current time + 30 minutes
   - iat: Current time
   - action: Requested operation
   - resource: Resource identifier
   - k: Key ID used for signing

3. Sign JWT using ES384 algorithm:
   - Use private key
   - Standard JWT encoding

4. Return base64-encoded JWT

Validation

Algorithm: Validate ProxyToken

Input: JWT token string
Output: Result<ProxyTokenClaims>

1. Decode JWT without signature verification (read claims)
2. Extract issuer and key_id from unverified claims
3. Fetch issuer's profile from remote instance
4. Look up public key by key_id in profile
5. Verify JWT signature using issuer's public key (ES384)
6. Check expiration timestamp:
   - If exp < current_time: Return TokenExpired error
7. Check audience claim:
   - If aud != this_instance.base_id_tag: Return InvalidAudience error
8. Return verified claims

Validation ensures:
- Token signed by claimed issuer
- Token not expired
- Token intended for this instance

Use Cases

ProxyTokens are used for:

  • File fetching: Downloading attachments from remote instances
  • Profile queries: Accessing extended profile information
  • Database sync: Read access to federated databases

See Also