Skip to navigation

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

Use a certificate field that your CA controls and that uniquely identifies the workload. Mixlayer exposes decoded certificate attributes, so you can match a common name without parsing a distinguished name:

mixlayer.subject = assertion.subject.common_name

For a certificate with CN=production-model-client, this mapping returns production-model-client. The CN= label is not part of the value. A common name is an identity attribute, not an automatic DNS hostname check.

To use a URI SAN as the identity, select its entry from assertion.subject_alt_names. For a certificate profile that puts the URI SAN first, map mixlayer.subject from assertion.subject_alt_names[0].value and require assertion.subject_alt_names[0].type == "URI" in admission. Use a fixed, CA-controlled SAN order and adjust both indexes if needed. An exists check admits a certificate; it does not select the value used for mixlayer.subject.

Subject and issuer attributes

Both assertion.subject and assertion.issuer contain these fields:

Scalar fieldList fieldCertificate attribute
common_namecommon_namesCN, OID 2.5.4.3
organizationorganizationsO, OID 2.5.4.10
organizational_unitorganizational_unitsOU, OID 2.5.4.11
country_codecountry_codesC, OID 2.5.4.6
provinceprovincesST, OID 2.5.4.8
localitylocalitiesL, OID 2.5.4.7
street_addressstreet_addressesSTREET, OID 2.5.4.9
postal_codepostal_codesPostal code, OID 2.5.4.17

A scalar field is present only when the certificate contains exactly one occurrence of that attribute. A list field is always present and contains every occurrence in certificate order. Missing attributes have an empty list. Repeated values are not deduplicated, and Mixlayer does not choose the first or last value for an ambiguous scalar.

For example, if a certificate has two OUs, organizational_units contains both and organizational_unit is absent. Use has to check a scalar before reading it, or exists to search all occurrences:

has(assertion.subject.common_name) &&
assertion.subject.common_name == "production-model-client" &&
assertion.subject.organizational_units.exists(ou, ou == "Production")

Values preserve case and whitespace. UTF-8 and supported ASN.1 string encodings, including BMPString and UniversalString, are decoded to strings. Undecodable or non-string values use # followed by lowercase DER hex. Attributes with other OIDs are not exposed in the assertion.

Typed subject alternative names

assertion.subject_alt_names is a list in certificate order. Each entry has string fields type and value. A CUSTOM entry also has an oid field with its dotted numeric OID.

typevalue
DNSDNS name as encoded in the certificate
URIURI as encoded in the certificate, including SPIFFE IDs
EMAILRFC 822 email address
IP_ADDRESSIPv4 or IPv6 address in standard text form
CUSTOMASN.1 otherName value, decoded as a supported string or represented as # plus DER hex

Use quoted strings for SAN types; bare identifiers such as DNS are not defined. directoryName, registeredID, X.400, and EDI party SANs are not exposed in this list.

Require a DNS SAN in an allowed namespace:

assertion.subject_alt_names.exists(san,
san.type == "DNS" && san.value.endsWith(".example.com"))

Require a specific SPIFFE ID:

assertion.subject_alt_names.exists(san,
san.type == "URI" &&
san.value == "spiffe://example.com/production/model-client")

Match an otherName by OID and value:

assertion.subject_alt_names.exists(san,
san.type == "CUSTOM" &&
san.oid == "1.3.6.1.4.1.311.20.2.3" &&
san.value == "model-client@example.com")

These expressions belong in the admission condition. For an authorization rule, map a boolean first:

attribute.production = assertion.subject.organizational_units.exists(ou, ou == "Production")

Then use attribute.production == true in the rule condition. Authorization rules cannot read assertion directly. See CEL policy support for limits and other supported operations.

Certificate metadata

Mixlayer also exposes these leaf certificate facts:

AssertionValue
assertion.serial_numberLowercase unsigned hex, without DER sign padding; zero is 00
assertion.sha256_fingerprintLowercase SHA-256 hex of the complete leaf DER certificate
assertion.valid_not_beforeRFC 3339 UTC validity start, ending in Z
assertion.valid_not_afterRFC 3339 UTC validity end, ending in Z
assertion.client_cert_presenttrue, after certificate validation
assertion.client_cert_chain_verifiedtrue, after validation against the selected provider’s CAs

A fingerprint identifies one certificate and changes on renewal. Prefer a stable, CA-controlled identity when you want renewal to work without policy changes.

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.

RSA keys must be 2048 to 8192 bits. Unsupported signature or public-key algorithms, malformed or duplicate extensions, and unknown critical extensions are rejected.

Mixlayer does not fetch missing intermediates through AIA, 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.

Mixlayer does not currently support direct mTLS authentication. To authenticate using X509 certificates, you must exchange a certificate for a short-lived token as documented above. If you are interested in mTLS/client certificate authentication for the Mixlayer API and inference endpoints, reach out to us.