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: '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:    string   = 'auto',   // 'kubernetes' | 'aws' | 'aws_iam' | 'gcp' | 'azure' | 'auto'
    tokenSource: ?Closure = null,     // override OIDC token fetch entirely
    awsRegion:   string   = '',       // optional - pins the aws_iam STS region (else AWS chain + EC2 IMDS)
)

Field	Type	Default	Description
`provider`	`string`	`'auto'`	Which provider to use for the workload OIDC token. `'auto'` probes the environment in order.
`tokenSource`	`?Closure`	`null`	Custom closure that returns a workload OIDC JWT string. When non-null, takes precedence over `provider`.

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 (`.../instance/service-accounts/default/identity?audience=westyx-nexus`)

The first matching provider is used. If none match and no tokenSource closure is provided, NexusClient::create throws a NexusException. 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: '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 (the baseUrl 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 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: 'kubernetes'),
));

Custom tokenSource closure

Provide a Closure to bypass auto-detection entirely. This is useful for tests, custom CI flows, or environments the SDK does not natively recognise:

use WestyxNexus\WifConfig;

$client = NexusClient::create(new NexusConfig(
    baseUrl: $_ENV['NEXUS_URL'],
    wif: new WifConfig(
        tokenSource: function (): string {
            // Any logic that returns a workload OIDC JWT string.
            return file_get_contents('/run/secrets/oidc-token');
        },
    ),
));

When tokenSource is non-null it takes precedence over provider.

Token exchange flow

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

OIDC token fetch - calls tokenSource() (or the auto-detected built-in equivalent) to get a workload-identity JWT.
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	Subsequent sync attempts throw `NexusException`; existing cache continues to be served

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

Custom tokenSource closure

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

​Custom tokenSource closure

​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

Custom tokenSource closure

Token exchange flow

Session refresh within 60 s of expiry

Error cases

Project-level vs service-level trust policies