Federation authentication and trust

Use TLS 1.3 plus a pinned publisher signing key. TLS authenticates the configured host and protects credentials/data in transit. The Ed25519 key authenticates exported views, independent of a particular connection. A verified identity still needs a current Share grant. There is no automatic trust on first use or credential forwarding to a link in a document.

Personal pairing with mTLS

Provision a server certificate for the owner's hostname and a client certificate with Client Authentication usage from a trusted CA. On the owner, set server.mtls.client_ca and map the base64url, unpadded SHA-256 of the leaf DER to an operator-named principal:

server:
  mtls:
    client_ca: private/peer-ca.pem
    required: false
    principals:
      - principal: bob-peer
        certificate_sha256: replace-with-verified-leaf-fingerprint

Add certificate and private_key under Bob's peer config. Do not also configure a bearer token for certificate-only pairing. A certificate alone receives the federation capability, never ordinary catalog or admin access. In Alice's federation.grants, bind the same principal and optionally the same leaf fingerprint. required: true requires a valid client certificate for every TLS connection, including administrators. The service uses verified TLS connection state; forwarded certificate or user headers confer no identity.

OAuth workload access

Use an enrolled self-hosted issuer. The server supports JWT access tokens of type at+jwt and optional opaque-token introspection. It validates signature, issuer, audience, allowed algorithm, validity times and explicit principal/scope rules. It identifies the subject by issuer and subject, and optionally matches client_id. Role claims are not capabilities. OAuth mappings for whole-bundle administration need an explicit subject and whole-bundle prefix. Use a separate rule and credential for each workload.

server:
  oauth:
    resource: https://alice.example.invalid
    jwks_cache_secs: 60
    issuers:
      - issuer: https://identity.example.invalid
        jwks_url: https://identity.example.invalid/keys
        audience: https://alice.example.invalid
        algorithms: [ES256, RS256]
        rules:
          - principal: bob-peer
            subject: bob-workload
            client_id: bob-knowledge
            scopes: [knowledge:share]
            capabilities: [federation]
            prefixes: []
            proof: mtls

In Bob's peer entry, configure oauth.token_endpoint, client_id, resource, scopes and optionally client_secret_env. Use certificate and private_key for mTLS client authentication and certificate-bound tokens. For proof: dpop, set an operator-provisioned dpop_private_key PEM and dpop_public_jwk on the OAuth client. The issuer must bind the issued access token to that key. The server verifies method, canonical URI, token hash, timestamp and replay ID. The resource base URI must match the public endpoint for DPoP. For bearer tokens without sender binding, use proof: none. OAuth introspection is opt-in on one issuer per server, uses an enrolled endpoint, and does not cache active token decisions. Supply one of client_secret_env or an owner-private client_secret_file. OAuth access-token expiry caps the authorization lease. Key discovery is bounded and uses configured endpoints or same-origin issuer discovery. There are no token-service redirects.

OAuth client credentials are cached briefly until expiry. The Rust oauth::client_token helper also supports explicit access-token exchange for a named resource; a user's token is never silently forwarded or exchanged as part of ordinary federation. Grant revocation and issuer offboarding are separate. Grant changes take effect at the owner even while an OAuth token is valid. For JWT identity revocation use short expirations or provider introspection. DPoP server nonce negotiation is outside this profile.

Human OIDC sign-in

Register a native application with the issuer and loopback callback. Configure a named profile under server.oauth.login. For example:

server:
  oauth:
    login:
      lab-cli:
        issuer: https://identity.example.invalid
        authorization_endpoint: https://identity.example.invalid/authorize
        token_endpoint: https://identity.example.invalid/token
        jwks_url: https://identity.example.invalid/keys
        client_id: knowledge-cli
        resource: https://alice.example.invalid
        redirect_uri: http://127.0.0.1:8123/callback
        scopes: [knowledge:share]

Run knowledge -c <config> federation login lab-cli --token-file private/lab-access.token. Open the printed URL in a browser. The CLI listens only on the literal loopback address, validates callback state and S256 PKCE, and verifies the ID token's issuer, audience, nonce, signature and lifetime. It writes only the access token to a new private file. The ID token is never used as a Knowledge API credential. Local and gateway authorization still uses the server's configured OAuth rule and the grant. oidc::Login supports host-managed callbacks when embedding the library.

Operational boundaries

  • Pin issuer endpoints and the publisher key independently. A rotation needs explicit re-enrollment; keep certificates, token credentials, database keys and publisher keys separate. File-based private keys need owner-only permissions on Unix.
  • Peer requests use operator-enrolled endpoints, no redirects and no implicit proxies. Share manifests contain exact signed payload bytes, not trusted instructions. An archive or evidence locator never chooses a network destination.
  • A consumer sees only its configured aliases. A Share request sees only its scoped evidence and opaque change cursor. 304 Not Modified is evaluated after authorization. Replicated content and derivations are encrypted on disk; the original OKF source, intentional exports and local key files need filesystem protection.
  • A lost connection does not prove revocation. Default offline time is zero. A known denial closes serving immediately; a previously granted finite offline interval may permit cooperative continued use when the owner is unreachable. Already disclosed plaintext cannot be revoked by a protocol.

Primary standards: OAuth Security BCP, JWT access tokens, mTLS-bound tokens, DPoP, OIDC Core, OAuth for Native Apps, protected resource metadata.

Read Markdown →