Skip to navigation
AuthenticationWorkload Identity Federation

X.509 Workload Identity

X.509 workload identity federation exchanges a verified client-certificate identity for a short-lived Mixlayer access token. The certificate is required only for the exchange; use the returned bearer token for subsequent Mixlayer API requests.

Before you begin

You need:

  • A root CA certificate in PEM format.
  • Any intermediate CA certificates needed to build the chain.
  • A client certificate and its private key on the workload.
  • Permission to manage workload identity providers in your Mixlayer organization.

Keep the private key on the workload. Mixlayer provider configuration contains public CA certificates only.

Certificate materialPurpose
Trust anchorRoot CA that Mixlayer trusts for this provider
Intermediate CABuilds a path from the client certificate to a trust anchor; it is not trusted as a root
Client certificateIdentifies the workload and is presented during token exchange
Private keyProves possession of the client certificate; never upload it to Mixlayer

Choose the workload identity

Mixlayer derives these assertion fields from the verified leaf certificate:

AssertionValue
assertion.subject_dnCertificate subject distinguished name
assertion.issuer_dnCertificate issuer distinguished name
assertion.serial_numberLowercase hexadecimal serial number
assertion.sha256_fingerprintLowercase SHA-256 fingerprint
assertion.valid_not_beforeRFC 3339 validity start
assertion.valid_not_afterRFC 3339 validity end
assertion.uri_sansURI subject alternative names
assertion.dns_sansDNS subject alternative names

Prefer a stable URI SAN issued by a controlled certificate profile. A fingerprint identifies one certificate and therefore requires a policy update whenever that certificate is renewed.

The following policy assumes each client certificate contains one URI SAN:

mixlayer.subject = assertion.uri_sans[0]

Restrict admission to the expected workload:

mixlayer.subject == "spiffe://example.com/production/model-client"

Use a final authorization rule such as:

{
  "condition": "true",
  "permissions": ["inference"]
}

Create the provider

Open Workload Identity, select New provider, and choose X.509.

  1. Enter a descriptive name.
  2. Add each root CA as a separate Trust anchor certificate.
  3. Add any intermediate CA certificates needed for chain construction.
  4. Map mixlayer.subject to the certificate identity selected above.
  5. Add an admission condition and least-privilege fallback permissions.
  6. Create the provider and record its wi_... provider ID.

Add one PEM certificate per field. Do not include a private key or concatenate unrelated roots into one field.

Present the certificate chain

The certificate file passed by the workload should contain the leaf certificate first, followed by its intermediate chain. Do not include the root certificate.

-----BEGIN CERTIFICATE-----
...leaf client certificate...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...intermediate CA certificate...
-----END CERTIFICATE-----

Export the client paths and provider ID:

export MIXLAYER_IDENTITY_PROVIDER_ID="wi_..."
export MIXLAYER_CLIENT_CERT="/run/secrets/mixlayer/client-chain.pem"
export MIXLAYER_CLIENT_KEY="/run/secrets/mixlayer/client-key.pem"

Exchange the certificate identity

file=exchange-x509-workload-identity.sh
MIXLAYER_ACCESS_TOKEN=$(
  jq -n \
    --arg provider "$MIXLAYER_IDENTITY_PROVIDER_ID" \
    '{
      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
      subject_token_type: "urn:mixlayer:params:oauth:token-type:mtls-x509",
      identity_provider_id: $provider
    }' |
  curl --fail-with-body --silent --show-error \
    --cert "$MIXLAYER_CLIENT_CERT" \
    --key "$MIXLAYER_CLIENT_KEY" \
    https://api.mixlayer.com/v1/workload_identity/token \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -er .access_token
)

The JSON body does not contain a subject_token; the client certificate is the external credential.

Use the resulting token with the normal bearer header. You do not need to send the client certificate again:

curl https://mixlayer.ai/v1/models \
  -H "Authorization: Bearer $MIXLAYER_ACCESS_TOKEN"

Certificate requirements and rotation

Mixlayer validates the certificate path, CA constraints, validity period, and client-authentication usages. The leaf must not be a CA. If Key Usage is present it must allow digital signatures; if Extended Key Usage is present it must allow client authentication.

Mixlayer does not fetch certificate revocation lists or perform OCSP checks. Use short-lived client certificates and deactivate the provider or remove a compromised trust anchor when revocation is required.

During CA rotation, configure both old and new trust anchors before issuing certificates from the new CA. Remove the old anchor after every workload has rotated. The Mixlayer access token expires after at most one hour and never outlives the client certificate.