Copy page

Upstream Authentication

Upstream AWS Federated Auth Policy

Authenticate to AWS upstreams with no stored AWS keys using Workload Identity Federation. This policy exchanges Zuplo's ambient OIDC identity for an IAM role's short-lived temporary credentials via STS AssumeRoleWithWebIdentity, and makes them available to the AWS Lambda handler and to custom code, which sign upstream requests with AWS Signature Version 4.

With this policy, you'll benefit from:

• No Long-Lived Secrets: No AWS access keys are stored anywhere — the gateway proves its identity with a short-lived, audience-bound OIDC token
• Least Privilege: Assume a specific IAM role whose trust policy trusts only the Zuplo OIDC identity provider
• Automatic Token Management: Temporary credentials are cached in memory and refreshed before they expire
• Reusable Credentials: Resolve credentials once and use them from the AWS Lambda handler or your own code via AwsClient.fromContext(context)

To set this up you configure an IAM OIDC identity provider that trusts Zuplo's issuer, and an IAM role whose trust policy permits AssumeRoleWithWebIdentity for that provider.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

Code
{
  "name": "my-upstream-aws-federated-auth-inbound-policy",
  "policyType": "upstream-aws-federated-auth-inbound",
  "handler": {
    "export": "UpstreamAwsFederatedAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "region": "us-east-1",
      "roleArn": "arn:aws:iam::123456789012:role/zuplo-gateway"
    }
  }
}

Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be upstream-aws-federated-auth-inbound.
• handler.export <string> - The name of the exported type. Value should be UpstreamAwsFederatedAuthInboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• roleArn (required) <string> - The IAM role to assume with STS AssumeRoleWithWebIdentity. The role's trust policy must trust the Zuplo OIDC identity provider.
• region (required) <string> - The AWS region used for the STS endpoint and as the default signing region for consumers of the resolved credentials.
• audience <string> - The audience ('aud' claim) of the Zuplo-issued OIDC token. Must match a client ID configured on the IAM OIDC identity provider. Defaults to "sts.amazonaws.com".
• roleSessionName <string> - The STS role session name recorded in AWS CloudTrail. Must match the pattern [\w+=,.@-]64. Defaults to "zuplo-gateway".
• durationSeconds <number> - The lifetime in seconds of the temporary credentials requested from STS (900-43200). The assumed role's maximum session duration may further limit this value. Defaults to 3600.
• stsEndpoint <string> - Overrides the STS endpoint URL. Only needed for non-standard partitions such as AWS GovCloud or AWS China.
• tokenRetries <number> - The number of times to retry fetching temporary credentials in the event of a failure. Defaults to 3.
• expirationOffsetSeconds <number> - The number of seconds before credential expiration at which cached credentials are discarded and refreshed. Defaults to 300.

Using the Policy

Overview

The Upstream AWS Federated Auth policy obtains AWS credentials without storing any AWS keys. It exchanges Zuplo's ambient OIDC identity token for an IAM role's short-lived temporary credentials using STS AssumeRoleWithWebIdentity, then registers those credentials on the request context.

Like the upstream-aws-service-auth policy, it does not add an Authorization header itself — AWS Signature Version 4 signs the exact final request, which is only known inside the handler. The AWS Lambda handler and your own code read the resolved credentials and sign the requests they build.

AWS setup

1. Create an IAM OIDC identity provider that trusts the Zuplo issuer. Set the audience (client ID) to the value you use for the audience option (default sts.amazonaws.com).
2. Create an IAM role whose trust policy allows sts:AssumeRoleWithWebIdentity for that provider, with a condition on the token's audience.
3. Grant the role only the permissions the gateway needs (for example execute-api:Invoke or lambda:InvokeFunction).

Using the credentials

With the AWS Lambda handler

Code
{
  "paths": {
    "/lambda/{path}*": {
      "x-zuplo-route": {
        "handler": {
          "export": "awsLambdaHandler",
          "module": "$import(@zuplo/runtime)",
          "options": { "region": "us-east-1", "functionName": "my-function" }
        },
        "policies": { "inbound": ["upstream-aws-federated-auth"] }
      }
    }
  }
}

With custom code

Code
import { AwsClient } from "@zuplo/runtime/aws";
import { ZuploContext, ZuploRequest } from "@zuplo/runtime";

export default async function (request: ZuploRequest, context: ZuploContext) {
  const aws = AwsClient.fromContext(context, {
    service: "execute-api",
    region: "us-east-1",
  });
  return aws.fetch(
    "https://abc123.execute-api.us-east-1.amazonaws.com/prod/orders",
  );
}

Configuration

Code
{
  "name": "upstream-aws-federated-auth",
  "policyType": "upstream-aws-federated-auth",
  "handler": {
    "export": "UpstreamAwsFederatedAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "roleArn": "arn:aws:iam::123456789012:role/zuplo-gateway",
      "region": "us-east-1"
    }
  }
}

Read more about how policies work