Skip to content

Best Practices for Workloads

Choose the Right Authentication Method

Prefer credential-less authentication methods wherever your environment supports them. Credential-less methods eliminate static secrets that must be rotated and reduce the risk of credential exposure.

Method Credential-less? Recommended When
spiffe_spire Yes Service mesh or SPIFFE/SPIRE infrastructure already deployed
azure_jwt Yes Workload runs in Azure (VM, AKS, App Service)
azure_arc Yes On-premises or edge server enrolled in Azure Arc
oidc_oauth2 Yes Custom or internal OIDC-compatible identity provider available
pki_certificate No Existing PKI infrastructure; environments without an OIDC provider
client_secret No Development, testing, or environments with no other option

Reserve client_secret and pki_certificate for environments where credential-less methods are genuinely unavailable. If you use client_secret, rotate the secret on a regular schedule and treat it with the same care as a database password.

Scope Access to the Minimum Required Lockers

Grant each Workload access only to the Lockers it actually needs. A Workload that has access to five Lockers when it only reads from one represents unnecessary exposure. Review access grants regularly and revoke any that are no longer required.

Use the Locker's Workload Access tab to audit which Workloads have access to each Locker.

Use Inactive Status for Temporary Suspension

If a Workload needs to be temporarily disabled — during an incident investigation, deployment freeze, or maintenance window — set its Status to Inactive rather than deleting it. This preserves configuration and access grants for re-enablement while immediately blocking access.

Choosing Between SaaS and Bridge Authentication

Direct SaaS authentication is the right default for cloud-native Workloads. Target a Bridge when the Workload has specific availability or latency requirements that the SaaS cannot meet.

Use SaaS when… Use a Bridge when…
The Workload runs in a cloud environment with reliable SaaS connectivity The Workload runs on-premises or at the edge, co-located with a Bridge
Centralised audit logging is required in real time Secrets retrieval must survive temporary SaaS outages
No on-premises Bridge exists or is warranted Network latency to the SaaS is a concern
Multiple on-premises Workloads share the same Lockers

When targeting a Bridge, ensure the Lockers required by the Workload are assigned to that Bridge's cache. If a Locker is not cached, the Bridge will return a 404 even if the Workload has a valid access grant. See Setting up Bridges for instructions on assigning Lockers to a Bridge cache.

Offline-Capable Bridge Access

If the Workload must continue to authenticate when neither the SaaS nor an external identity provider is reachable, use client_secret or pki_certificate. The Bridge validates both methods entirely from its in-memory credential data, with no external calls required.

For all other authentication methods (azure_jwt, azure_arc, spiffe_spire, oidc_oauth2), the Bridge must be able to reach the external identity provider to validate the token. If the identity provider is unreachable, authentication fails.

Handle Authentication Failures Gracefully

Applications consuming secrets via the Workload API should handle authentication failures and network errors with appropriate backoff and alerting. A Workload failure means the application cannot retrieve secrets — design for this case rather than crashing.

Monitor for Unauthorised Access

The audit log records every secrets download attempt, including workload.locker.download.unauthorised events. Alert on unexpected patterns — unauthorised attempts may indicate misconfigured access grants or credential misuse.

Next Steps