PHP SDK - Workload Identity Federation

For deployments that prefer not to manage static API keys, the PHP 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 null (the default), the SDK uses the static apiKey flow and behaves identically to a client without WIF configuration.

Enabling WIF

Pass a WifConfig to NexusConfig::$wif:

use WestyxNexus\NexusClient;
use WestyxNexus\NexusConfig;
use WestyxNexus\WifConfig;

$client = NexusClient::create(new NexusConfig(
    baseUrl: 'https://blue-ocean-a5rx7.westyx.dev',
    wif: new WifConfig(provider: WifProvider::AUTO),
));

apiKey becomes optional when wif is set. You can provide both - the SDK uses WIF and falls back to the static key if a session refresh fails after the initial connect.

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

WifConfig reference

new WifConfig(
    provider:         WifProvider = WifProvider::AUTO,  // KUBERNETES|AWS|AWS_IAM|GCP|AZURE|DEVELOPER|AUTO
    credentialSource: ?WifCredentialSource = null,      // replaces the SDK's resolution entirely
    awsRegion:        string = '',                      // optional - pins the aws_iam STS region
    audience:         string = '',                      // empty means the Nexus default
)

Field	Type	Default	Description
`provider`	`WifProvider`	`AUTO`	Which provider authenticates this workload. `AUTO` probes the environment in order. An enum, so an unknown value cannot be constructed; parse a configuration string with `WifProvider::fromWire()`.
`credentialSource`	`?WifCredentialSource`	`null`	Supplies the credential instead of the SDK’s own resolution. When set it is the sole resolver.
`awsRegion`	`string`	`''`	`aws_iam` only. Empty resolves from the AWS chain, then EC2 IMDS.
`audience`	`string`	`''`	Empty means the Nexus default, which is what a GCP trust policy expects. The Azure IMDS path requires your app registration’s Application ID URI (`api://<client-id>`).

Provider auto-detection table

When provider is 'auto', the SDK probes the environment in this order, checking for actual credential material (the token files are stat-ed, not just env-var presence):

Provider string	Auto-detect signal	Credential
`'kubernetes'`	`/var/run/secrets/kubernetes.io/serviceaccount/token` exists	Reads the projected service-account token file (rotated by kubelet)
`'aws'`	`AWS_WEB_IDENTITY_TOKEN_FILE` set and the file exists (EKS IRSA)	Reads the token file at `AWS_WEB_IDENTITY_TOKEN_FILE`
`'azure'`	`AZURE_FEDERATED_TOKEN_FILE` set and the file exists (AKS)	Reads the federated token file at `AZURE_FEDERATED_TOKEN_FILE`
`'gcp'`	GCE metadata server reachable	Fetches a Google-signed OIDC identity token from the GCE metadata server
`'azure'` (IMDS)	the Azure IMDS endpoint is reachable	Fetches an Azure managed-identity token - requires `audience: 'api://<client-id>'`
`'developer'`	`dev-credentials.json` holds an entry for this endpoint, or `$WESTYX_DEV_TOKEN` is set - probed last	Sends the session `westyx dev setup` issued as the Bearer; there is no token exchange on this path

Every free filesystem check precedes every network probe, which is why the Azure file check runs before the GCP probe and the Azure IMDS probe after it: an AKS workload must not wait on a probe that cannot succeed there to find a credential that was in a local file all along. developer is last despite being a file check, because on a real cloud host the workload’s own credential must always win over one that happens to be on the machine. The first matching provider is used. If none match and no credential source is configured, NexusClient::create throws a NexusException naming what was probed. aws_iam is not auto-detected - select it explicitly (resolvable AWS credentials alone, e.g. a dev laptop’s ~/.aws/credentials, are too weak a signal).

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. It requires the optional aws/aws-sdk-php package:

composer require aws/aws-sdk-php

$client = NexusClient::create(new NexusConfig(
    baseUrl: $_ENV['NEXUS_URL'],
    wif: new WifConfig(provider: WifProvider::AWS_IAM, awsRegion: 'eu-central-1'),
));

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 into X-Nexus-Server-ID inside the signature - the baseUrl host, plus its port when that is not the scheme’s default, matching the host the backend validates against - and Nexus verifies it against the host the request arrived on, so a captured signed request is valid for that ONE service only. A deployment reached at a non-default port such as https://host:8443 is authenticated correctly. Selecting aws_iam without aws/aws-sdk-php installed throws an actionable NexusException.

Explicit provider

Pin a specific provider to skip auto-detection:

$client = NexusClient::create(new NexusConfig(
    baseUrl: $_ENV['NEXUS_URL'],
    wif: new WifConfig(provider: WifProvider::KUBERNETES),
));

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

$client = NexusClient::create(new NexusConfig(
    baseUrl: $_ENV['NEXUS_URL'],
    wif: new WifConfig(), // AUTO reaches `developer` when no cloud credential is present
));

Select WifProvider::DEVELOPER explicitly when you want the actionable “run westyx dev setup” error instead of “no WIF provider could be detected”. 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 matched on the endpoint’s host and on its port when that is not the scheme’s default, so a trailing slash, a scheme difference or a capitalised host does not hide it, while two local services on different ports stay distinct. $WESTYX_DEV_TOKEN overrides the file entirely. There is no token exchange on this path. The stored value is an already-issued Nexus session, so the SDK never posts to /v1/auth/token-exchange and never sees a Keycloak access or refresh token. The source is re-consulted on every session refresh, so re-running westyx dev setup in another terminal repairs a running process. A credential that is absent, expired, or too close to expiry to be refreshed against raises NexusDeveloperCredentialsException naming the service and the command.

Supplying your own credential

WifConfig::$credentialSource replaces the SDK’s resolution entirely - no provider is detected and no provider branch runs, so overriding resolution does not require aws/aws-sdk-php to be installed in order to select aws_iam.

use WestyxNexus\CallableWifCredentialSource;
use WestyxNexus\WifCredential;
use WestyxNexus\WifCredentialSource;

// A raw OIDC token:
new WifConfig(credentialSource: CallableWifCredentialSource::oidc(
    fn (): string => file_get_contents('/run/secrets/oidc-token'),
));

// Anything else - including a credential that is already a Nexus session:
final class MySource implements WifCredentialSource
{
    public function credential(): WifCredential
    {
        return WifCredential::sessionToken($token, $expiresAtUnix);
    }
}

Implement the interface rather than passing a callable when Laravel builds the client: a class-string survives php artisan config:cache and is resolved from the container, while a closure cannot be var_export()ed. A fault inside a source is reported as NexusTokenSourceException with the original as its cause, so it is never mistaken for the backend refusing the credential.

Token exchange flow

Internally, the SDK runs this protocol at startup and on each session refresh:

Credential resolution - the configured credential source, or the selected/auto-detected provider, produces the credential. The developer provider skips this step and the next entirely: what it reads is already a Nexus session, so the SDK goes straight to using it as the Bearer.
Token exchange - POSTs {"oidc_token": "<jwt>"} to /v1/auth/token-exchange. No auth header is sent on this call. The backend validates the OIDC issuer and signature, then returns:
{ "session_token": "<short-lived-nexus-jwt>", "token_type": "Bearer", "expires_in": 3600, "wif_provider": "kubernetes" }
Bearer auth on subsequent calls - every /v1/* request carries Authorization: Bearer <session_token>.
Pre-emptive refresh - when a request finds the session expires within 60 seconds, the SDK refreshes (re-running steps 1-2) before issuing the call.

Session refresh within 60 s of expiry

The SDK stores the session expiry time after each token exchange. Before each sync, write, or A/B test call, it checks whether the JWT expires within 60 seconds. If yes, it runs a token exchange first, then proceeds with the original call. connectStream()’s auth_expiring SSE event triggers a non-blocking early refresh ~5 minutes before expiry, reducing the chance of a mid-stream expiry.

Error cases

Scenario	Behaviour
`provider = 'auto'` but no environment signal found	`NexusClient::create` throws `NexusException` (WIF not configured)
`/v1/auth/token-exchange` returns non-2xx	`NexusClient::create` throws `NexusException` (token exchange failed); check for audience mismatch or OIDC issuer misconfiguration
Session JWT expired and refresh failed	Reads raise `NexusSessionExpiredException` - a WIF-only client fails closed rather than falling back to an empty API-key header. A static `apiKey` configured alongside WIF is the documented exception and is used instead.

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 applies this resolution order:

Does a service-level trust policy match this workload’s OIDC token claims? - if yes, authorise.
Does a project-level trust policy match? - if yes, authorise.
Neither matches - return 401.

This means you can configure one project-level trust policy and all services in the project accept that workload’s tokens. Each service client still uses its own baseUrl, so each gets its own service’s data.

A project-level trust policy is less restrictive than a service-level one. Any workload satisfying the policy can connect to any service in the project by targeting its baseUrl. For services handling sensitive data (payments, credentials, PII) consider a dedicated service-level trust policy instead.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

PHP SDK - Workload Identity Federation

Enabling WIF

WifConfig reference

Provider auto-detection table

AWS IAM (non-EKS AWS compute)

Explicit provider

Local development (developer credentials)

Supplying your own credential

Token exchange flow

Session refresh within 60 s of expiry

Error cases

Project-level vs service-level trust policies

​Enabling WIF

​WifConfig reference

​Provider auto-detection table

​AWS IAM (non-EKS AWS compute)

​Explicit provider

​Local development (developer credentials)

​Supplying your own credential

​Token exchange flow

​Session refresh within 60 s of expiry

​Error cases

​Project-level vs service-level trust policies

Enabling WIF

WifConfig reference

Provider auto-detection table

AWS IAM (non-EKS AWS compute)

Explicit provider

Local development (developer credentials)

Supplying your own credential

Token exchange flow

Session refresh within 60 s of expiry

Error cases

Project-level vs service-level trust policies