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.
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:
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:
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:
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.
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:
Require a specific SPIFFE ID:
Match an otherName by OID and value:
These expressions belong in the admission condition. For an authorization rule, map a boolean first:
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:
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
Console
API
Open Workload Identity, select New provider, and choose X.509.
- Enter a descriptive name.
- Add each root CA as a separate Trust anchor certificate.
- Add any intermediate CA certificates needed for chain construction.
- Map
mixlayer.subjectto the certificate identity selected above. - Add an admission condition and least-privilege fallback permissions.
- 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.
Export the client paths and provider ID:
Exchange the certificate identity
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:
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.