AegisAegis
Dashboard
AegisAegis Developer Portal

Developer Search

Press ⌘K or Ctrl+K to jump through guides and public API docs for user-owned master key and scoped credential flows.

Developer Docs

MCP Broker Security Model

Production authentication and authorization model for MCP credential brokerage: workload identity, nonce replay protection, control-plane SPIFFE bootstrap, sender-constrained access, token lifecycle controls, tenant/principal isolation, audit-driven detections, and data ownership boundaries where user-held key material remains outside platform access.

AuthN

Workload Proof

Exchange workload identity proof for short-lived broker tokens with strict proof type and nonce checks, without transferring user master keys.

AuthZ

Scope + Principal Bound

Enforce allowlisted scopes and bind leases to both tenant and principal to prevent cross-workload reuse.

Audit

Detect + Respond

Emit broker lifecycle events and alert on replay attempts, denial spikes, and abnormal redemption patterns.

Required Controls

  1. Authenticate MCP as workload principal via OIDC federation or mTLS.
  2. For user-driven broker flow, mint with `MintUserApiToken` using specific credential selectors.
  3. Call `ExchangeWorkloadToken` with one-time nonce and PoP key identifier.
  4. Bootstrap SPIFFE identity using `BeginSpiffeBootstrap` + `CompleteSpiffeBootstrap` with CSR.
  5. Issue short-lived token (default 10m, capped at 15m).
  6. Verify DPoP signatures using JWKS public keys bound to `pop_key_id` (`kid`).
  7. For mTLS exchange, require `pop_key_id` to match provisioned SPIFFE cert fingerprint.
  8. Send `request_proof` on every create/redeem/revoke call (DPoP JWT or mTLS fingerprint mode).
  9. Reject replayed workload nonces and cross-principal lease access.
  10. Write immutable audit event for each broker action.

Exchange Claims

{
  "sub": "mcp:desktop-broker:host-01",
  "tenant_id": "business-default",
  "aud": "aegis-api",
  "scope": [
    "credential.lease.create:provider:gcp:app:billing-prod:account:deploy-bot",
    "credential.lease.redeem:provider:gcp:app:billing-prod:account:deploy-bot"
  ],
  "role": "org_admin",
  "jti": "2c8e6a96-78dc-4da3-8ab9-6f012b4c2a32"
}

Lease Request Proof

Lease endpoints enforce sender-constrained proofs. For DPoP mode, include `request_proof.dpop_jwt` with `ath`, `htm`, `htu`, `jti`, `iat`, and `nonce` claims. For mTLS mode, use bootstrap-provisioned `mtls_fingerprint`.

{
  "proof_type": "dpop_jwt",
  "dpop_jwt": "<signed_jwt_with_htm_htu_ath_jti_iat_nonce>",
  "nonce": "nonce-create-0001"
}

Scope Matrix

  • credential.lease.create: create short-lived credential leases
  • credential.lease.redeem: redeem lease into ephemeral credential material
  • credential.lease.revoke: revoke active lease immediately
  • broker.audit.read: read broker audit event stream

Token Lifecycle

  1. Bootstrap token: SPIFFE scopes only, target TTL <= 5 minutes.
  2. Broker access token: lease scopes, default TTL 10 minutes, hard cap 15 minutes.
  3. Lease artifact: single-use or low redemption, short expiry, target-bound.
  4. Revocation: explicit revoke path for compromised key, host, or principal.
  5. Storage: keep in memory and avoid durable local bearer token storage.

Scoped Credential Selectors

Scope is capability + resource selector. Authorization evaluates tenant, principal, action, and target resource together.

credential.lease.create:provider:gcp:app:billing-prod:account:deploy-bot
credential.lease.redeem:provider:aws:app:payments:account:ci-role
credential.lease.revoke:provider:gcp:app:analytics:account:breakglass
  • Grant create/redeem/revoke scopes independently (no implicit action inheritance).
  • Allow wildcard selectors only under explicit elevated policy.
  • `MintUserApiToken` rejects wildcard selectors; user tokens are credential-specific.
  • Deny and audit scope escalation attempts by default.
  • Selector-scoped checks are enforced at runtime for lease create/redeem/revoke operations.

Extended Doc

Full architecture and threat model are documented in docs/api/mcp-broker-security-model.md.

Open Usage Patterns

API Surface

Use `BeginMcpOauthDeviceAuthorization`, `ApproveMcpOauthDeviceAuthorization`, `ExchangeMcpOauthDeviceAuthorization`, `MintUserApiToken`, `ExchangeWorkloadToken`, `BeginSpiffeBootstrap`, `CompleteSpiffeBootstrap`, `CreateCredentialLease`, `RedeemCredentialLease`, `RevokeCredentialLease`, and `ListBrokerAuditEvents` for the broker lifecycle.

Open API Explorer