Skip to content

docs: Add PRD for browser-based auth in aws/user identity#1887

Merged
Benbentwo merged 17 commits intomainfrom
feature/dev-3829-add-browser-based-auth-flow-for-root-and-iam-identities
Mar 4, 2026
Merged

docs: Add PRD for browser-based auth in aws/user identity#1887
Benbentwo merged 17 commits intomainfrom
feature/dev-3829-add-browser-based-auth-flow-for-root-and-iam-identities

Conversation

@Benbentwo
Copy link
Member

@Benbentwo Benbentwo commented Dec 17, 2025

what

Add Product Requirements Document for enhancing the aws/user identity with browser-based OAuth2 authentication as a fallback credential source.

  • Extends existing aws/user identity (NOT a new provider type)
  • Three-tier credential resolution: YAML → Keychain → Browser webflow
  • Zero-config authentication using AWS console credentials
  • Supports headless/remote mode for servers without browsers
  • Native SDK implementation (no AWS CLI dependency)

why

DEV-3829 tracks the implementation of browser-based authentication. This approach:

  • Provides seamless fallback when no static credentials configured
  • Maintains backward compatibility with existing configurations
  • Eliminates need for long-term IAM access keys
  • Enables zero-config onboarding for new users

references

Summary by CodeRabbit

  • New Features

    • Browser-based OAuth2 (PKCE) fallback for aws/user enabling interactive and headless remote authentication when no static credentials are present.
  • Documentation

    • New product requirements and user-facing docs covering overview, user journeys, credential lifecycle, configuration examples, security, testing, rollout, and success metrics.
  • Roadmap

    • Planned milestone added for browser-based OAuth2 auth (Q1 2026).

@Benbentwo Benbentwo requested a review from a team as a code owner December 17, 2025 21:56
@github-actions github-actions bot added the size/m Medium size PR label Dec 17, 2025
@github-actions
Copy link

github-actions bot commented Dec 17, 2025

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

@codecov
Copy link

codecov bot commented Dec 17, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.61%. Comparing base (7091aa6) to head (c07ccd0).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #1887      +/-   ##
==========================================
+ Coverage   76.59%   76.61%   +0.01%     
==========================================
  Files         832      832              
  Lines       79524    79524              
==========================================
+ Hits        60914    60925      +11     
+ Misses      14814    14806       -8     
+ Partials     3796     3793       -3     
Flag Coverage Δ
unittests 76.61% <ø> (+0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Dec 17, 2025

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds a new PRD documenting browser-based OAuth2 (PKCE) fallback for the aws/user identity and inserts a planned roadmap milestone for that feature. Changes are documentation-only; no source code or tests were modified in this diff.

Changes

Cohort / File(s) Summary
PRD / Product docs
docs/prd/aws-browser-auth.md
New PRD describing browser-based OAuth2 PKCE fallback for aws/user: status, problem statement, user stories (US-1..US-5), full OAuth2 webflow (PKCE, endpoints, callback/actions), credential lifecycle, CloudTrail events, requirements, config schema, UX (interactive & headless), implementation approach, testing, rollout, metrics, and open questions.
Website / Roadmap
website/src/data/roadmap.js
Adds planned milestone "Browser-based OAuth2 fallback for aws/user" (q1-2026, PR #1887) to the Unified Authentication roadmap.
Docs references (not changed here)
website/docs/.../aws-user.mdx, website/docs/.../auth/login.mdx
PRD calls out documentation updates and integration points for existing guides (no edits to these files in this diff).

Sequence Diagram(s)

sequenceDiagram
    participant CLI as CLI/Agent
    participant Browser as Browser
    participant Auth as OAuth2 Authorization Server
    participant Callback as Local Callback Listener
    participant STS as AWS STS
    CLI->>Browser: open auth URL (PKCE + state)
    Browser->>Auth: user authenticates & consents
    Auth->>Browser: redirect to localhost callback with code
    Browser->>Callback: deliver authorization code
    Callback->>CLI: forward code
    CLI->>Auth: exchange code + PKCE_verifier for tokens
    Auth-->>CLI: return ID token / access token
    CLI->>STS: AssumeRoleWithWebIdentity / exchange token for AWS creds
    STS-->>CLI: return short-lived AWS credentials
Loading

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Suggested reviewers

  • osterman
  • aknysh
🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the primary change: adding a PRD document for browser-based authentication in the aws/user identity.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch feature/dev-3829-add-browser-based-auth-flow-for-root-and-iam-identities

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

coderabbitai[bot]
coderabbitai bot previously approved these changes Dec 17, 2025
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Nitpick comments (1)
docs/prd/aws-browser-auth.md (1)

165-165: Defer fenced code block language tags to documentation cleanup.

Static analysis flagged three fenced code blocks missing language specifications (MD040) at lines 165, 189, and 245. These are valid but low-priority style issues. Per established learnings, markdownlint formatting issues should be addressed in a separate documentation cleanup commit to avoid blocking this PR.

Also applies to: 189-189, 245-245

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

  • Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between d3e7503 and a9544f7.

📒 Files selected for processing (1)
  • docs/prd/aws-browser-auth.md (1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
docs/prd/**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

All Product Requirement Documents (PRDs) MUST be placed in docs/prd/ with kebab-case filenames

Files:

  • docs/prd/aws-browser-auth.md
🧠 Learnings (4)
📓 Common learnings
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-16T18:20:55.614Z
Learning: Applies to docs/prd/**/*.md : All Product Requirement Documents (PRDs) MUST be placed in docs/prd/ with kebab-case filenames
📚 Learning: 2025-11-10T20:03:56.875Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1775
File: pkg/auth/providers/aws/sso_provisioning.go:40-79
Timestamp: 2025-11-10T20:03:56.875Z
Learning: In the Atmos AWS SSO provider (pkg/auth/providers/aws/sso_provisioning.go), the OAuth access token from the AWS SSO device flow is intentionally stored in the `AccessKeyID` field of `AWSCredentials` during authentication. This token is then extracted and used for ListAccounts and ListAccountRoles API calls during identity provisioning. This design reuses the existing `AWSCredentials` type for token transport rather than creating a separate credential type.

Applied to files:

  • docs/prd/aws-browser-auth.md
📚 Learning: 2025-04-25T20:54:19.701Z
Learnt from: mcalhoun
Repo: cloudposse/atmos PR: 963
File: website/docs/core-concepts/projects/configuration/stores.mdx:286-286
Timestamp: 2025-04-25T20:54:19.701Z
Learning: For the AWS SSM Parameter Store implementation in Atmos, support for `read_role_arn` and `write_role_arn` options is essential to enable cross-account access, allowing users to run operations like `terraform plan` in multiple accounts while accessing values across keystores. Azure Key Vault would need similar capabilities for cross-tenant/subscription authentication.

Applied to files:

  • docs/prd/aws-browser-auth.md
📚 Learning: 2025-12-13T06:07:34.794Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: docs/prd/tool-dependencies-integration.md:58-64
Timestamp: 2025-12-13T06:07:34.794Z
Learning: For docs in the cloudposse/atmos repository under docs/prd/, markdownlint issues MD040, MD010, and MD034 should be deferred to a separate documentation cleanup commit and must not block the current PR. If needed, address these issues in a follow-up PR dedicated to documentation improvements.

Applied to files:

  • docs/prd/aws-browser-auth.md
🪛 LanguageTool
docs/prd/aws-browser-auth.md

[grammar] ~255-~255: Ensure spelling is correct
Context: ...ack 6. Exchange code for tokens via AWS signin service 7. Use tokens to obtain tempora...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)
docs/prd/aws-browser-auth.md

165-165: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


189-189: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


245-245: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
  • GitHub Check: Acceptance Tests (windows)
  • GitHub Check: Summary
🔇 Additional comments (1)
docs/prd/aws-browser-auth.md (1)

1-337: Strong alignment with past feedback on SDK-native implementation approach.

This PRD comprehensively addresses DEV-3829 objectives. I particularly appreciate that lines 236-272 recommend native AWS SDK integration and explicitly reject the CLI wrapper approach—this directly addresses the prior feedback to integrate with SDK support rather than shell out to the AWS CLI.

The structure is solid: user stories cover the full scope (IAM, root, federated, headless, role chaining), technical details are precise, requirements are well-prioritized, configuration examples are practical, and both interactive and headless UX flows are documented. Security considerations and testing strategy round things out nicely.

coderabbitai[bot]
coderabbitai bot previously approved these changes Dec 17, 2025
@Benbentwo Benbentwo changed the title docs: Add PRD for aws/login provider docs: Add PRD for aws/login provider (native SDK auth) Dec 18, 2025
@Benbentwo Benbentwo added the no-release Do not create a new release (wait for additional code changes) label Dec 18, 2025
@osterman
Copy link
Member

I’m leaning toward modeling this differently.

The problem is aws/login doesn’t represent who you are — it’s just a web-based authentication flow that mints STS credentials for an existing AWS identity (root or IAM user). Right now it’s implicitly carrying both “how I authenticate” and “who I become,” which is where the confusion comes from.

Instead, I think we should make the split explicit:

  • Introduce aws/root as a first-class identity (alongside aws/user)
  • Treat web login as an authentication method, not an identity (E.g. we could add credential processes as a method)
  • Have aws/user and aws/root declare how they authenticate (e.g. via web flow)

This gives us a cleaner and more accurate model:

  • Identities = who you are (root, IAM user, assumed role)
  • Auth methods = how you authenticate (web login, SSO, SAML, static keys)

Example: IAM User via Web Login (Break-Glass User)

auth:
  methods:
    web: # this is just an arbitrary name
      kind: aws/login
      region: us-east-1

  identities:
    breakglass-user:
      kind: aws/user
      principal_arn: arn:aws:iam::123456789012:user/developer
      via:
        method: web

Example: Root Access via Web Login (Break-Glass)

auth:
  methods:
    console:
      kind: aws/login
      region: us-east-1

  identities:
    root-breakglass:
      kind: aws/root
      account_id: "123456789012"
      via:
        method: console

Example: Role Assumption from Break-Glass User

auth:
  identities:
    prod-admin:
      kind: aws/assume-role
      via:
        identity: breakglass-user
      principal:
        role_arn: arn:aws:iam::123456789012:role/AdminRole

This keeps aws/login focused on what it actually does — obtaining STS credentials via a browser flow — while making identities explicit and giving us a clear place to add root-specific guardrails and UX later.

Happy to bikeshed naming, but I think this separation makes the model both safer and easier to reason about long-term.

@Benbentwo
Copy link
Member Author

I’m leaning toward modeling this differently.

The problem is aws/login doesn’t represent who you are — it’s just a web-based authentication flow that mints STS credentials for an existing AWS identity (root or IAM user). Right now it’s implicitly carrying both “how I authenticate” and “who I become,” which is where the confusion comes from.

Instead, I think we should make the split explicit:

  • Introduce aws/root as a first-class identity (alongside aws/user)
  • Treat web login as an authentication method, not an identity (E.g. we could add credential processes as a method)
  • Have aws/user and aws/root declare how they authenticate (e.g. via web flow)

This gives us a cleaner and more accurate model:

  • Identities = who you are (root, IAM user, assumed role)
  • Auth methods = how you authenticate (web login, SSO, SAML, static keys)

Example: IAM User via Web Login (Break-Glass User)

auth:
  methods:
    web: # this is just an arbitrary name
      kind: aws/login
      region: us-east-1

  identities:
    breakglass-user:
      kind: aws/user
      principal_arn: arn:aws:iam::123456789012:user/developer
      via:
        method: web

Example: Root Access via Web Login (Break-Glass)

auth:
  methods:
    console:
      kind: aws/login
      region: us-east-1

  identities:
    root-breakglass:
      kind: aws/root
      account_id: "123456789012"
      via:
        method: console

Example: Role Assumption from Break-Glass User

auth:
  identities:
    prod-admin:
      kind: aws/assume-role
      via:
        identity: breakglass-user
      principal:
        role_arn: arn:aws:iam::123456789012:role/AdminRole

This keeps aws/login focused on what it actually does — obtaining STS credentials via a browser flow — while making identities explicit and giving us a clear place to add root-specific guardrails and UX later.

Happy to bikeshed naming, but I think this separation makes the model both safer and easier to reason about long-term.

Frankly, I agree. I think this is a login type. My only concern is that we're adding too many different major headers, methods, identities, providers. I realize that's not many right now, but I don't see methods being used a whole lot. Perhaps we could embed the method of AWS login to be the default unless hardcoded credentials are used. Meaning the flow would b. First check if there's an environment block, such as AWS Credentials Key and AWS Secret Access Key. Then, if not, check if the credential store has something set for the user. Finally, if nothing is provided, use the AWS login flow. For root users, I think this is just the default.

@Benbentwo Benbentwo changed the title docs: Add PRD for aws/login provider (native SDK auth) docs: Add PRD for browser-based auth in aws/user identity Dec 23, 2025
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Nitpick comments (1)
docs/prd/aws-browser-auth.md (1)

319-319: Minor: Standardize AWS terminology for "sign-in".

Line 319 uses "signin service"; AWS conventionally hyphenates this as "sign-in" (e.g., AWS Sign-In service). Update for consistency: "Exchange code for tokens via AWS sign-in service".

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

  • Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between a9544f7 and bac89ee.

📒 Files selected for processing (1)
  • docs/prd/aws-browser-auth.md
🧰 Additional context used
📓 Path-based instructions (1)
docs/prd/**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

All Product Requirement Documents (PRDs) MUST be placed in docs/prd/ with kebab-case filenames

Files:

  • docs/prd/aws-browser-auth.md
🧠 Learnings (3)
📓 Common learnings
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-16T18:20:55.630Z
Learning: Applies to docs/prd/**/*.md : All Product Requirement Documents (PRDs) MUST be placed in docs/prd/ with kebab-case filenames
📚 Learning: 2025-11-10T20:03:56.875Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1775
File: pkg/auth/providers/aws/sso_provisioning.go:40-79
Timestamp: 2025-11-10T20:03:56.875Z
Learning: In the Atmos AWS SSO provider (pkg/auth/providers/aws/sso_provisioning.go), the OAuth access token from the AWS SSO device flow is intentionally stored in the `AccessKeyID` field of `AWSCredentials` during authentication. This token is then extracted and used for ListAccounts and ListAccountRoles API calls during identity provisioning. This design reuses the existing `AWSCredentials` type for token transport rather than creating a separate credential type.

Applied to files:

  • docs/prd/aws-browser-auth.md
📚 Learning: 2025-12-13T06:07:34.794Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: docs/prd/tool-dependencies-integration.md:58-64
Timestamp: 2025-12-13T06:07:34.794Z
Learning: For docs in the cloudposse/atmos repository under docs/prd/, markdownlint issues MD040, MD010, and MD034 should be deferred to a separate documentation cleanup commit and must not block the current PR. If needed, address these issues in a follow-up PR dedicated to documentation improvements.

Applied to files:

  • docs/prd/aws-browser-auth.md
🪛 LanguageTool
docs/prd/aws-browser-auth.md

[grammar] ~319-~319: Ensure spelling is correct
Context: ...ack 6. Exchange code for tokens via AWS signin service 7. Return temporary AWS credent...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)
docs/prd/aws-browser-auth.md

181-181: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


210-210: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


232-232: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


309-309: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
  • GitHub Check: Acceptance Tests (windows)
  • GitHub Check: Summary
🔇 Additional comments (3)
docs/prd/aws-browser-auth.md (3)

97-97: Clarify requirement FR-4: AWS CLI version validation appears misaligned with native SDK approach.

FR-4 specifies validating "AWS CLI version >= 2.32.0" as P0, but NFR-1 (line 107) states "Native SDK implementation (no AWS CLI dependency)" as P0, and the implementation approach (line 326) explicitly avoids external AWS CLI dependency. Why validate AWS CLI version if it's not a dependency?

Either remove FR-4 or clarify its purpose. If it exists for environment checks unrelated to the actual OAuth2 flow, document that clearly.

Also applies to: 107-107


1-392: PRD is well-structured and comprehensive.

The document clearly articulates the problem, proposes a focused solution (webflow fallback for existing aws/user identity), provides concrete user stories, configuration examples, and a phased rollout plan. It appropriately emphasizes native SDK implementation without AWS CLI dependency and aligns with the PR objectives to integrate webflow as a credential resolution fallback rather than introducing a separate provider type.


181-181: Note: Deferred markdownlint MD040 issues for future documentation cleanup.

Several fenced code blocks (lines 181, 210, 232, 309) lack language specifications. Per learnings, markdownlint issues MD040 and related formatting concerns should be deferred to a separate documentation cleanup commit and do not block the current PR. These can be addressed in a follow-up.

Also applies to: 210-210, 232-232, 309-309

coderabbitai[bot]
coderabbitai bot previously approved these changes Dec 23, 2025
Benbentwo added a commit that referenced this pull request Dec 29, 2025
Add planned milestone for OAuth2 browser authentication as fallback
for aws/user identity (PR #1887) to the auth initiative roadmap.

🤖 Generated with Claude Code

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
@Benbentwo Benbentwo force-pushed the feature/dev-3829-add-browser-based-auth-flow-for-root-and-iam-identities branch from bac89ee to 7d8d582 Compare December 29, 2025 17:46
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
docs/prd/aws-browser-auth.md (1)

64-87: Clarify that this describes the OAuth2 flow we'll implement natively.

The section title "AWS Login OAuth2 Flow" and line 68 stating "The aws login command uses OAuth 2.0..." could be misinterpreted as planning to shell out to the AWS CLI. Given NFR-1 explicitly requires "Native SDK implementation (no AWS CLI dependency)", consider rewording to clarify we're implementing this OAuth2 flow ourselves using the AWS SDK.

🔎 Suggested clarification
-### AWS Login OAuth2 Flow
+### OAuth2 Flow (Native SDK Implementation)

-The `aws login` command uses OAuth 2.0 Authorization Code flow with PKCE:
+AWS browser-based authentication uses OAuth 2.0 Authorization Code flow with PKCE (we'll implement this natively via AWS SDK, not the AWS CLI):
📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

  • Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between bac89ee and 7d8d582.

📒 Files selected for processing (2)
  • docs/prd/aws-browser-auth.md
  • website/src/data/roadmap.js
🧰 Additional context used
📓 Path-based instructions (3)
website/**

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

website/**: Update website documentation in the website/ directory when adding new features, ensure consistency between CLI help text and website documentation, and follow the website's documentation structure and style
Keep website code in the website/ directory, follow the existing website architecture and style, and test website changes locally before committing
Keep CLI documentation and website documentation in sync and document new features on the website with examples and use cases

Files:

  • website/src/data/roadmap.js
website/src/data/roadmap.js

📄 CodeRabbit inference engine (CLAUDE.md)

PRs labeled minor/major MUST update website/src/data/roadmap.js with shipped milestones, changelog links, PR numbers, and updated initiative progress percentages

Files:

  • website/src/data/roadmap.js
docs/prd/**

📄 CodeRabbit inference engine (CLAUDE.md)

All Product Requirement Documents (PRDs) MUST be placed in docs/prd/ with kebab-case filenames

Files:

  • docs/prd/aws-browser-auth.md
🧠 Learnings (4)
📓 Common learnings
Learnt from: Listener430
Repo: cloudposse/atmos PR: 1149
File: internal/exec/go_getter_utils.go:263-264
Timestamp: 2025-03-25T12:24:36.177Z
Learning: Tests for the default Bitbucket username fallback to "x-token-auth" will be added during a future refactoring phase rather than in this PR.
📚 Learning: 2025-12-26T06:31:02.259Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-26T06:31:02.259Z
Learning: Applies to website/src/data/roadmap.js : PRs labeled minor/major MUST update website/src/data/roadmap.js with shipped milestones, changelog links, PR numbers, and updated initiative progress percentages

Applied to files:

  • website/src/data/roadmap.js
📚 Learning: 2025-11-10T20:03:56.875Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1775
File: pkg/auth/providers/aws/sso_provisioning.go:40-79
Timestamp: 2025-11-10T20:03:56.875Z
Learning: In the Atmos AWS SSO provider (pkg/auth/providers/aws/sso_provisioning.go), the OAuth access token from the AWS SSO device flow is intentionally stored in the `AccessKeyID` field of `AWSCredentials` during authentication. This token is then extracted and used for ListAccounts and ListAccountRoles API calls during identity provisioning. This design reuses the existing `AWSCredentials` type for token transport rather than creating a separate credential type.

Applied to files:

  • docs/prd/aws-browser-auth.md
📚 Learning: 2025-12-13T06:07:34.794Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: docs/prd/tool-dependencies-integration.md:58-64
Timestamp: 2025-12-13T06:07:34.794Z
Learning: For docs in the cloudposse/atmos repository under docs/prd/, markdownlint issues MD040, MD010, and MD034 should be deferred to a separate documentation cleanup commit and must not block the current PR. If needed, address these issues in a follow-up PR dedicated to documentation improvements.

Applied to files:

  • docs/prd/aws-browser-auth.md
🪛 LanguageTool
docs/prd/aws-browser-auth.md

[grammar] ~319-~319: Ensure spelling is correct
Context: ...ack 6. Exchange code for tokens via AWS signin service 7. Return temporary AWS credent...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)
docs/prd/aws-browser-auth.md

181-181: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


210-210: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


232-232: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


309-309: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
  • GitHub Check: Acceptance Tests (windows)
  • GitHub Check: Summary
🔇 Additional comments (3)
website/src/data/roadmap.js (1)

134-134: LGTM! Milestone entry correctly added.

The new planned milestone for browser-based authentication follows the established pattern and accurately reflects the feature described in the PRD. Status, quarter, PR reference, and benefits are all appropriate.

docs/prd/aws-browser-auth.md (2)

276-327: Implementation approach looks solid.

The technical implementation correctly emphasizes native SDK integration with no AWS CLI dependency. The webflow.go approach with OAuth2 PKCE flow, local callback server, and credential caching follows established atmos auth patterns. Good reuse of existing authentication infrastructure.


1-391: Comprehensive PRD with clear requirements and rollout plan.

The PRD effectively documents the browser-based authentication feature, including user stories, technical details, security considerations, and testing strategy. The three-tier credential resolution (YAML → Keychain → Browser) is clearly explained, and the fallback approach maintains backward compatibility with existing configurations.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
docs/prd/aws-browser-auth.md (1)

180-180: Fenced code blocks should specify language (MD040).

Lines 180, 209, 231, and 308 have fenced code blocks without a language identifier. Per established learnings, these markdownlint issues (MD040, MD010, MD034) should be addressed in a separate documentation cleanup commit rather than blocking this PR.

Also applies to: 209-209, 231-231, 308-308

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

  • Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 7d8d582 and 907205e.

📒 Files selected for processing (1)
  • docs/prd/aws-browser-auth.md
🧰 Additional context used
📓 Path-based instructions (1)
docs/prd/**

📄 CodeRabbit inference engine (CLAUDE.md)

All Product Requirement Documents (PRDs) MUST be placed in docs/prd/ with kebab-case filenames

Files:

  • docs/prd/aws-browser-auth.md
🧠 Learnings (4)
📓 Common learnings
Learnt from: Listener430
Repo: cloudposse/atmos PR: 1149
File: internal/exec/go_getter_utils.go:263-264
Timestamp: 2025-03-25T12:24:36.177Z
Learning: Tests for the default Bitbucket username fallback to "x-token-auth" will be added during a future refactoring phase rather than in this PR.
📚 Learning: 2025-11-10T20:03:56.875Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1775
File: pkg/auth/providers/aws/sso_provisioning.go:40-79
Timestamp: 2025-11-10T20:03:56.875Z
Learning: In the Atmos AWS SSO provider (pkg/auth/providers/aws/sso_provisioning.go), the OAuth access token from the AWS SSO device flow is intentionally stored in the `AccessKeyID` field of `AWSCredentials` during authentication. This token is then extracted and used for ListAccounts and ListAccountRoles API calls during identity provisioning. This design reuses the existing `AWSCredentials` type for token transport rather than creating a separate credential type.

Applied to files:

  • docs/prd/aws-browser-auth.md
📚 Learning: 2025-04-25T20:54:19.701Z
Learnt from: mcalhoun
Repo: cloudposse/atmos PR: 963
File: website/docs/core-concepts/projects/configuration/stores.mdx:286-286
Timestamp: 2025-04-25T20:54:19.701Z
Learning: For the AWS SSM Parameter Store implementation in Atmos, support for `read_role_arn` and `write_role_arn` options is essential to enable cross-account access, allowing users to run operations like `terraform plan` in multiple accounts while accessing values across keystores. Azure Key Vault would need similar capabilities for cross-tenant/subscription authentication.

Applied to files:

  • docs/prd/aws-browser-auth.md
📚 Learning: 2025-12-13T06:07:34.794Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: docs/prd/tool-dependencies-integration.md:58-64
Timestamp: 2025-12-13T06:07:34.794Z
Learning: For docs in the cloudposse/atmos repository under docs/prd/, markdownlint issues MD040, MD010, and MD034 should be deferred to a separate documentation cleanup commit and must not block the current PR. If needed, address these issues in a follow-up PR dedicated to documentation improvements.

Applied to files:

  • docs/prd/aws-browser-auth.md
🪛 LanguageTool
docs/prd/aws-browser-auth.md

[grammar] ~318-~318: Ensure spelling is correct
Context: ...ack 6. Exchange code for tokens via AWS signin service 7. Return temporary AWS credent...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)
docs/prd/aws-browser-auth.md

180-180: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


209-209: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


231-231: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


308-308: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
  • GitHub Check: Acceptance Tests (windows)
  • GitHub Check: Summary
🔇 Additional comments (1)
docs/prd/aws-browser-auth.md (1)

1-390: Comprehensive PRD addressing browser-based OAuth2 fallback for aws/user identity.

The document is well-structured and covers technical details, security, user experience, and rollout planning thoroughly. It clearly articulates the problem (users without static credentials stuck with configuration friction), the solution (three-tier fallback: YAML → keychain → browser webflow), and implementation path. Configuration examples and UX flows (both interactive and headless) are practical and clear. The reference to native SDK implementation and security considerations around PKCE and short-lived credentials are solid.

coderabbitai[bot]
coderabbitai bot previously approved these changes Jan 2, 2026
@mergify
Copy link

mergify bot commented Jan 2, 2026

💥 This pull request now has conflicts. Could you fix it @Benbentwo? 🙏

@mergify mergify bot added the conflict This PR has conflicts label Jan 2, 2026
@Benbentwo
Copy link
Member Author

@coderabbitai full review

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Feb 23, 2026

✅ Actions performed

Full review triggered.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
website/src/data/roadmap.js (1)

175-175: ⚠️ Potential issue | 🟡 Minor

Stale PR title in prs[] doesn't match the milestone.

The title 'Add PRD for aws/login provider (native SDK auth)' no longer reflects what this PR delivers. The milestone on Line 165 correctly calls it "Browser-based authentication for aws/user" — the prs entry should match.

✏️ Proposed fix
-        { number: 1887, title: 'Add PRD for aws/login provider (native SDK auth)' },
+        { number: 1887, title: 'Add PRD for browser-based auth for aws/user identity' },
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@website/src/data/roadmap.js` at line 175, Update the stale PR title in the
prs array: find the PR object with number: 1887 and change its title from 'Add
PRD for aws/login provider (native SDK auth)' to match the milestone naming
"Browser-based authentication for aws/user" (or equivalent phrasing used in the
milestone at line ~165) so the prs[] entry reflects the actual deliverable.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/prd/aws-browser-auth.md`:
- Around line 111-130: The schema for the aws/user identity is missing the
credentials toggle introduced in Design Decision 2; add the webflow_enabled
boolean under the credentials block for the aws/user identity (e.g.,
credentials.webflow_enabled) with a default of false and document its purpose
and placement alongside region/access_key_id/secret_access_key/mfa_arn in the
"Configuration Schema" section; ensure examples and YAML snippet show
webflow_enabled: false and mention its optionality and default value.
- Around line 76-80: Update the "Credential Lifecycle" section to resolve the
conflict with Design Decision 1 and NFR-1 by clarifying that the
"~/.aws/login/cache" path (or AWS_LOGIN_CACHE_DIRECTORY) is not used by the
native SDK; state explicitly that webflow credentials are stored in the atmos
keychain per Design Decision 1 and that the CLI cache path is only relevant as
an optional, read-only compatibility tier for existing AWS CLI sessions (or
remove the CLI path entirely if stale). Mention "atmos keychain", "Design
Decision 1", and "NFR-1" in the sentence so implementers understand the
authoritative storage location and the optional/legacy nature of the CLI cache.
- Line 313: Update the note about redirect_uri to clarify that for loopback IPs
AWS's arn:aws:signin:::devtools/same-device client follows RFC 8252 and accepts
any ephemeral port at request time (so binding to 127.0.0.1:0 and interpolating
the OS-assigned port into redirect_uri is correct), but retain the guidance to
read back the assigned port and surface a clear, user-friendly error if
ephemeral binding fails (include a hint to check for port conflicts); reference
the terms redirect_uri, 127.0.0.1:0, and arn:aws:signin:::devtools/same-device
in the note so readers know this applies to the described flow.

---

Outside diff comments:
In `@website/src/data/roadmap.js`:
- Line 175: Update the stale PR title in the prs array: find the PR object with
number: 1887 and change its title from 'Add PRD for aws/login provider (native
SDK auth)' to match the milestone naming "Browser-based authentication for
aws/user" (or equivalent phrasing used in the milestone at line ~165) so the
prs[] entry reflects the actual deliverable.

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

  • Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 8fdf9b6 and 433f5b0.

📒 Files selected for processing (2)
  • docs/prd/aws-browser-auth.md
  • website/src/data/roadmap.js

- Add webflow_enabled field to configuration schema with default true
- Clarify credential storage uses atmos keychain (not AWS CLI cache),
  consistent with Design Decision 1 and NFR-1
- Add RFC 8252 Section 7.3 reference for loopback redirect_uri port
  acceptance
- Update stale PR title in roadmap prs array

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
coderabbitai[bot]
coderabbitai bot previously approved these changes Feb 23, 2026
Rework Overview and Problem Statement to explain the historical
limitation of IAM static credentials, AWS's recent introduction of
browser-based auth for IAM/root, and the gap in Atmos's aws/user
identity. Link to the AWS announcement blog post.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
coderabbitai[bot]
coderabbitai bot previously approved these changes Feb 24, 2026
@Benbentwo Benbentwo requested a review from osterman March 2, 2026 16:46
- Use XDG data directory for credential storage instead of ~/.aws path
- Label example configs as "Existing, Unaffected by Webflow"
- Replace --remote flag with existing --interactive=false global flag
  throughout (FR-2, FR-7, US-4, UX examples, docs, rollout plan)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@Benbentwo Benbentwo enabled auto-merge (squash) March 4, 2026 16:56
@Benbentwo Benbentwo merged commit 6d1f475 into main Mar 4, 2026
56 checks passed
@Benbentwo Benbentwo deleted the feature/dev-3829-add-browser-based-auth-flow-for-root-and-iam-identities branch March 4, 2026 20:59
@github-actions
Copy link

github-actions bot commented Mar 5, 2026

These changes were released in v1.208.1-test.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-release Do not create a new release (wait for additional code changes) size/m Medium size PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants