Workload Identity with SPIFFE

Concepts

The end-to-end model is:

1. Your SPIRE deployment is the authority for a trust domain and issues SVIDs to your workloads.
2. You publish that trust domain's bundle at an HTTPS endpoint.
3. You create a MonoCloud trust store pointing at that endpoint, which federates the trust domain.
4. You associate SPIFFE IDs with the MonoCloud clients those workloads should act as.
5. Workloads request access tokens by presenting their SVIDs at the token endpoint.

Providing the trust bundle

Before MonoCloud can verify your workloads' SVIDs, it needs your trust domain's bundle. MonoCloud retrieves the bundle by performing an HTTPS GET against a bundle endpoint URL that you supply.

MonoCloud fetches the bundle when you create the trust store, then refreshes it according to the bundle's refresh hint and MonoCloud's cache rules. Authentication uses the current cached bundle. If MonoCloud needs to refresh the bundle and the endpoint cannot be reached within the configured timeout, authentication is rejected.

There are two common ways to expose your SPIRE trust domain's bundle to MonoCloud. Both result in a single HTTPS URL that you paste into the trust store.

**MonoCloud validates the bundle endpoint's TLS certificate against the public web PKI. If you expose a SPIRE bundle endpoint directly, configure SPIRE to serve it using its https_web profile, with a certificate from a publicly trusted CA. The https_spiffe profile, where the endpoint's TLS certificate is itself an SVID, is not supported.

A trust bundle contains public verification material, not workload private keys. It must be integrity-protected and served over HTTPS, but it does not need to be confidential.

Creating a trust store

A trust store federates one trust domain. Creating one tells MonoCloud to fetch and trust SVIDs issued by that domain.

Associating SPIFFE IDs with a client

A trust store tells MonoCloud which SVIDs are authentic. It does not, by itself, specify which client a workload may authenticate as.

You make that association by adding a secret to the client whose value is the workload's SPIFFE ID. The client is what the access token is issued for, the SPIFFE ID secret is how the workload proves it may act as that client.

There is one secret type per SVID format. Both take a SPIFFE ID as their value and both require the Workload Identity add-on:

To add one in the dashboard:

1. Open the client under Applications and find the Secrets section.
2. Click Add Secret.
3. For Secret Type, choose SPIFFE ID (X.509-SVID) or SPIFFE ID (JWT-SVID), depending on how the workload will authenticate.
4. Enter the workload's SPIFFE ID as the value and save.

A client can hold several SPIFFE ID secrets. You can add secrets of both types to the same client if it uses both flows.

The value can match either an exact identity or a path prefix using a trailing /* wildcard:

• spiffe://example.org/ns/billing/sa/worker matches only that exact workload.
• spiffe://example.org/ns/billing/* matches workloads below that path, such as spiffe://example.org/ns/billing/sa/worker.

At authentication time, MonoCloud compares the SPIFFE ID from the presented SVID against the client's SPIFFE ID secrets of the matching type. If none match, authentication fails.

Workload Identity applies to both application and agent clients, so either client type can authenticate with an SVID.

If you omit client_id on the JWT SVID flow, MonoCloud finds the client by looking up which client holds a matching SPIFFE ID (JWT-SVID) secret. Each SPIFFE ID should normally be associated with a single client. See Requesting tokens with JWT SVIDs.

Requesting tokens with X.509 SVIDs

In this flow the workload presents its X.509 SVID as the client certificate over mutual TLS to MonoCloud's mTLS token endpoint.

Find the correct endpoint in your tenant's OpenID Connect discovery document. For the default trust store, use the corresponding token_endpoint value in mtls_endpoint_aliases. For an additional trust store, use the corresponding endpoint from MonoCloud's mtls_additional_endpoint_aliases extension.

This flow is normally combined with the client_credentials grant for service-to-service access.

curl -X POST https://{tenant}.{region}.mtls.monocloud.com/connect/token \
  --cert svid.pem \
  --key  svid.key \
  -d grant_type=client_credentials \
  -d client_id=billing-worker \
  -d scope=billing \
  -d resource=https://api.example.com/billing

You can include client_id to select a specific client. It is optional when the SPIFFE ID maps to exactly one client, but required when the same SPIFFE ID is associated with more than one client.

The client_id is required in this flow. The SVID is presented at the TLS layer, while client_id tells MonoCloud which client to issue the token for.

MonoCloud verifies the SVID against the matching trust store before issuing a token. It checks that:

• the certificate is a leaf certificate and not a CA,
• it has exactly one URI SAN, and that URI is a valid workload SPIFFE ID with a non-root path,
• the SPIFFE ID's trust domain matches the trust store's trust domain,
• the certificate chains to the trust domain's x509-svid authorities from the bundle - either directly, or through one or more intermediate CAs the workload presents alongside the leaf,
• the leaf's key usage and the validity period of every certificate in the chain satisfy the trust store's validation settings, and
• the SPIFFE ID is not banned.

MonoCloud then confirms that the SPIFFE ID matches one of the client's SPIFFE ID (X.509-SVID) secrets.

On success, MonoCloud issues an access token that is bound to the certificate used on the TLS connection through the cnf claim. See Proof of possession.

Requesting tokens with JWT SVIDs

In this flow, the workload obtains a JWT SVID through its SPIFFE Workload API and presents it as a client assertion on a regular, non-mTLS request to the token endpoint.

Find the token endpoint in your tenant's OpenID Connect discovery document.

First request a JWT SVID with MonoCloud's issuer URL as its audience:

SVID_JWT=$(spire-agent api fetch jwt \
  -audience https://{tenant}.{region}.monocloud.com \
  -socketPath /run/spire/sockets/agent.sock \
  -output json | jq -r '.svids[0].svid')

Then present that SVID as the client assertion:

curl -X POST https://{tenant}.{region}.monocloud.com/connect/token \
  -d grant_type=client_credentials \
  -d scope=billing \
  -d resource=https://api.example.com/billing \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-spiffe \
  -d client_assertion="$SVID_JWT"

The single most important requirement is the audience:

A JWT SVID used to authenticate to MonoCloud must have an aud claim equal to your tenant's issuer URL, and that must be its only audience. This is stricter than private_key_jwt. A JWT SVID whose audience is the token endpoint, or that carries any additional audience, is rejected. Take the issuer value from your tenant's OpenID configuration.

A JWT SVID is a standard SPIFFE JWT with the workload's SPIFFE ID as its sub:

{
  "sub": "spiffe://example.org/ns/billing/sa/worker",
  "aud": "https://{tenant}.{region}.monocloud.com",
  "exp": 1735689600
}

MonoCloud:

• resolves the trust domain from the SPIFFE ID in sub and looks up the matching trust store,
• verifies the assertion's signature against that trust domain's jwt-svid authorities,
• requires a signed token with an expiry and a supported algorithm: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, or ES512,
• requires sub to be a valid workload SPIFFE ID with a non-root path,
• rejects the SVID if it is banned, and
• confirms the SPIFFE ID matches one of the client's SPIFFE ID (JWT-SVID) secrets.

client_id is optional on this flow.

If you omit it, MonoCloud resolves the client from the SPIFFE ID in sub. If more than one client is associated with that SPIFFE ID the request is ambiguous and you must send client_id to disambiguate.

Access tokens issued through the JWT SVID flow are bearer tokens associated with the client. They are not key-bound and carry no cnf claim. Use the X.509 SVID flow when you need proof-of-possession, sender-constrained tokens.

Proof of possession and the cnf claim

When MonoCloud issues a token through the X.509 SVID flow, it binds the token to the client certificate used on the TLS connection, following RFC 8705 (OAuth 2.0 Mutual-TLS).

The token carries a confirmation (cnf) claim containing the SHA-256 thumbprint of that certificate:

{
  "iss": "https://{tenant}.{region}.monocloud.com",
  "client_id": "billing-worker",
  "aud": "https://api.example.com/billing",
  ...
  "cnf": {
    "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
  }
}

The same cnf claim is returned for the token at the introspection endpoint, so resource servers that use reference (opaque) tokens can retrieve it.

Certificate-bound tokens are issued only through the mTLS token endpoint.

Using SPIFFE identity in API access policies

Once a workload authenticates with an SVID, its SPIFFE identity is available to API Access Policies, so you can authorize token issuance based on workload identity, not just the client.

For requests authenticated with either SVID format, the workload's SPIFFE ID is exposed as context.spiffe_id:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context has spiffe_id &&
  context.spiffe_id == "spiffe://example.org/ns/billing/sa/worker"
};

For X.509 SVIDs, which authenticate over mTLS, you can additionally match on the certificate that was validated, including the trust store that validated it and the SPIFFE ID in its URI SAN:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context has certificate &&
  context.certificate.san_uris.contains("spiffe://example.org/ns/billing/sa/worker")
};

context.spiffe_id and context.certificate are optional, so guard them with context has .... See the API Access Policies guide for the complete context reference.

Troubleshooting

• The bundle endpoint could not be reached: MonoCloud must be able to reach the endpoint over HTTPS within the trust store's Bundle Fetch Timeout when it needs to fetch or refresh the bundle. Confirm that the URL is publicly reachable and served with a publicly trusted TLS certificate. MonoCloud validates the endpoint against the web PKI and does not support the https_spiffe profile.
• The SPIFFE bundle could not be parsed or the trust domain could not be determined: The endpoint must return a SPIFFE bundle encoded as a JWK Set and must contain the trust domain's X.509 authorities. MonoCloud reads the trust domain from those certificates' spiffe:// URI SAN. Publish with SPIRE's spiffe format, not the PEM format.
• 402 Payment Required when creating a trust store or credential: The Workload Identity add-on is required for trust stores and SPIFFE credentials. Reaching your trust-store quota also returns 402; the limit is governed by your add-on quantity.
• A trust store with that trust domain already exists: Each trust domain can be federated only once per tenant.
• X.509 SVID rejected: Check that the SVID is a leaf certificate with exactly one URI SAN that is a workload SPIFFE ID, that its trust domain matches the trust store, that it chains to the bundle's x509-svid authorities, and that it satisfies Validate Certificate Use and Validate Certificate Expiry. Also confirm that the client has a matching SPIFFE ID (X.509-SVID) secret and that the SPIFFE ID is not banned.
• X.509 SVID rejected with a chain error in nested SPIRE: The workload must present its complete SVID chain, the leaf followed by every intermediate CA. Every certificate in the chain must be valid. Presenting only the leaf, omitting an intermediate, or presenting an expired intermediate prevents chain building. Keep only the root in the bundle. See Nested SPIRE and SVID chains.
• JWT SVID rejected for audience: The assertion's aud must be exactly your tenant's issuer URL and nothing else. An audience set to the token endpoint, or any extra audience, fails validation.
• JWT SVID request is ambiguous: More than one client is associated with the SPIFFE ID in sub. Send an explicit client_id to select the client.
• Workload authenticated but no token was issued: Authentication and authorization are separate. Even after a valid SVID, an API Access Policy must still permit issuing the token for the requested API. Check the policies configured for that API.