Skip to content

Support cross AWS account IAM role authentication#979

Merged
pditommaso merged 34 commits intomasterfrom
001-cross-account-iam-role-auth
Mar 9, 2026
Merged

Support cross AWS account IAM role authentication#979
pditommaso merged 34 commits intomasterfrom
001-cross-account-iam-role-auth

Conversation

@munishchouhan
Copy link
Member

@munishchouhan munishchouhan commented Feb 11, 2026

Summary

  • Add support for AWS IAM role assumption (STS AssumeRole) when authenticating to ECR registries, enabling cross-account container image access
  • When Tower credentials contain an assumeRoleArn instead of static AWS keys, Wave now assumes that role via STS to obtain temporary ECR credentials
  • Support optional jump role chaining (wave.aws.jump-role-arn) for cross-account access where Wave first assumes an intermediary role, then uses those credentials to assume the target role
  • Cache STS temporary credentials and ECR auth tokens with TTL derived from STS credential expiration (5-minute refresh buffer)
  • Retry transient STS errors (5xx, throttling) with exponential backoff via configurable StsClientConfig
  • Handle ExpiredTokenException on the jump role path by bypassing cache and retrying with fresh credentials
  • Map STS exceptions to user-friendly error messages

Key Changes

Production code:

  • build.gradle — Promote software.amazon.awssdk:sts from runtimeOnly to implementation
  • ContainerRegistryKeys.groovy — Parse assumeRoleArn/externalId from Tower AWS credentials (previously logged a warning and returned null)
  • AwsEcrService.groovy — Add role ARN detection, STS AssumeRole with jump role chaining, credential caching, retry, and error mapping
  • StsClientConfig.groovy — New configurable retry settings for STS calls (wave.aws.sts.retry.*)
  • AwsRoleCache.groovy — New tiered cache for jump role temporary credentials
  • AwsStsCredentials.groovy — Serializable wrapper for STS credentials (cache value)

Documentation:

  • docs/configuration.md — Added configuration docs for cross-account role chaining, STS retry, and jump role cache
  • CLAUDE.md — Added WAVE_AWS_JUMP_ROLE_ARN/WAVE_AWS_JUMP_EXTERNAL_ID environment variables

Design docs:

  • specs/001-cross-account-iam-role-auth/ — Spec, plan, tasks, research, data model, service interface, and STS integration contracts

Tests:

  • AwsEcrServiceTest.groovy — ~895 lines covering role detection, assume role flows, caching, retry, error mapping
  • ContainerRegistryKeysTest.groovy — 304 lines covering assume role credential parsing

Configuration

New properties:

  • wave.aws.jump-role-arn — Optional intermediary role ARN for cross-account chaining
  • wave.aws.jump-external-id — Optional external ID for the jump role
  • wave.aws.jump-role-cache.duration — Jump role cache TTL (default: 45m)
  • wave.aws.jump-role-cache.max-size — Maximum cache entries for jump role credentials (default: 100)
  • wave.aws.sts.retry.delay / maxDelay / attempts / multiplier / jitter — STS retry tuning

Test Plan

  • Verify static AWS credentials flow still works (backward compatible)
  • Test role ARN detection with standard, GovCloud (aws-us-gov), and China (aws-cn) partitions
  • Test jump role chaining: Wave default creds → jump role → target role → ECR token
  • Test direct role assumption (no jump role configured)
  • Verify ExpiredTokenException retry bypasses jump role cache
  • Verify STS transient error retry with backoff
  • Verify ECR auth token cache TTL respects STS credential expiration minus 5-min buffer

Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
@munishchouhan munishchouhan self-assigned this Feb 11, 2026
@munishchouhan munishchouhan marked this pull request as draft February 11, 2026 12:04
@munishchouhan munishchouhan marked this pull request as ready for review February 13, 2026 16:29
@munishchouhan

This comment was marked as outdated.

@claude

This comment was marked as outdated.

@munishchouhan

This comment was marked as outdated.

@munishchouhan

This comment was marked as outdated.

@claude

This comment was marked as outdated.

@munishchouhan

This comment was marked as outdated.

Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
@munishchouhan

This comment was marked as off-topic.

@claude

This comment was marked as off-topic.

Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
munishchouhan and others added 2 commits March 6, 2026 14:32
Signed-off-by: munishchouhan <hrma017@gmail.com>
@munishchouhan

This comment was marked as off-topic.

@claude

This comment was marked as outdated.

@munishchouhan

This comment was marked as outdated.

@munishchouhan
Copy link
Member Author

@pditommaso, changes have been made as per review
please review again

pditommaso and others added 2 commits March 9, 2026 15:57
…#991)

* Refactor AwsCreds to use separate fields for role-based and static credential flows

Replace overloaded accessKey/secretKey fields with dedicated roleArn/externalId fields
for role-based auth, add factory methods (ofRole, ofKeys), and preserve backward-compatible
cache hash for static credentials.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update spec and plan docs to reflect AwsCreds refactor with separate fields

Align plan.md, service-interface.md, and data-model.md with the refactored
AwsCreds that uses dedicated roleArn/externalId fields and ofRole()/ofKeys()
factory methods instead of overloading accessKey/secretKey.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* updated specs

Signed-off-by: munishchouhan <hrma017@gmail.com>

* Renamed AwsJumpRoleCache → AwsRoleCache

Signed-off-by: munishchouhan <hrma017@gmail.com>

* fixed AwsEcrServiceTest

Signed-off-by: munishchouhan <hrma017@gmail.com>

---------

Signed-off-by: munishchouhan <hrma017@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: munishchouhan <hrma017@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: munishchouhan <hrma017@gmail.com>
@munishchouhan
Copy link
Member Author

@pditommaso This PR contains unverified commits, So i cannot merge it, please ,erge it
I did the final testing and aws creds are working fine

@pditommaso pditommaso changed the title Support cross aws account iam role authetication Support cross AWS account IAM role authentication Mar 9, 2026
@pditommaso pditommaso merged commit d59370c into master Mar 9, 2026
@pditommaso pditommaso deleted the 001-cross-account-iam-role-auth branch March 9, 2026 16:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants