Node.js SDK - Workload Identity Federation

For deployments that prefer not to manage static API keys, the Node.js 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. WIF is opt-in. When NexusConfig.wif is undefined (the default), the SDK falls back to the static apiKey flow and behaves exactly as in v0.1.0.

Enabling

import { NexusClient, WIFProviderAuto } from '@westyx-nexus/sdk-nodejs';

const client = await NexusClient.create({
  endpoint: 'https://blue-ocean-a5rx7.westyx.dev',
  wif: {
    enabled:  true,
    provider: WIFProviderAuto, // default - auto-detect from env
  },
});

apiKey becomes optional when WIF is enabled.

Security note (v0.9.0): endpoint must use https:// - NexusClient.create() refuses plain-http endpoints (loopback/localhost excepted for development), since credentials travel on every request.

Supported providers

When provider is WIFProviderAuto the SDK probes the environment in this order and picks the first provider whose credential material is actually present (v0.9.0 - file stats + live metadata probes, ~1 s timeout; earlier versions keyed on environment variables absent on real cloud nodes):

Provider constant	Auto-detect signal	Credential
`WIFProviderKubernetes`	`/var/run/secrets/kubernetes.io/serviceaccount/token` exists	reads the projected service-account token file (rotated by kubelet)
`WIFProviderAWS`	`AWS_WEB_IDENTITY_TOKEN_FILE` set and the file exists (EKS IRSA)	reads the IRSA token file at that path
`WIFProviderAzure` (Workload Identity)	`AZURE_FEDERATED_TOKEN_FILE` set and the file exists (AKS)	reads the projected federated token file
`WIFProviderGCP`	`metadata.google.internal` reachable (live probe)	GETs `metadata.google.internal/computeMetadata/v1/.../identity?audience=<aud>` with `Metadata-Flavor: Google`
`WIFProviderAzure` (IMDS)	`169.254.169.254/metadata` reachable (live probe)	GETs an Azure IMDS managed-identity token - requires `audience: "api://<client-id>"` (your app registration’s Application ID URI; the generic default is refused because Azure AD rejects it)
`WIFProviderDeveloper`	`dev-credentials.json` holds an unexpired entry for this endpoint, or `$WESTYX_DEV_TOKEN` is set - probed last, behind every cloud provider	a Nexus session issued by `westyx dev setup`, used as the Bearer directly; there is no token exchange on this path
`WIFProviderAWSIAM`	not auto-detected - select explicitly (resolvable AWS credentials alone, e.g. a dev laptop’s `~/.aws/credentials`, are too weak a signal)	SigV4-signs an STS `GetCallerIdentity` request (never sent to AWS) that Nexus replays to prove your IAM role - works on ECS/Fargate, Lambda, and plain EC2

The OIDC providers need nothing beyond the standard library - the core SDK declares no runtime dependencies. AWS IAM needs the AWS signer, so it ships as a separate package, @westyx-nexus/wif-aws-nodejs, which a consumer who does not use it never installs. You can also pin a specific provider:

import { WIFProviderKubernetes } from '@westyx-nexus/sdk-nodejs';

wif: { enabled: true, provider: WIFProviderKubernetes }

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 above cannot serve them. AWS IAM closes that gap. It ships as its own package and is selected through wif.exchangePayload:

npm install @westyx-nexus/wif-aws-nodejs

import { awsIamExchangePayload } from '@westyx-nexus/wif-aws-nodejs';

const client = await NexusClient.create({
  endpoint: 'https://blue-ocean-a5rx7.westyx.dev',
  wif: {
    enabled: true,
    exchangePayload: awsIamExchangePayload(),
    // awsIamExchangePayload({ region: 'eu-central-1' }) to pin the region;
    // by default it comes from AWS_REGION / shared config, then EC2 IMDSv2.
  },
});

Why a separate package. Signing an STS request needs the AWS SDK - 34 packages and around 14 MB. A core-only install is one package, so a service running nowhere near AWS neither installs nor loads that chain. provider: 'aws_iam' returns an error naming the package and this replacement. How it works:

The provider SigV4-signs an STS GetCallerIdentity request using the standard AWS credential chain (task role, instance profile, env). The request is never sent to AWS by the SDK.
The signed request (headers + body) is posted to /v1/auth/token-exchange as {"provider":"aws_iam","aws_sts_request":...}.
Nexus replays it against a pinned STS endpoint; AWS answers with the caller’s IAM identity, which Nexus matches against an aws_iam trust policy (subject = the assumed-role ARN, normalized to arn:aws:iam::<account>:role/<name>).

Nothing else to configure: the SDK passes your service’s own host - including a port that is not the scheme’s default, so a deployment on :8443 signs :8443 - to the provider, which signs it into the X-Nexus-Server-ID header before computing the signature, and Nexus verifies it against the host the exchange request actually arrived on. A captured signed request is therefore valid for that ONE service only - it cannot be replayed against any other service or deployment. AWS IAM is never auto-detected - resolvable AWS credentials alone, such as a developer laptop’s ~/.aws/credentials, are too weak a signal. Supply the payload producer explicitly. The STS host is partition-aware. sts.<region>.amazonaws.com does not exist in the AWS China partition, so cn-north-1 and cn-northwest-1 sign sts.<region>.amazonaws.com.cn instead.

Local development (developer credentials)

A laptop has no workload OIDC token, so no cloud provider can match. The developer provider covers that case: the Westyx CLI performs the exchange once and stores the resulting Nexus session, and the SDK sends it as the Bearer.

westyx dev setup --service=my-backend-api   # issue a session for this service
westyx dev status                           # what is stored, and until when
westyx dev teardown                         # remove it

const client = await NexusClient.create({
  endpoint: 'https://swift-ocean-a5rx7.westyx.dev',
  wif: { enabled: true },   // auto-detect reaches `developer` when no cloud credential is present
});

Pin it with provider: WIFProviderDeveloper when you want the actionable “run westyx dev setup” error instead of “no provider matched”. The CLI creates the credentials file 0600 inside a 0700 directory:

Platform	Path
Linux	`$XDG_CONFIG_HOME/westyx/dev-credentials.json`, or `~/.config/westyx/dev-credentials.json`
macOS	`~/Library/Application Support/westyx/dev-credentials.json`
Windows	`%AppData%\westyx\dev-credentials.json`

The entry is selected by endpoint host, so a trailing slash or a scheme difference between what the CLI stored and what you configured does not hide it. $WESTYX_DEV_TOKEN overrides the file entirely - the escape hatch for a container or a CI-like shell with no user config directory. What makes this provider different:

No token exchange. The stored value is an already-issued Nexus session, so the SDK never posts to /v1/auth/token-exchange on this path.
No Keycloak token. The CLI performed the Keycloak exchange; only the resulting Nexus session reaches disk.
Last in the chain. On a real cloud host the workload’s own credential always wins.
Renewal without a restart. The source re-reads its input on every session refresh, so re-running westyx dev setup in another terminal repairs a running process at its next refresh.
Fails closed with a command to run. An absent, expired, or too-soon-to-expire credential throws NexusWIFNotConfiguredError naming the service and westyx dev setup --service=<name>.

Custom token source

Provide a tokenSource function to bypass auto-detection. The right hook for tests, custom CI flows, or topologies the SDK doesn’t natively recognise.

wif: {
  enabled: true,
  tokenSource: async () => readMyOidcToken(),
}

When tokenSource is set it takes precedence over provider, and exchangePayload takes precedence over both. The SDK reports either as provider 'custom' - it used the credential you supplied rather than one it resolved itself. 'custom' is reportable but not selectable: provider: 'custom' is a compile error. The one selector that does not defer to tokenSource is WIFProviderAWSIAM. It throws the message naming @westyx-nexus/wif-aws-nodejs either way, because signing an STS request and sending a bearer token are different authentication methods and the SDK will not quietly pick one.

Audience

GCP and Azure require an audience claim when issuing the OIDC token:

wif: {
  enabled:  true,
  provider: WIFProviderGCP,
  audience: 'westyx-nexus',
}

The default is 'westyx-nexus' if unset. 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.

Token exchange flow

OIDC token fetch - the configured token source returns a workload-identity JWT.

Token exchange - the SDK POSTs {"oidc_token": "<jwt>"} to /v1/auth/token-exchange. The backend validates the OIDC issuer/signature and returns:

{
  "session_token":  "<jwt>",
  "token_type":     "Bearer",
  "expires_in":     3600,
  "service_kind":   "backend",
  "wif_provider":   "kubernetes"
}

Session storage - the SDK caches the session token in memory and uses Authorization: Bearer <session> on all subsequent /sync and /stream requests.
Auto-refresh - ~60 s before expiry the SDK silently re-runs steps 1-2 from a background promise. The active SSE stream is not interrupted.
auth_expiring event - when the server emits this control event over SSE, the SDK pre-emptively refreshes the session before the server force-closes the stream.

The developer provider skips steps 1 and 2 entirely. The value it reads is already a Nexus session - the CLI performed the exchange - so the SDK goes straight to session storage and never posts to /v1/auth/token-exchange. Failures throw NexusWIFTokenExchangeFailedError (or NexusWIFNotConfiguredError for environment-detection failures). On the initial connect these are wrapped in NexusInitError. Background-refresh failures are reported through the configured logger with component: "wif", and the existing session is retried.

Service kind

The token-exchange response includes a service_kind field ("backend" or "frontend"). The SDK propagates this to the NexusClient.kind getter, which getSecret() uses to gate access:

if (client.kind === 'frontend') {
  // throws NexusServiceKindMismatchError - frontends must not hold secrets
  client.getSecret('DB_PASSWORD');
}

Project-level vs service-level trust policies

The Nexus backend supports trust policies at two scopes:

Scope	What it covers	Recommended for
Project-level	All services in the project share one policy	Most teams - no per-service cloud identity needed
Service-level	A specific policy bound to one service only	High-security services (payments, PII)

At token exchange time the backend checks service-level policies first, then falls back to project-level. All services in a project can share one Kubernetes service account.

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 endpoint. For services handling sensitive data (payments, credentials, PII) consider a dedicated service-level trust policy.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Node.js SDK - Workload Identity Federation

Enabling

Supported providers

AWS IAM (non-EKS AWS compute)

Local development (developer credentials)

Custom token source

Audience

Token exchange flow

Service kind

Project-level vs service-level trust policies

​Enabling

​Supported providers

​AWS IAM (non-EKS AWS compute)

​Local development (developer credentials)

​Custom token source

​Audience

​Token exchange flow

​Service kind

​Project-level vs service-level trust policies

Enabling

Supported providers

AWS IAM (non-EKS AWS compute)

Local development (developer credentials)

Custom token source

Audience

Token exchange flow

Service kind

Project-level vs service-level trust policies