AWS request signing (SigV4)#

Install the package:

composer require kinetis/aws-sigv4

Kinetis\AwsSigV4\SigV4SigningClient is a PSR-18 client that signs every request with AWS Signature Version 4 and sends it to one configured origin. Use it with a library that accepts a PSR-18 client when the AWS endpoint authenticates with IAM, such as Amazon OpenSearch Service or an API Gateway API with IAM authorization. A request suspends the calling Fiber while it waits on AWS.

Sign requests for Amazon OpenSearch Service#

With kinetis/search-opensearch installed (Search (OpenSearch)), configure the domain endpoint and its region:

composer require kinetis/search-opensearch
.env#
OPENSEARCH_DOMAIN_URL=https://search-orders-abc123.eu-west-1.es.amazonaws.com
AWS_REGION=eu-west-1

Then bind a signed OpenSearch\Client in bootstrap.php:

bootstrap.php#
use Kinetis\AwsSigV4\SignedTransport;
use Kinetis\AwsSigV4\SigV4SigningClient;
use Kinetis\Config\Config;
use Kinetis\Container\AppScope;
use OpenSearch\Client;
use OpenSearch\EndpointFactory;
use OpenSearch\TransportFactory;

return static function (AppScope $app, Config $config): void {
    $signed = new SigV4SigningClient(
        origin: $config->required('OPENSEARCH_DOMAIN_URL'),
        region: $config->required('AWS_REGION'),
        service: 'es',
        transport: SignedTransport::create([
            'timeout' => 5.0,
            'max_duration' => 10.0,
            // opensearch-php sets no Content-Type, and OpenSearch requires JSON.
            'headers' => ['Content-Type' => 'application/json', 'Accept' => 'application/json'],
        ]),
    );

    $app->instance(Client::class, new Client(
        new TransportFactory()->setHttpClient($signed)->create(),
        new EndpointFactory(),
    ));
};

Inject OpenSearch\Client wherever application code needs the engine client. OPENSEARCH_DOMAIN_URL is this example’s own key; AWS_REGION is also the variable AWS tooling reads.

  • Leave SEARCH_OPENSEARCH_HOST unset. The package then binds nothing, and this binding is the only OpenSearch\Client. Kinetis\Search\SearchClient is not bound on this path: its failure contract (Failures) belongs to the package’s own transport.

  • origin is the domain endpoint, with no path. opensearch-php sends a path and a query string only; the client adds the origin’s scheme and host.

  • service: 'es' is Amazon OpenSearch Service’s signing name, and execute-api is API Gateway’s. A wrong service or region still signs, and AWS rejects the signature rather than this client reporting an error.

  • Grant access in the domain’s access policy to the IAM role or user the application runs as.

  • Build the client once, at boot. It holds resolved credentials until they expire and reuses its connections, and it keeps no request state, so the AppScope instance is safe in a persistent worker.

An origin, region or service that fails validation throws Kinetis\AwsSigV4\Exception\SigningException from the constructor, so a misconfigured endpoint fails at boot.

The trusted origin#

origin is the only scheme, host and port the client signs for, with an optional path prefix. For each request:

  • a relative target such as /orders/_search resolves against the origin, under its path prefix;

  • an absolute target must name exactly that origin and stay under the prefix;

  • anything else — another host or port, http under an https origin, a path that climbs out of the prefix — throws UntrustedOriginException before credentials are resolved, the body is read, or anything is sent.

A redirect is returned as the response and never followed, and nothing in the client or its transport resends a request, so the signed Authorization and X-Amz-Security-Token headers reach only this origin. Set the origin from deployment configuration, never from request input: it decides where signed credentials may go. The trusted origin has the origin grammar and target normalization, and The canonical request the exact signed form.

Credentials#

With no credentialProvider argument, the client resolves credentials through AsyncAws’s default chain, in order: environment variables (assuming the role in AWS_ROLE_ARN through STS when it is set), a web identity token, the shared credentials and config files, ECS or EKS pod identity, then EC2 instance metadata.

  • In production, attach an IAM role to the workload — an ECS task role, EKS pod identity, a web identity role, or an EC2 instance profile. Credentials then come from AWS, expire and refresh, and never appear in configuration.

  • For local development, set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, plus AWS_SESSION_TOKEN for temporary credentials, in the environment or an uncommitted .env, or select a profile from ~/.aws/credentials with AWS_PROFILE.

Resolved credentials are held and reused until they expire. A lookup that finds nothing holds nothing, so a transient metadata failure costs one request, which fails with UnsignableRequestException before anything is sent. Pass credentialProvider: to replace the chain (Credential resolution).

Deadlines#

SignedTransport::create() bounds every request at 30 seconds idle — the longest wait between bytes — and 30 seconds in total. Set both for a caller that cannot wait that long, as the example above does; setting one leaves the other at 30.

sendRequest() returns once the response headers arrive, and the body is read after that. opensearch-php reads it within the same call; a body read that fails or outlives the deadline throws a RuntimeException from the response stream rather than a PSR-18 exception (Deadlines).

When a request fails#

Every exception sendRequest() throws implements PSR-18’s ClientExceptionInterface:

  • Psr\Http\Client\NetworkExceptionInterface — NetworkFailureException: the connection could not be made, was lost, or timed out. The request may have reached AWS and been applied. An index or bulk write can already be stored: check before sending it again, or write with a document ID so a repeat replaces the document instead of adding a second one. Nothing on this path resends a request — not the signing client, not its transport, and not opensearch-php’s HttpTransport.

  • Psr\Http\Client\RequestExceptionInterface — the request could not be signed or sent: UntrustedOriginException for a target outside the origin, UnsignableRequestException for missing credentials, a failing credential provider or an unreadable body, and TransportFailureException when the transport rejects the signed request. The first two are raised before anything is sent.

An HTTP error status is a response, not an exception, at this layer; opensearch-php raises its own exception for a status of 400 or more. Exception messages are fixed text with no cause chained, and getRequest() returns the request that was passed in, never the signed one (Failures).

What blocks a worker#

Network work suspends the calling Fiber: the signed request and every credential lookup that calls AWS (STS, web identity, ECS, EKS pod identity, instance metadata). Local work blocks the calling thread: the shared credentials and config files, an SSO cache file and a web identity token file are read with blocking filesystem calls when credentials are first resolved and on each refresh, and the request body is buffered in memory and hashed.

In a persistent worker, blocking work pauses every request on that worker while it runs; under PHP-FPM it delays only its own request. A client built once at boot reads credential files only when it has no unexpired credentials. Request bodies and blocking work has the body buffering rules.

See also#