Skip to main content
For deployments that prefer not to manage static API keys, the Spring Boot SDK can authenticate via Workload Identity Federation (WIF). The SDK fetches a workload OIDC token from the running environment, exchanges it for a Nexus session JWT, and uses Authorization: Bearer <jwt> on every subsequent API call. In the starter WIF is on whenever nexus.api-key is not set (unless nexus.wif.enabled=false); a plain client uses it when NexusConfig.wif(...) carries an enabled WIFConfig.

Enabling via application.yml

When WIF is on, nexus.api-key is optional. When both are set the session is used, and the key is the fallback for a session that has expired and could not be renewed.
nexus.base-url must use https:// - NexusClient.create rejects plain-http endpoints (loopback excepted, for development), since credentials travel on every request.

Enabling programmatically

Each provider has its own factory, and that factory owns the provider’s options - so a combination that has no meaning cannot be written down:

Supplying your own credential

The auto-configuration picks up any WIFConfig bean automatically, and a bean takes precedence over the nexus.wif.* properties. WIFConfig.custom(...) takes an ExchangePayloadSource, which returns the credential to exchange as an ExchangeCredential; the SDK writes the request body from it.
ExchangeCredential has exactly the shapes the exchange accepts:
A blank token is a missing credential (NexusWIFNotConfiguredException). context.serverId() is the authority this client’s own requests carry in Host - a signed credential binds to it so it cannot be replayed against another deployment; the aws_iam provider signs it into X-Nexus-Server-ID. The source is called once per session refresh, on the calling thread, so blocking I/O inside it is fine. It cannot be selected from nexus.wif.provider - it needs an object, so it is a bean.

Supported providers

When provider is auto the SDK probes the environment in this order and picks the first provider whose credential material is actually present - a file stat or a live metadata probe with a ~1 s timeout, never an environment variable alone: developer is the last provider auto considers, so a real cloud identity always wins over a laptop credential. WIFProvider is an enum: wireValue() is the spelling the protocol and application.yml use, and fromWireValue(String) parses one. The property binds leniently - aws_iam, aws-iam, AWS_IAM and NEXUS_WIF_PROVIDER=aws_iam all resolve to the same constant - and an unknown value fails the context start naming the property, the value, its origin and every valid name. The OIDC providers use only java.net.http.HttpClient; aws_iam additionally uses software.amazon.awssdk:auth + :regions (optional dependencies) for the credential/region chain and the SigV4 signer. developer needs nothing - the credentials file is read through the SDK’s own JSON codec.

Local development (the developer provider)

An application on a developer machine has no workload OIDC token. The developer provider uses the session the Westyx CLI already obtained:
westyx dev run starts the application with WESTYX_SERVICE_ENDPOINT set to the service’s endpoint, and with no nexus.api-key the starter enables WIF on its own - so under westyx dev run neither nexus.base-url nor nexus.wif.enabled is needed. A nexus.base-url you set wins over the variable. The variable is trimmed, an empty value counts as unset, and it is validated like the property - https, or http on loopback only - with any error naming WESTYX_SERVICE_ENDPOINT. Discovery order
  1. $WESTYX_DEV_TOKEN, when set and non-blank - its value is the session token, and no file is read.
  2. The CLI’s dev-credentials.json, whose entry is selected by matching the endpoint - base-url, or WESTYX_SERVICE_ENDPOINT when that is unset. Two local services on different ports therefore keep their own credentials.
Where the file lives, matching what the CLI writes: Expiry. The SDK cannot renew a developer session itself. A credential that has expired - or that is close enough to expiry that the next request would refresh it anyway - is refused with NexusSessionExpiredException, whose message names the exact westyx dev setup --service=<name> command to run; with no credential for the endpoint at all the exception is NexusWIFNotConfiguredException. Only token and expires_at are read from an entry; no Keycloak credential is ever opened or stored. File safety. The credentials file is refused if it is readable beyond its owner. The CLI writes it 0600 inside a 0700 directory. No exchange takes place - see Token exchange flow.

AWS IAM (non-EKS AWS compute)

ECS/Fargate tasks, Lambda functions, and plain EC2 instances have IAM credentials but no OIDC token, so the OIDC providers cannot serve them. The aws_iam provider closes this gap. Add the optional AWS SDK dependencies (software.amazon.awssdk:auth + :regions), then:
The SDK SigV4-signs an STS GetCallerIdentity request with the standard AWS credential chain (task role, instance profile, env) - never sending it to AWS - and posts the signed headers + body to /v1/auth/token-exchange as {"provider":"aws_iam","aws_sts_request":...}. Nexus replays it against a pinned STS endpoint and matches the caller’s IAM role against an aws_iam trust policy (subject = arn:aws:iam::<account>:role/<name>). Nothing else to configure: the SDK signs your service’s own host (the base-URL host) into X-Nexus-Server-ID inside the signature, and Nexus verifies it against the host the request arrived on - so a captured signed request is valid for that ONE service only. Selecting aws_iam without the AWS SDK dependencies present throws an actionable error naming the Maven coordinates.

Audience

GCP and Azure require an audience claim when issuing the OIDC token:
Azure IMDS is the exception: the generic default is refused with a clear error, because Azure AD rejects it as a resource. On the IMDS path (plain VM / App Service - no federated token file) you MUST set audience to your app registration’s Application ID URI (api://<client-id>). On AKS with Azure Workload Identity the projected federated token file ($AZURE_FEDERATED_TOKEN_FILE) is preferred automatically and no audience is needed. Default: westyx-nexus.

Token exchange flow

The developer provider skips this entirely. It yields an already-issued Nexus session token, which is used directly as the bearer; nothing is POSTed to /v1/auth/token-exchange. A refresh re-reads the source, so re-running westyx dev setup in another terminal is picked up without restarting the application.
  1. Credential - the provider (or your ExchangePayloadSource) produces an ExchangeCredential: a workload OIDC token, or a signed aws_iam request.
  2. Token exchange - the SDK POSTs it to /v1/auth/token-exchange. The backend validates it and returns:
  3. Session storage - the SDK keeps the session token in memory and sends Authorization: Bearer <session> on every request.
  4. Refresh - the first request within 60 s of the session’s expiry re-runs steps 1-2 before it goes out. The active stream is not interrupted.
  5. auth_expiring event - when the server emits this control event over the stream, the SDK refreshes the session in the background before the server closes the stream.

When a refresh fails

Reads keep serving the cache in every case.

Split sync vs stream HttpClient

The SDK uses two separate HttpClient instances - one for short requests (sync, writes, evaluations, the token exchange; 10 s connect and request timeouts) and one for the long-lived stream - so a consumer-supplied short timeout cannot cut the stream.

Project-level vs service-level trust policies

The Nexus backend supports trust policies at two scopes:
A project-level trust policy is less restrictive than a service-level one. Any workload that satisfies the policy can connect to any service in the project by targeting its base-url. For services handling sensitive data (payments, credentials, PII) consider a dedicated service-level trust policy.