Credex Deployment

This guide covers how to deploy and configure Credex.

Note

Before deploying Credex, you must be granted access to the Cofide container image repository. Please contact the Cofide team to arrange access.

Credex is an OAuth 2.0 Authorization Server which provides a standards-based RFC 8693 Token Exchange endpoint. It is a stateless micro-service in a SPIFFE trust domain that exposes a set of OAuth 2.0 compatible HTTP API endpoints. Clients authenticate with a SPIFFE JWT-SVID or an RFC 7523 JWT bearer assertion, and exchange one or two tokens for another.

In addition to OAuth token exchange, Credex also provides optional OIDC to SPIFFE exchange functionality (see use cases) which allows workloads to obtain a SPIFFE JWT-SVID rather than an OAuth access token.

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. 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 centralized source of exchange policies and audit information.

• The OIDC to SPIFFE exchange functionality 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.9.2 \
  --set credex.issuerURL=https://credex.example.org \
  --set credex.connectMTLSGRPCTarget=connect.example.org:443 \
  --set credex.connectSPIFFEID=spiffe://example.org/ns/connect/sa/cofide-connect-api \
  --set credex.signing.method=spire \
  --set credex.signing.spireServerAddr=spire-server.spire-server.svc.cluster.local:443

To enable the optional OIDC to SPIFFE exchange functionality, ensure the appropriate dependencies are satisfied, then add --set credex.enableSPIFFEExchange=true to the above command.

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 signs every Credex-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 OIDC to SPIFFE token exchange path does not sign tokens itself: JWT-SVIDs are produced and signed by the SPIRE server.

Trusted Issuers

Credex relies 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.

Monitoring and Observability

See Monitoring for details.