Credex Deployment

This guide covers how to deploy and configure Credex.

Credex is a stateless micro-service in a SPIFFE trust domain that exposes token exchange functionality via a set of OAuth 2.0 compatible HTTP API endpoints. It serves two independent subsystems:

The OAuth Authorization Server provides a standards-based RFC 8693 Token Exchange endpoint. Clients authenticate with a SPIFFE JWT-SVID or an RFC 7523 JWT bearer assertion, and exchange one or two tokens for another. This is the primary, client-facing exchange path and is enabled by default.
The SPIFFE Token Exchange (preview) subsystem provides a lightweight POST / endpoint that accepts a JSON envelope containing a JWT and returns a JWT-SVID.

This deployment guide uses the cofide-credex Helm chart. Each subsystem can be enabled or disabled independently with the enableOAuthAS and enableSPIFFEExchange Helm chart values.

Dependencies

Credex requires the following during normal operation:

Access to the SPIFFE Workload API to obtain its own SVID and validate JWT-SVIDs presented by clients. The cofide-credex Helm chart mounts the Workload API socket via the SPIFFE CSI driver.
Access to the SPIRE server’s gRPC API for token signing. The SPIRE server must also be configured to trust Credex’s SPIFFE ID for mTLS authentication via the experimental.custom_jwt_signers section in Cofide SPIRE server config. See Additional SPIRE Configuration for the required SPIRE server configuration and Signing Keys for more details.
Access to the Cofide Connect API which serves as a centralised source of exchange policies and audit information.
The SPIFFE Token Exchange subsystem also needs access to the SPIRE Agent admin socket, which exposes the Delegation API used to mint JWT-SVIDs. See Additional SPIRE Configuration for the required SPIRE agent configuration.

Deployment

Cofide Credex is installed using the cofide-credex Helm chart.

It requires a Kubernetes cluster with a Cofide SPIRE Agent running and the SPIFFE CSI driver (csi.spiffe.io) available on each node.

A minimal Helm install pointing at a Cofide Connect control plane and in-cluster Cofide SPIRE server requires the following:

helm repo add cofide https://cofide.github.io/helm-charts --force-update
helm install cofide-credex cofide/cofide-credex \
  --namespace cofide \
  --create-namespace \
  --version 0.3.2 \
  --set credex.issuerURL=https://credex.example.org \
  --set credex.connectURL=connect.example.org:443 \
  --set credex.connectTrustDomain=example.org \
  --set credex.signing.method=spire \
  --set credex.signing.spireServerAddr=spire-server.spire-server.svc.cluster.local:443

For the full set of available configuration options and their defaults, including TLS options, see the Helm chart documentation.

TLS

TLS is critical for Credex, since it exposes token exchange endpoints that clients will call over the network.

To enable TLS, provide a Kubernetes Secret containing a PEM-encoded certificate and key under the tls.crt and tls.key keys. cert-manager is a convenient way to provision and rotate this secret automatically.

Alternatively, create the secret manually:

kubectl create secret tls credex-tls \
  --namespace cofide \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

Then enable TLS in your Helm values:

credex:
  tls:
    enabled: true
    secretName: credex-tls

When TLS is enabled, the chart automatically adjusts the Kubernetes service port from 80 to 443 and switches health probes to HTTPS.

Signing Keys

The OAuth AS subsystem signs every issued access token with a JWT signing key and publishes the corresponding verification key at /keys.

The example Helm install command above uses the spire signing method, which delegates token signing to a custom JWT signer gRPC service on the Cofide SPIRE server. Credex never sees the private signing key; it sends the claims to SPIRE over mTLS and receives the signed JWT in response.

SPIRE-backed signing inherits SPIRE’s automatic JWT signing key rotation and battle-tested CA subsystem, which is the recommended posture for production deployments.

For this mode to work, the SPIRE server configuration must include Credex’s SPIFFE ID in its experimental.custom_jwt_signers allowlist (see Dependencies).

The SPIFFE Token Exchange subsystem does not sign tokens itself: JWT-SVIDs are produced by the SPIRE server.

Trusted Issuers

The OAuth AS and SPIFFE exchange subsystems both rely on the concept of ‘trusted issuers’ to determine which external JWTs to accept (based on their iss claim and validated signature). This allows Credex to bridge identities issued outside of SPIFFE (for example by Microsoft Entra, Okta, or AWS STS) into Credex-protected or SPIFFE-protected services.

Example trusted issuer configuration via Helm values:

credex:
  trustedIssuers:
    - issuer: https://sts.windows.net/<tenant-id>/
      jwksURL: https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys
      allowedAudiences:
        - api://my-app

For each entry, the Credex OAuth AS:

Fetches and caches the issuer’s JWKS (refreshed on cache miss).
Verifies that the inbound JWT’s signature is produced by a key in that JWKS.
Verifies that the JWT’s aud claim includes either the Credex token endpoint URL or one of the entries in allowedAudiences (if configured).
Treats the JWT’s sub and iss claims as the subject identity passed to the policy engine.

For delegated exchanges, actor tokens cannot be external JWTs. Only identities already trusted by the deployment (a SPIFFE JWT-SVID, or an access token previously issued by this Credex instance) may act on behalf of a subject.

The SPIFFE exchange subsystem uses the same trusted issuers, except that the allowed audiences list is ignored (since incoming OIDC token audiences are usually the OAuth client ID of the calling workload and adding every client ID to Credex config would be impractical).