Integration adapters

Integration adapters connect the gateways, platforms and clients that terminate mTLS to the trust you manage in Mutual Trust. Every change is a hashed plan you approve, applied by mt-adapt in your environment and proven with real requests.

What adapters do

A valid certificate chain is only half of mutual TLS. Something in your infrastructure terminates the connection (a reverse proxy, an API gateway, a load balancer, an interface engine or the client application itself), and that component must trust the right issuing chain, require client certificates and hand each request to an authorization decision. Integration adapters connect those components to the trust you manage in Mutual Trust.

Each adapter knows one platform surface: where mTLS terminates, how to read the current configuration, how to change trust safely and how to prove the result. Adapters run inside mt-adapt, a single binary you run on a workstation or in CI with your own platform credentials. Mutual Trust never holds those credentials. It computes the desired state, records your approvals and keeps the evidence.

Trust-chain acceptance and per-resource authorization are always separate changes. There is no combined "install the CA and allow access" step: the gateway learns to verify certificates from your trust space, and the Mutual Trust enforcer decides, per request, whether that workload may call that route.
Nothing changes without a plan you approved. Every change is a hashed plan; the runtime applies only a plan whose hash an approval names.
Every adapter verifies with real requests. Positive and negative mTLS requests prove that the authorized partner gets through and everything else is denied.

Roles and delivery modes

An adapter plays one or more roles on a connection:

Adapter roles
Role	What it does	Examples
`client`	Presents the workload certificate and trusts the server it calls.	Java and Spring Boot, .NET, OpenSSL and curl, cert-manager
`tls_terminator`	Terminates mTLS and verifies client certificates against the issuing chain.	NGINX, Envoy, HAProxy, Traefik
`policy_enforcer`	Sends every request to an authorization decision (the Mutual Trust enforcer or a native ACL) and fails closed.	NGINX `auth_request`, Envoy `ext_authz`, Traefik `forwardAuth`

Each adapter advertises the delivery modes it supports for the exact platform versions it was tested with:

Delivery modes
Mode	Meaning
`G` Guided setup	Exact manual steps and test vectors for your platform. You apply them with your own tooling.
`C` Generated configuration	Versioned configuration files with SHA-256 digests and a signed export, ready for your GitOps or change process.
`A` Approved automatic apply	mt-adapt applies the approved plan itself, validates it (for example `nginx -t`), reloads and keeps a rollback artifact. Offered only for versions whose full acceptance suite passed.
`O` Observation	Read-only telemetry: source and freshness. Request-level visibility is claimed only when connector logs are available.
`V` Active validation	Positive and negative mTLS requests against the live endpoint, with expected and observed results.

Platforms that are set up with guided steps show Guided setup in the catalog. mt-adapt asks a short assessment (deployment topology, where TLS actually terminates, versions, the configuration surface your vendor supports), then produces the steps and the positive and negative test vectors that prove the result.

Plan, approve, apply, verify

Register the integration in the portal (Integrations, Register an integration) or with POST /v1/integrations: the adapter, the endpoint it protects (hostname, port, SNI, route, TLS terminator and an optional protected upstream), and optionally the service and partner connection it enforces. Registration pins the approval key mt-adapt verifies.
Inspect. mt-adapt inspect reads the current configuration (read-only) and records evidence with its source, platform version and timestamp. Secrets are redacted before anything is written.
Fetch the desired state. mt-adapt desired fetch (GET /v1/integrations/{id}/desired-state) returns the issuing chain and bundle hash, the revocation mode, the identity bindings of the active partner grants and the policy mapping, exactly as mt-adapt reads it. The Desired-State-Fingerprint header (and ?detail=1) carry its fingerprint; detail=1 adds the CRL URLs, the enforcer deny set and the route policy behind the bindings.
Plan. mt-adapt plan computes the exact, version-specific changes, a redacted human-readable diff, test vectors and parallel-trust and rollback notes, then seals the plan with its plan_hash.
Submit. mt-adapt plan submit (POST /v1/integrations/{id}/plans). The control plane recomputes the plan hash and the desired-state fingerprint and refuses a plan that was edited, that names another tenant, integration or endpoint, or that was computed against an older desired state. Submitting the same plan twice is a no-op.
Approve. A service owner or trust administrator reviews the diff in the portal and approves it. The confirmation names the tenant, endpoint, environment and plan hash.
Apply. mt-adapt apply --fetch-approval fetches a fresh approval, verifies it with the pinned key and applies exactly that plan. Re-applying a plan that is already in place changes nothing; a target whose configuration drifted from both the inspected and the planned state aborts with conflicting_configuration.
Verify and report. mt-adapt verify runs the positive and negative requests; mt-adapt report records the apply and verification runs. They appear on the integration's runs timeline and evidence matrix.

One change, end to endmt-adapt --config mt-adapt.yaml inspect --target edge --out inspection.json
mt-adapt --config mt-adapt.yaml desired fetch --integration $ID --out desired.json
mt-adapt --config mt-adapt.yaml plan --inspection inspection.json --desired desired.json --out plan.json
mt-adapt --config mt-adapt.yaml plan submit --integration $ID --plan plan.json
# approve in the portal, then:
mt-adapt --config mt-adapt.yaml apply --plan plan.json --fetch-approval --out result.json
mt-adapt --config mt-adapt.yaml verify --plan plan.json --url https://api.example.com:443 --client authorized=client.pem,client-key.pem --out verification.json
mt-adapt --config mt-adapt.yaml report --result result.json --verification verification.json --integration $ID

mt-adapt authenticates to the API with an API credential (MT_API_KEY) that holds the service owner or trust administrator role for the organization that owns the integration. Approvals always happen in the portal with a passkey or SSO session.

Download mt-adapt from https://mutualtrust.io/downloads/adapters/<os>-<arch>/mt-adapt (for example darwin-arm64, linux-amd64, windows-amd64). The integration's Run mt-adapt tab in the portal shows the configuration file, the pinned approval key and these commands with your integration id filled in.

A rollback is a plan too: the rollback artifact mt-adapt keeps after an apply has its own plan hash, is submitted to the same endpoint and needs its own approval.

Approvals

An approval is an ES256 compact JWS signed by the isolated signer with your trust space's manifest key, the same key your gateways already pin. Its protected header has typ mt.adapter-approval.v1+jws and the kid of that key; its claims bind one plan to one place:

ApprovalV1 claims{
  "typ": "mt.adapter-approval.v1",
  "tenant_id": "org_...",
  "integration_id": "int_...",
  "adapter_id": "nginx.oss.server",
  "endpoint": "https://api.example.com:443",
  "plan_hash": "b168562a...",
  "approver": "usr_...",
  "iat": 1794657600,
  "exp": 1794658500
}

Who can approve. A service owner or trust administrator, from a browser session signed in with a passkey or your organization identity provider. API credentials cannot approve, and sandbox guest sessions cannot approve.
Step-up. Approving needs a sign-in or re-authentication from the last 15 minutes. Passkey accounts confirm with their passkey in place; organization accounts sign in again.
Separation of duties. When the organization has more than one service owner or trust administrator, the person whose credential submitted a plan cannot approve it. Each integration can turn this rule off.
Lifetime. An approval decision stays usable for 24 hours. Each approval JWS lasts at most one hour, so fetch a fresh one for each apply.
Independent checks. The signer re-reads the approval from the database before signing: approved, not expired, same plan hash, tenant, integration, adapter and endpoint, and the key pinned at registration. The runtime then refuses a missing, expired, rejected or stale approval, a changed plan hash, another tenant and another endpoint, each with its own error code.
Stale approvals. If the desired state changes after a plan was approved (an issuing CA rotates, a partner grant is suspended), the control plane stops issuing approvals for that plan with approval_stale. Plan again.

Evidence

Every adapter is held to the same eight acceptance categories. The integration's evidence matrix shows the latest result for each, with case counts, timings and provenance (the run, the adapter and platform versions, and when it was observed).

Acceptance categories
Category	What it proves
1. Identity authorization	The authorized client reaches the allowed resource; a valid chain with the wrong identity is denied.
2. Certificate validation	Unknown issuer, expired, not yet valid, wrong EKU, malformed chain and invalid client proof are denied.
3. Revocation and withdrawal	Withdrawal is enforced and the time it takes is measured. A platform that cannot revoke natively is compensated by the Mutual Trust enforcer.
4. Idempotent apply	The same plan applied twice widens nothing and duplicates nothing; conflicting configuration aborts.
5. Safe failure	A failed update leaves the last known good configuration in place; nothing fails open.
6. Approval binding	Stale and rejected approvals, a changed plan hash, another tenant, another endpoint and an expired scope are all refused.
7. Resilience and renewal	Restarts, control-plane outages, renewal and overlapping trust anchors behave as documented.
8. Redaction	Logs and reports never contain private keys, tokens, protected endpoint details or other tenants.

Runs are append-only. Each run records its operation, plan hash, idempotency key, before and after fingerprints and outcome; reporting the same run twice is a no-op, and a run that changed a target must reference an approved plan.

Security model

Your credentials stay with you. mt-adapt runs in your environment and uses your platform credentials with the least privilege each adapter documents. Mutual Trust receives plans, approvals and results, never platform secrets.
Integrity end to end. desired_state_fingerprint is the SHA-256 of the canonical JSON of the desired state; plan_hash is the SHA-256 of the canonical JSON of the adapter, version, target, inspection fingerprint, desired-state fingerprint and changes. The control plane and the runtime compute both independently and must agree byte for byte.
Deny by default. Policy mappings require fail_closed; the enforcer denies anything not explicitly granted, exactly as described in the security model.
Redaction. mt-adapt redacts secrets and protected upstream details before a plan or report leaves the host, and the control plane redacts them again before storing a diff. Upstream addresses are never written to logs, the audit log or the Sectigo staff console.
Tenant isolation. Integrations belong to the API owner organization; other organizations cannot see them, and a cross-tenant request is answered as not found.
Audit. Registration, plan submission, every decision and every run are written to your organization's audit log and published as integration.* events.