AWS Web Identity Token

The AWS Web Identity Token method authenticates agents using AWS IAM Outbound Identity Federation. The agent exchanges its IAM role credentials for a short-lived JWT; the Trust Domain Server verifies the JWT using the AWS account's OIDC discovery endpoint.

This method works for any AWS workload with an IAM role — EC2 instances, Lambda functions, ECS tasks, EKS pods — and produces attribute-rich claims from the role's identity and tags.

Attributes available for SVID issuance

The following attributes are produced. All have the origin aws_token.

Attribute	Description
aws_token.account.id	AWS account ID
aws_token.org.id	AWS organization ID
aws_token.source_region	AWS region where the token was requested
aws_token.identity_store_user_id	IAM Identity Center user ID associated with the session (if applicable)
aws_token.principal_tags.<TAG_NAME>	Value of principal tag TAG_NAME from the JWT
aws_token.request_tags.<TAG_NAME>	Value of request tag TAG_NAME from the JWT

Example SPIFFE ID template using principal tags:

/aws/{{aws_token.account.id}}/{{aws_token.principal_tags.environment}}

Prerequisites

AWS IAM Outbound Identity Federation must be enabled in the AWS account where agents run. Navigate to IAM > Account settings > Outbound Identity Federation and click Enable.

Once enabled, you will see the Issuer URL needed for server configuration in the console.

The IAM role used by the agent must have the following permission:

{
  "Effect": "Allow",
  "Action": "sts:GetWebIdentityToken",
  "Resource": "*"
}

How to Deploy

Step 1 — Update cluster configuration

Configure the AgentAttestation policy with the issuer URL from your AWS account's outbound federation configuration:

section: AgentAttestation
schema: v1
spec:
  policies:
    - name: aws_policy
      requiredAttestors:
        - type: aws_token
          config:
            issuerURLs:
              - "https://a1e777e5-1234-5678-9bf8-cdda2afef4bb.tokens.sts.global.api.aws"
            allowedAudiences:
              - urn:defakto:security:server
            allowedPrincipalTags:
              environment:
                - production
            allowedRequestTags:
              classification:
                - sensitive

Apply it using spirlctl:

spirlctl config set cluster --id <cluster-id> attestation-policy.yaml

Or using Terraform:

resource "spirl_cluster_config" "agent_attestation" {
  cluster_id = spirl_cluster.my_cluster.id
  sections = {
    AgentAttestation = <<-YAML
      section: AgentAttestation
      schema: v1
      spec:
        policies:
          - name: aws_policy
            requiredAttestors:
              - type: aws_token
                config:
                  issuerURLs:
                    - "https://a1e777e5-1234-5678-9bf8-cdda2afef4bb.tokens.sts.global.api.aws"
                  allowedAudiences:
                    - urn:defakto:security:server
                  allowedPrincipalTags:
                    environment:
                      - production
    YAML
  }
}

Once a configuration document passes validation and is stored, the Defakto control plane syncs it to your Trust Domain Servers automatically. No server or agent restart is required.

Server Configuration Reference

Field	Required	Default	Description
issuerURLs	Yes	—	List of AWS-issued OIDC issuer URLs. Matched against the iss claim in the JWT.
allowedAudiences	No	urn:defakto:security:server	Allowed token audiences (aud claim).
allowedPrincipalTags	No	—	Allowed values by tag key from the token's principal_tags section.
allowedRequestTags	No	—	Allowed values by tag key from the token's request_tags section.

Step 2 — Configure the Agent

Helm Installation

agent:
  auth:
    clusterId: c-xxxxxx
    attestors:
      - type: aws_token
        config:
          audience: urn:defakto:security:server  # defaults to urn:defakto:security:server
          signingAlgorithm: ES384                # ES384 or RS256; defaults to ES384
          requestTags:
            classification: sensitive

Linux Installation

cluster-id: c-xxxxxx
agent-attestors:
  - type: aws_token
    config:
      audience: urn:defakto:security:server
      signingAlgorithm: ES384
      requestTags:
        classification: sensitive

Agent Configuration Reference

Field	Default	Description
audience	urn:defakto:security:server	Audience value (aud) to include when calling GetWebIdentityToken. Must match server's allowedAudiences.
signingAlgorithm	ES384	JWT signing algorithm. Supported values: ES384, RS256.
requestTags	—	Map of tag key-value pairs included as request_tags claims in the JWT.

Step 3 — Verify

Server logs — look for these in order:

1. "Login started with multi-attestation support" — confirms the agent offered providedMethods: ["aws_token"]
2. "Authorization received and verified" — includes agentAttestationAttributes with the token claims:

   {
     "msg": "Authorization received and verified",
     "agentAttestationAttributes": [
       "aws_token:aws_token.account.id=\"123456789012\"",
       "aws_token:aws_token.org.id=\"o-xxxxxxxxxxxx\"",
       "aws_token:aws_token.source_region=\"us-east-1\""
     ]
   }

3. "Connected to agent" — session is fully established

Agent logs — enable debug logging to see "Sending Login" with attestors: ["aws_token"]. At the default log level, "Connected to server" confirms the session is live.

Metrics — confirm proofs are succeeding:

spirl_attestation_signer.proof{attestor_type="aws_token",outcome="success"}
spirl_attestation_agent.proof{attestor_type="aws_token",outcome="success"}

Alert on outcome="failed" to detect token validation failures.

Common errors:

Error	Likely cause
no cluster policy authorizes the provided attestors	Agent's aws_token method doesn't match any policy — verify issuerURLs in the cluster config matches your account's outbound federation URL
Attestor rejected proof, policy failed	Token claims (audience, principal tags, or request tags) don't satisfy the configured allowedAudiences, allowedPrincipalTags, or allowedRequestTags
OutboundWebIdentityFederationDisabledException in agent logs	AWS Outbound Identity Federation is not enabled in IAM Account settings

Security Considerations

• Each token is short-lived and tied to the agent's IAM role identity. Tokens cannot be replayed beyond their expiry.
• Use allowedPrincipalTags and allowedRequestTags to enforce that only agents with specific IAM tags can authenticate. This is the primary access control mechanism for this method.
• The allowedAudiences constraint prevents tokens issued for other services from being used to authenticate to the Trust Domain Server.

Troubleshooting

OutboundWebIdentityFederationDisabledException in agent logs — Outbound Identity Federation is not enabled in the AWS account. Enable it in IAM > Account settings.

Agent can obtain a proof — Enable debug logging on the agent to see the actual JWT being sent. This helps diagnose audience mismatches or tag filtering issues.