Credex Exchange Policies

Credex token exchanges are mediated by exchange policies; allowing fine-grained control over which exchanges are permitted and which claims the Credex-issued JWTs may contain.

This guide covers how to author and manage those policies. For the exchanges these policies govern, see Exchange Types.

OAuth Token Exchange

Every RFC 8693 token exchange is gated by the Credex policy engine. An exchange policy specifies who can exchange what, on whose behalf, and which scopes can be granted in the resulting access token.

If no policy matches an exchange request, the exchange is denied. If a policy source contains zero policies, every exchange is denied.

The Cofide Connect platform provides a centralized source for policy configuration and auditing. Policies are managed by interacting with the Connect API using either the cofidectl CLI, the Terraform provider, or by interacting directly with the Connect gRPC API.

The remainder of this guide will use cofidectl commands to manage exchange policies.

Policy structure

A Credex RFC 8693 token exchange policy is scoped to a trust zone and contains the following fields, which include both matchers for the exchange request and settings for the outbound token:

Policy Field	Field Type	Usage
name	String	Name for the policy
trust_zone_id	String	Trust zone the policy applies to; immutable after creation
subject_identity	List of string matchers	Matches the sub claim of the subject token
subject_issuer	List of string matchers	Matches the iss claim of the subject token
subject_audience	List of string matchers	Matches the aud claim of the subject token (required for ID tokens)
actor_identity	List of string matchers	Matches the sub / SPIFFE ID of the actor token (delegation flows only)
actor_issuer	List of string matchers	Matches the iss claim of the actor token
client_id	List of string matchers	Matches the identity used in the client_assertion (e.g. the calling workload’s SPIFFE ID)
target_audience	List of string matchers	Matches the audience parameter (if provided by the client)
outbound_identity	String	Overrides the sub claim of the issued token
outbound_scopes	List of strings	Caps the scopes granted on the issued token
oauth_as	Outbound OAuth config	Routes the exchange to a downstream OAuth authorization server instead of minting a token locally (allow policies only); see OAuth Bridge exchange
external_hooks	List of external hooks	Called in order to enrich the outbound token’s claims (allow policies only); see External hooks
action	String	allow or deny

A string matcher is either an exact string equality check or a glob pattern. A list of string matchers field matches if any string matcher in the list matches.

Every field of type list of string matchers except actor_identity, actor_issuer, and subject_audience must have at least one matcher. For required fields, an absent or empty field never matches, and is not a wildcard. To leave a field unconstrained, set it to a single glob:"*" matcher.

Each policy also carries read-only fields set by the server: id, org_id, created_at, and last_updated_at. See ExchangePolicy in the Connect API reference for the full message.

Allow, deny, and resolution order

All policies are evaluated against every request, not just the first match. Resolution proceeds as follows:

1. If any matching policy has action: deny, the exchange is denied immediately.
2. If any matching allow policy allows the requested scopes, the exchange is permitted.
3. Otherwise, the exchange is denied.

Deny policies are useful for revoking access for a specific identity without rewriting or reordering the broader allow set.

Actor fields and delegation

The two actor fields (actor_identity and actor_issuer) are the only fields where absence is meaningful:

• If both are absent or empty, the policy only matches exchanges without an actor token (impersonation).
• If either is present, the policy only matches exchanges with a valid actor token (delegation).

This makes it possible to write distinct policies for the impersonation and delegation cases on the same subject identity.

Outbound identity

By default, the sub claim of the issued token matches the sub claim of the subject token. The optional outbound_identity field can be used to override the sub claim of the issued token. This can be useful when a downstream resource server or authorization server expects a different subject than the one in the subject token.

If outbound_identity is non-empty, the subject_identity and subject_issuer fields must use exact string matchers only - no glob matchers are allowed. If several policies match a token exchange request, they must all have the same outbound_identity value, or an error will be returned. This ensures a predictable mapping of identities.

Policy examples

Impersonation

Allow any workload in the payments namespace to exchange a JWT-SVID for an access token targeting the payments API, with payments:read scope:

cofidectl exchange-policy add \
    --name policy-1 \
    --trust-zone example \
    --subject-identity glob:"spiffe://example.org/cluster/example-cluster/ns/payments/sa/*" \
    --subject-issuer glob:"*" \
    --client-id glob:"spiffe://example.org/cluster/example-cluster/ns/payments/sa/*" \
    --target-audience "https://payments.example.com" \
    --outbound-scope "payments:read" \
    --action allow

Delegation

Allow an agent workload to act on behalf of any user authenticated against an external IdP (a delegation flow):

cofidectl exchange-policy add \
    --name policy-2 \
    --trust-zone example \
    --subject-identity glob:"*" \
    --subject-issuer "https://login.example.com" \
    --actor-identity "spiffe://example.org/ns/agents/sa/booking-agent" \
    --actor-issuer glob:"*" \
    --client-id "spiffe://example.org/ns/agents/sa/booking-agent" \
    --target-audience "https://travel-api.example.com" \
    --outbound-scope "bookings:write" \
    --action allow

The corresponding exchange request for a delegated access token which is allowed by this policy would be:

POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-spiffe
&client_assertion=<JWT-SVID for booking-agent, aud=https://credex.example.com/token>
&subject_token=<external JWT from login.example.com>
&subject_token_type=urn:ietf:params:oauth:token-type:jwt
&actor_token=<JWT-SVID for booking-agent, aud=https://credex.example.com/token>
&actor_token_type=urn:ietf:params:oauth:token-type:jwt_spiffe
&audience=https://travel-api.example.com
&scope=bookings:write

with a subject JWT containing claims such as:

{
  "iss": "https://login.example.com",
  "sub": "user-12345",
  "aud": "https://credex.example.com/token",
  "exp": 1796000600,
  "iat": 1796000000,
  "email": "[email protected]",
  "name": "Alice Example"
}

and actor JWT-SVID claims such as:

{
  "sub": "spiffe://example.org/ns/agents/sa/booking-agent",
  "aud": ["https://credex.example.com/token"],
  "exp": 1796000300,
  "iat": 1796000000
}

The resulting token issued by Credex would include the following claims structure:

{
  "iss": "https://credex.example.com",
  "sub": "user-12345",
  "act": {
    "sub": "spiffe://example.org/ns/agents/sa/booking-agent"
  },
  "aud": "https://travel-api.example.com",
  "exp": 1796000700,
  "iat": 1796000100
}

When this Credex-issued token is later sent to the service at https://travel-api.example.com, both the request subject (i.e. user-12345) and the request actor (i.e. the booking-agent) can be used for authorization decisions and clear audit trails.

External hooks

An allow policy may optionally specify one or more external hooks. When Credex matches a policy with hooks, it calls each hook endpoint in sequence after evaluating the policy and before minting the token. Each hook can add, remove, or replace custom claims on the outbound token using a JSON Patch (RFC 6902), making it possible to enrich tokens with metadata that Credex does not hold directly.

Request and response

For each hook, Credex sends a POST request with Content-Type: application/json and a body containing the following fields:

Field	Required	Description
subject_claims	Yes	Claims from the subject token being exchanged
actor_claims	No	Claims from the actor token, present only in delegation exchanges
outbound_claims	Yes	The full set of claims that will appear in the issued token, including sub, aud, and scope

The hook must return HTTP 200 with a body containing:

Field	Required	Description
action	No	Must be either allow or deny (default: allow). Denial rejects the token exchange and prevents any subsequent hooks from running for the request.
action_reason	No	Optional message to complement action. Action reason is returned as a user-facing error message when action is deny.
claims_patch	No	A JSON Patch (RFC 6902) array to apply to the outbound token’s claims

Protected claims

The following claims are protected and any attempt by a hook to modify them will result in an error and the exchange being rejected: iss, sub, aud, exp, nbf, iat, jti, scope, client_id, act.

Error handling

If a hook returns a non-200 status code, exceeds its configured timeout (default: 3 seconds), or returns a body that does not conform to the expected schema, Credex rejects the exchange. Credex retries the hook once on a transient network error before failing.

Configuring hooks

Hooks can be configured using the Terraform provider or the cofidectl CLI. Each hook accepts the following fields:

Required fields:

Field	Description
name	Identifier for the hook, used in error messages
url	HTTPS endpoint URL of the hook server
auth	Authentication configuration; exactly one variant must be set (see below)

Optional fields:

Field	Description
description	Human-readable description of the hook’s purpose
timeout	Per-request timeout; seconds in Terraform, a Go duration string (e.g. 5s) in cofidectl (default: 3 seconds)

The only supported auth variant is spiffe_mtls, which requires the SPIFFE ID of the hook server. Credex presents its own X.509-SVID and verifies that the hook server presents a certificate matching that SPIFFE ID. The hook server must be a SPIFFE workload reachable by Credex.

Example

The following Terraform resource defines the impersonation policy above extended with a hook that adds the workload’s team and cost centre to the issued token.

resource "cofide_connect_exchange_policy" "policy_with_hook" {
  name             = "policy-with-hook"
  trust_zone_id    = cofide_connect_trust_zone.example.id
  action           = "ALLOW"
  subject_identity = [{ glob = "spiffe://example.org/cluster/example-cluster/ns/payments/sa/*" }]
  subject_issuer   = [{ glob = "*" }]
  client_id        = [{ glob = "spiffe://example.org/cluster/example-cluster/ns/payments/sa/*" }]
  target_audience  = [{ exact = "https://payments.example.com" }]
  outbound_scopes  = ["payments:read"]
  external_hooks   = [
    {
      name    = "workload-directory"
      url     = "https://directory.internal/hooks/claims"
      timeout = 5
      auth = {
        spiffe_mtls = {
          spiffe_id = "spiffe://example.org/ns/directory/sa/claims-hook"
        }
      }
    }
  ]
}

When this policy matches an exchange request, Credex calls the hook with:

{
  "subject_claims": {
    "sub": "spiffe://example.org/cluster/example-cluster/ns/payments/sa/checkout",
    "aud": ["https://credex.example.com/token"],
    "exp": 1796000300,
    "iat": 1796000000
  },
  "outbound_claims": {
    "sub": "spiffe://example.org/cluster/example-cluster/ns/payments/sa/checkout",
    "aud": "https://payments.example.com",
    "scope": "payments:read",
    "client_id": "spiffe://example.org/cluster/example-cluster/ns/payments/sa/checkout"
  }
}

The hook looks up the workload by subject_claims.sub and responds with:

{
  "claims_patch": [
    { "op": "add", "path": "/department", "value": "engineering" },
    { "op": "add", "path": "/cost_centre", "value": "CC-42" }
  ]
}

The resulting token issued by Credex includes the enriched claims:

{
  "iss": "https://credex.example.com",
  "sub": "spiffe://example.org/cluster/example-cluster/ns/payments/sa/checkout",
  "aud": "https://payments.example.com",
  "scope": "payments:read",
  "department": "engineering",
  "cost_centre": "CC-42",
  "exp": 1796000700,
  "iat": 1796000100
}

The credex-policy-hook-reference repository contains an example hook demonstrating the request and response schema required by Credex as well as the SPIFFE mTLS configuration to enable secure communication between Credex and the external hook.

OAuth Bridge exchange

By default, a matching allow policy causes Credex to mint the issued token itself. Setting the policy’s oauth_as field changes this: instead of minting a token, Credex obtains one from a downstream OAuth authorization server and returns it to the caller verbatim.

For the use case this exchange addresses, see Federating to a legacy OAuth authorization server on the Use Cases page. For the caller’s side of this exchange and how Credex authenticates to the downstream server, see OAuth Bridge exchange on the Exchange Types page.

The client assertion’s sub identifies the client in the downstream authorization server, and is equal to the resolved outbound identity for the exchange. The caller does not need to hold a SPIFFE SVID: a policy can match an external JWT or OIDC ID token from a trusted issuer just as it can match a JWT-SVID, and the bridge behaves the same way in both cases.

Fields

The oauth_as message accepts the following fields (see OutboundOAuthAS in the Connect API reference for the full schema):

Field	Required	Description
grant_type	Yes	Must be client_credentials, the only grant type supported for outbound exchanges.
issuer_url	If no token_url	Issuer URL of the downstream authorization server. The token endpoint is discovered via RFC 8414 / OIDC discovery and cached for 24 hours.
token_url	If no issuer_url	Token endpoint URL of the downstream authorization server. Bypasses discovery.
audiences	No	Audience values included in the JWT client assertion. Defaults to the token endpoint URL.
timeout	No	Timeout for the outbound call to the downstream authorization server. Defaults to 10 seconds.

At least one of issuer_url or token_url must be set. If both are set, token_url is used and issuer_url is ignored.

Validation rules

• oauth_as is only valid on allow policies.
• oauth_as cannot be combined with external_hooks on the same policy.

If several allow policies match a request, they must all agree on oauth_as. If some matching policies set it and others do not, or matching policies set structurally different values, the exchange is rejected as ambiguous.

Example

Allow a workload in the prod namespace to exchange its JWT-SVID for a token minted by a downstream authorization server, targeting downstream-service with read scope:

cofidectl exchange-policy add \
    --name policy-bridge \
    --trust-zone example \
    --subject-identity "spiffe://example.org/cluster/example-cluster/ns/prod/sa/my-service" \
    --subject-issuer glob:"*" \
    --client-id "spiffe://example.org/cluster/example-cluster/ns/prod/sa/my-service" \
    --target-audience "downstream-service" \
    --outbound-scope "read" \
    --outbound-oauth-as '{"grant_type":"client_credentials","issuer_url":"https://downstream-as.example.com","audiences":["https://downstream-as.example.com/token"]}' \
    --action allow

The --outbound-oauth-as flag sets the policy’s oauth_as field. It accepts the configuration as inline JSON, or as file://<path> to a JSON file with the same fields.

When a request matches this policy, Credex performs a client_credentials exchange against https://downstream-as.example.com, authenticating with a signed JWT assertion whose sub is the workload’s SPIFFE ID, and returns the downstream token to the caller. For a caller that is not SPIFFE-attested, set --subject-identity and --subject-issuer to match the external token’s sub and iss instead, and the assertion’s sub will be that subject identity. The corresponding exchange request is shown under OAuth Bridge exchange on the Exchange Types page.

OIDC to SPIFFE (Preview)

For OIDC to SPIFFE exchanges, Credex enforces which inbound identities may obtain which SPIFFE IDs entirely through SPIRE registration entries, rather than using Cofide ExchangePolicy resources.

A request is granted or denied based solely on whether SPIRE finds a matching registration entry for the selectors Credex presents.

The recommended approach is to use static attestation policies to manage the registration entries. Each entry binds a specific (issuer, subject) pair to a SPIFFE ID and must be parented to Credex’s SPIFFE ID — this links the entry to Credex’s delegated authority.

For example:

# Create an attestation policy with the Credex selectors
cofidectl attestation-policy add static \
    --name aws-my-workload \
    --selectors credex:oidc:issuer:https://sts.amazonaws.com \
    --selectors credex:oidc:claims:sub:arn:aws:sts::012345678910:assumed-role/MyRole/session \
    --parent-id-path cluster/<cluster-name>/ns/cofide/sa/cofide-credex \
    --spiffe-id-path remote/cloud/aws/my-workload

# Bind the policy to the target trust zone
cofidectl attestation-policy-binding add \
    --trust-zone local \
    --attestation-policy aws-my-workload

Replace <cluster-name> with the name of the cluster on which Credex is running (hint: see cofidectl cluster list).

To allow all subjects from a trusted issuer to obtain the same SPIFFE ID, omit the credex:oidc:claims:sub selector — but this is rarely advisable in production.

If no registration entry matches the presented selectors, SPIRE rejects the request and Credex returns an error to the caller. Adding a trusted issuer to the environment variables is therefore not sufficient on its own: at least one matching SPIRE registration entry must also exist before any exchange will succeed. If the parent ID does not match Credex’s SPIFFE ID, SPIRE will also reject the call even if the selectors match.