Authentication¶
Workloads support six authentication methods. Select the method that best matches your environment and identity infrastructure. Where possible, prefer credential-less methods — they eliminate static secrets and remove a class of credential management overhead.
client_secret¶
The Workload authenticates using a Client ID and Client Secret pair — similar to a username and password. This is the simplest method but requires credential management.
| Field | Description |
|---|---|
| Client ID | Generated by the platform at creation time |
| Client Secret | Generated at creation time; displayed once. Stored as a bcrypt hash |
The Workload presents its Client ID and Client Secret with each API request using HTTP Bearer token authentication.
This is a legacy method. Prefer credential-less methods where available. See Best Practices for guidance on method selection.
pki_certificate¶
The Workload authenticates by presenting an X.509 client certificate during the TLS handshake. The platform verifies the certificate against the registered certificate's fingerprint.
| Field | Description |
|---|---|
| Certificate | PEM-encoded X.509 certificate (the Workload's public certificate) |
The platform stores only the certificate fingerprint. The corresponding private key must be held securely by the Workload.
This is a legacy method. Prefer credential-less methods where available.
azure_jwt¶
The Workload authenticates using a JWT issued by Azure Active Directory. This supports both Azure Managed Identity and Workload Identity Federation scenarios.
| Configuration Field | Description |
|---|---|
| Tenant ID | The Azure AD tenant ID |
| Client ID / App ID | The Azure AD Application or Managed Identity client ID |
| Audience | The JWT audience claim to validate (usually the application's App ID URI) |
The platform validates the JWT signature against Azure AD's JWKS endpoint and checks the aud, iss, and sub claims.
azure_arc¶
The Workload authenticates using a managed identity token issued by the Azure Arc-connected machine's IMDS endpoint. This method is suitable for on-premises or edge servers enrolled in Azure Arc.
| Configuration Field | Description |
|---|---|
| Tenant ID | The Azure AD tenant ID |
| Client ID | The Arc-enrolled machine's managed identity client ID |
| Resource | The resource URI included in the token request |
spiffe_spire¶
The Workload authenticates using a SPIFFE Verifiable Identity Document (SVID). This is the recommended method for service meshes and environments using SPIFFE/SPIRE for workload identity.
| Configuration Field | Description |
|---|---|
| Trust Domain | The SPIFFE trust domain (for example, spiffe://example.com) |
| SPIFFE ID | The specific SPIFFE ID assigned to this Workload (for example, spiffe://example.com/ns/production/sa/api) |
The platform validates the SVID against the SPIRE trust bundle and verifies the SPIFFE ID matches the registered value.
oidc_oauth2¶
The Workload authenticates using a JWT issued by any OIDC-compliant identity provider.
| Configuration Field | Description |
|---|---|
| Issuer URL | The OIDC issuer URL (used to discover the JWKS endpoint) |
| Client ID / Audience | The expected aud claim value |
| Subject | The expected sub claim value for this specific Workload |
Authenticating Against a Bridge¶
When a Workload targets a Bridge instead of the SaaS, the same credentials are used — only the base URL changes. The Bridge validates credentials using data synced from the platform during its heartbeat cycle.
The six authentication methods behave differently on a Bridge depending on whether credential validation requires an external identity provider:
| Method | Validation on Bridge | Requires External Connectivity |
|---|---|---|
client_secret |
Bridge validates bcrypt hash locally | No |
pki_certificate |
Bridge validates fingerprint locally | No |
azure_jwt |
Bridge must contact Azure AD JWKS endpoint | Yes |
azure_arc |
Bridge must contact Azure IMDS and Azure AD | Yes |
spiffe_spire |
Bridge must contact SPIRE server for trust bundle | Yes |
oidc_oauth2 |
Bridge must contact OIDC issuer discovery URL | Yes |
Offline resilience: If the Bridge cannot reach an external identity provider at authentication time, the authentication attempt fails. For Workloads that must continue to retrieve secrets when neither the SaaS nor the external IdP is reachable, use client_secret or pki_certificate — both validate entirely from data the Bridge holds in memory.
For all other methods, the Bridge must have network access to the relevant identity provider even when it cannot reach the SaaS platform.
Next Steps¶
- Setting up Workloads — create and configure Workloads.
- Best Practices for Workloads — guidance on selecting the right authentication method.