Credex Usage

This guide covers how to use Credex as a policy-backed credential broker to bridge OAuth and SPIFFE systems across one or more trust domains.

HTTP API

The Credex HTTP API surface is summarised in the following table:

Method	Path	Description
POST	/	SPIFFE Token Exchange
POST	/token	OAuth AS token exchange (RFC 8693)
GET	/.well-known/openid-configuration	OIDC provider metadata
GET	/.well-known/oauth-authorization-server	OAuth AS metadata (RFC 8414)
GET	/keys	JWKS for verifying issued tokens
GET	/health	Liveness/readiness probe

Exchange Types

Credex is a flexible security token service which can be used for various purposes.

The type of token exchange performed is determined by request parameters in a given exchange request, such as which tokens the client presents and which it omits.

Broadly speaking, the use cases for Credex can be broken down into three different exchange types based on their semantics and intended use cases:

• Impersonation exchanges
• Delegation exchanges
• OIDC to SPIFFE exchanges.

Impersonation

An RFC 8693-compliant request where the client presents a subject token and no actor token, and receives an access token that carries only the subject’s identity.

This is appropriate when the calling workload is genuinely the principal: there is no separate user or upstream identity to preserve.

sequenceDiagram
    participant W as Workload
    participant C as Credex
    participant S as Downstream service

    W->>C: POST /token (client_assertion, subject_token, audience, scope)
    C->>C: Validate client and subject token
    C->>C: Evaluate policy and grant scopes
    C-->>W: access_token { sub: workload }
    W->>S: Authorization: Bearer access_token
    S->>S: sub = workload

In this scenario, the workload presents its own JWT-SVID as both client_assertion and subject_token. For example:

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, aud=https://credex.example.com/token>
&subject_token=<JWT-SVID, aud=https://credex.example.com/token>
&subject_token_type=urn:ietf:params:oauth:token-type:jwt_spiffe
&audience=https://api.example.com
&scope=data:read

and the response would include a token with a sub claim but no act claim:

{
  "iss": "https://credex.example.com",
  "sub": "spiffe://example.com/<workload-identifier>",
  "aud": "https://api.example.com",
  "exp": 1796000600,
  "iat": 1796000000
}

The resulting token would then be used to authenticate to https://api.example.com, assuming the API is configured to trust Credex-issued tokens.

Delegation

Similar to the impersonation request, except that the client presents both a subject token (the principal on whose behalf the exchange is happening) and an actor token (the workload performing the action). The issued access token preserves both identities: the subject in sub and the actor in a nested act claim.

sequenceDiagram
    participant A as Agent workload
    participant C as Credex
    participant S as Downstream service

    A->>C: POST /token (subject_token, actor_token, client_assertion, audience, scope)
    C->>C: Validate subject and actor tokens
    C->>C: Evaluate delegation policy
    C-->>A: access_token { sub: user, act: { sub: agent } }
    A->>S: Authorization: Bearer access_token
    S->>S: sub = user, act.sub = agent

In the above diagram, the Agent workload holds the subject token (user OIDC token or upstream AS access token) and its own JWT-SVID (used as both client_assertion and actor_token)

Delegation is the right choice whenever the calling workload is acting on behalf of someone else, for example an agent acting on behalf of a user, or a service-bus consumer acting on behalf of a publisher. Downstream services can inspect both claims to apply identity-aware audit logging and authorisation decisions.

If the subject token itself already carries an act claim (e.g. it was issued by Credex in a previous delegation hop), Credex nests the previous actor inside the new actor claim, preserving the entire chain.

In this scenario, the agent workload presents the subject token (e.g. a user OIDC token) as subject_token and its own JWT-SVID as both client_assertion and actor_token. For example:

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 agent, aud=https://credex.example.com/token>
&subject_token=<OIDC ID token from trusted IdP>
&subject_token_type=urn:ietf:params:oauth:token-type:jwt
&actor_token=<JWT-SVID for agent, aud=https://credex.example.com/token>
&actor_token_type=urn:ietf:params:oauth:token-type:jwt_spiffe
&audience=https://api.example.com
&scope=data:read

and the response would include a token with both a sub claim (the delegated subject) and an act claim (the agent):

{
  "iss": "https://credex.example.com",
  "sub": "user-12345",
  "act": {
    "sub": "spiffe://example.com/<agent-identifier>"
  },
  "aud": "https://api.example.com",
  "exp": 1796000600,
  "iat": 1796000000
}

The resulting token would then be used to authenticate to https://api.example.com, which can use both sub and act.sub for authorisation decisions and audit logging.

OIDC to SPIFFE (Preview)

An OIDC to SPIFFE exchange involves sending a request containing an OIDC ID token signed by a trusted issuer and receiving a JWT-SVID signed by the SPIRE server in response.

This allows non-SPIFFE-native workloads or those running in an environment where SPIFFE Workload API access is not available (e.g. ‘serverless’ workloads such as GitHub Actions or AWS Lambda functions) to obtain SVIDs which are trusted by other SPIFFE-native systems.

An OIDC to SPIFFE exchange requires Credex’s SPIFFE Token Exchange subsystem to be enabled (see Deployment).

The exchange request format is

POST /
Content-Type: application/json

{
  "InboundToken": "<OIDC JWT string>"
}

and the response format is

{
  "status": "ok",
  "token": "<JWT-SVID string>"
}

This functionality is under active development; the request and response formats may change in the near future.

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.

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 centralised 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 contains the following fields which are matched against inputs derived from the exchange request:

Policy Field	Field Type	Matcher Source
subject_identity	List of string matchers	sub claim of the subject token
subject_issuer	List of string matchers	iss claim of the subject token
subject_audience	List of string matchers	aud claim of the subject token (required for ID tokens)
actor_identity	List of string matchers	sub / SPIFFE ID of the actor token (delegation flows only)
actor_issuer	List of string matchers	iss claim of the actor token
client_id	List of string matchers	The identity used in the client_assertion (e.g. the calling workload’s SPIFFE ID)
target_audience	List of string matchers	The audience parameter (if provided by the client)
outbound_scopes	List of strings	Caps the scopes granted on the issued token
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.

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.

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 authorisation decisions and clear audit trails.

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.

Reference

OAuth AS Token Types

The Credex OAuth Token Exchange subsystem accepts various token types for each request parameter.

The client_assertion_type parameter must be one of:

• urn:ietf:params:oauth:client-assertion-type:jwt-spiffe - SPIFFE client authentication
• urn:ietf:params:oauth:client-assertion-type:jwt-bearer - RFC 7523

Note

The SPIFFE client-assertion-type uses a hyphen to match the current SPIFFE client authentication draft specification, whereas the token-type parameters below use an underscore to match IETF naming conventions.

The subject_token_type must be one of:

• urn:ietf:params:oauth:token-type:jwt - a JWT from an external trusted issuer, similar to an RFC 7523 JWT Bearer Authorization Grant.
• urn:ietf:params:oauth:token-type:jwt_spiffe - a SPIFFE JWT-SVID.
• urn:ietf:params:oauth:token-type:access_token - an OAuth access token previously issued by Credex.
• urn:ietf:params:oauth:token-type:id_token - an OIDC ID token from an external trusted issuer.

The actor_token_type must be one of:

• urn:ietf:params:oauth:token-type:jwt_spiffe - a SPIFFE JWT-SVID.
• urn:ietf:params:oauth:token-type:access_token - an OAuth access token previously issued by Credex.

RFC 8693 also supports an optional requested_token_type parameter; however, Credex currently only supports a value of urn:ietf:params:oauth:token-type:access_token if the parameter is included (though this may change in future).

Similarly, the issued_token_type field in the response will be set to urn:ietf:params:oauth:token-type:access_token in all responses.

Token Audience Requirements

The required aud claim varies depending on the role a token plays in the exchange request. The URN prefixes have been removed from the following tables for brevity.

Client assertion

The audience requirement for the client_assertion depends on its type:

client_assertion_type	Required aud
jwt-spiffe (JWT-SVID)	Credex token endpoint URL
jwt-bearer (external JWT)	Credex token endpoint URL, or one of the allowed audiences configured for the issuer via TRUSTED_ISSUER_ALLOWED_AUDIENCES_n

For jwt-bearer, Credex follows the audience requirements in RFC 7523 for JWT bearer client authentication which state that the audience must identify the authorization server (i.e. Credex). Since some OAuth AS implementations do not allow requesting a specific audience, the TRUSTED_ISSUER_ALLOWED_AUDIENCES_n configuration may be used as a workaround for accepting audiences other than the Credex token endpoint URL.

Subject token

The audience requirement for the subject_token depends on its type:

subject_token_type	Required aud
access_token (Credex-issued)	Any
jwt (external JWT)	Credex token endpoint URL, or one of the allowed audiences configured for the issuer via TRUSTED_ISSUER_ALLOWED_AUDIENCES_n
id_token (OIDC ID token)	Credex token endpoint URL, or the subject_audience policy field
jwt_spiffe (JWT-SVID)	Any

The distinction between jwt and id_token is subtle. For jwt, Credex follows the audience requirements in RFC 7523 for JWT bearer authorization grants: the audience must identify the authorization server. The per-trusted issuer allowed audiences configuration allows for accepting audiences other than the AS token endpoint URL.

For id_token, Credex follows the audience requirements in the OpenID Connect Core 1.0 specification: the audience identifies the Relying Party that requested the ID token from the issuer (typically an IdP). This is likely to vary for each client, so a policy-driven approach is used.

Note that for clients using an ID token both as a subject ID token and JWT bearer client assertion, both TRUSTED_ISSUER_ALLOWED_AUDIENCES_n and subject_audience will need to be set if the audience is not the AS token endpoint URL.

Actor token

Actor tokens must always be bound to the Credex token endpoint:

actor_token_type	Required aud
access_token (AS-issued)	Credex token endpoint URL
jwt_spiffe (JWT-SVID)	Credex token endpoint URL