Issue Evidence Gateway access tokens with Registry Mint

Start with the completed candidate from Build and deploy an Evidence Gateway project. Use Registry Mint when that deployment has no suitable OpenID Connect (OIDC) issuer for Evidence Gateway. Mint is a separate supporting service. Evidence Gateway does not require Mint, and an external HTTPS OIDC issuer follows the same Evidence Gateway authentication contract.

Outcome: A separately checked Mint issuer and one registered-client token accepted by the completed Evidence Gateway candidate.
Time: About 30 minutes after the Evidence Gateway candidate and client registration are reviewed
Level: Production token issuance with a synthetic deployment client
Prerequisites: Released mint and evidencectl binariesA completed Evidence Gateway candidateA registered machine client and owner-only private JWKOperator-controlled HTTPS routing

Before you start

You need a completed Evidence Gateway candidate, a public HTTPS issuer name for Mint, a registered machine caller, and released mint and evidencectl binaries. Mint serves one active process in Version 1. Its client-assertion replay cache is memory-only and clears when the process restarts. Do not make a high-availability or durable replay-protection claim for this deployment shape.

Create Mint’s signing key independently from Evidence Gateway’s signing key. Strict deployments keep the non-exportable private key in Vault or OpenBao Transit and expose only a workload-local Unix socket to Mint.

Author Mint separately

Create a complete Mint target beside the Evidence Gateway target in the deployment repository:

environments/production/mint/
  mint.yaml
  clients/
    <client>.yaml
  public-keys/
    <mint-thumbprint>.jwk.json

Git contains the public service JWK and public client registrations. Keep the Mint audit HMAC key, provider token, auto-auth credentials, client private keys, and issued tokens outside Git.

Set Mint’s issuer to its public HTTPS identity. Configure its listener on a private address and let operator-controlled routing or split DNS resolve the public HTTPS issuer inside the private network. Do not replace Evidence Gateway’s issuer or JWKS URI with an internal plain-HTTP service name.

Register each client with its public JWK, reviewed principal, requester tags, evidence audience, and optional grant. Mint writes authority from this registration, never from the client’s request.

Set validationMode: strict. Configure signing.activePublicJwkFile with the exact public P-256 JWK, and configure signer.kind: transit with the workload-local socket, Transit mount, key name, pinned nonzero version, and bounded timeout. Follow Configure Transit signing for Evidence Gateway and Registry Mint to create the key, proxy identity, socket, and least-privilege policy. Mint receives no provider token or private signing key.

Check the two configurations

Start the workload-local Mint proxy, then validate Mint without opening a listener. mint check performs the provider metadata and sign-and-verify self-test, so a strict configuration fails when the proxy is unavailable:

mint check --config "<deployment-repository>/environments/production/mint/mint.yaml"

Then compare the completed Evidence Gateway candidate with Mint. This check is read-only and does not copy or modify either project:

evidencectl doctor \
  --project "<candidate>" \
  --mint-config "<deployment-repository>/environments/production/mint/mint.yaml"

The paired check compares issuer, JWKS URI, audiences, admitted algorithm and token type, plus the principal, requester-tags, evidence audience, grant-id, grant-authority, and optional actor claim names. It does not decide whether a client has legal authority, create an authority profile, or register a client.

Start Mint and obtain a token

Start Mint behind operator-controlled TLS, keeping the Mint listener private:

mint serve --config "<deployment-repository>/environments/production/mint/mint.yaml"

Route token requests only after Mint’s /ready endpoint reports ready.

Use a registered caller’s own private JWK to request one access token over the public HTTPS identity. The token is written to standard output only. Store it in an owner-only local file for the next request, never in the candidate, a fixture, a log, or a command argument.

umask 077
mint token \
  --url "https://<mint-public-host>/token" \
  --client-id "<registered-client-id>" \
  --key "<owner-only-client-private-jwk>" > "<owner-only-token-file>"

Send the token to Evidence Gateway through its real HTTPS boundary using the owner-only Curl configuration described in Build and deploy an Evidence Gateway project. That request proves the selected client-to-grant path. The paired doctor check does not.

Expected result

Mint accepts the reviewed client assertion and Evidence Gateway accepts the resulting at+jwt access token over its HTTPS boundary. Retain the Evidence Gateway response and audit verification result, not the token.

Clean up the token file

Remove the temporary token file after the synthetic deployment request. Do not retain it in a candidate, fixture, audit record, or shell history.

rm -f "<owner-only-token-file>"