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
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 anyWIFConfig 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:
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
Whenprovider 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
$WESTYX_DEV_TOKEN, when set and non-blank - its value is the session token, and no file is read.- The CLI’s
dev-credentials.json, whose entry is selected by matching the endpoint -base-url, orWESTYX_SERVICE_ENDPOINTwhen that is unset. Two local services on different ports therefore keep their own credentials.
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. Theaws_iam provider closes this gap. Add the optional AWS SDK dependencies (software.amazon.awssdk:auth + :regions), then:
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 anaudience claim when issuing the OIDC token:
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
Thedeveloper 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.
- Credential - the provider (or your
ExchangePayloadSource) produces anExchangeCredential: a workload OIDC token, or a signedaws_iamrequest. - Token exchange - the SDK POSTs it to
/v1/auth/token-exchange. The backend validates it and returns: - Session storage - the SDK keeps the session token in memory and sends
Authorization: Bearer <session>on every request. - 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.
auth_expiringevent - 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.
