docs: PRD for aws/credentials identity with credential_process

[osterman]

Summary

Adds comprehensive Product Requirements Document for introducing a new aws/credentials identity kind that obtains AWS credentials from external processes using the AWS SDK's credential_process standard. Enables seamless integration with external credential helpers (aws-sso-cli, Okta CLI, aws-vault, custom SAML tools, etc.).

Why a New Identity Kind?

aws/credentials instead of extending aws/user:

The aws/user identity kind is semantically tied to IAM Users and performs IAM User-specific operations:

• Takes long-lived credentials (access key + secret key)
• Calls STS GetSessionToken to generate temporary credentials
• Prompts for MFA tokens for IAM User MFA devices
• Enforces IAM User session duration limits (12h without MFA, 36h with MFA)

Semantic mismatch with credential_process:

• External processes return already-temporary credentials from SSO, assumed roles, or other sources
• These credentials already include a session token
• Calling GetSessionToken again would fail (can't get session token from session credentials)
• MFA is handled by the external process, not by Atmos

Solution: New aws/credentials identity kind

• Semantic meaning: "I have AWS credentials from an external source"
• Behavior: Use credentials as-is without transformation
• Simpler: No MFA prompting, no STS calls, just execute process and use credentials
• Cleaner: Preserves aws/user for its intended purpose (IAM Users with long-lived credentials)

Identity Kind Comparison

Feature	aws/user (existing)	aws/credentials (new)
Purpose	IAM User authentication	External credential processes
Credential source	Access key + secret key	credential_process output
Transformation	Calls STS GetSessionToken	Uses credentials as-is
MFA	Prompts for token	Handled by external process
Session limits	IAM User limits (12h-36h)	Process-determined
Typical use	Break-glass IAM users	SSO, SAML, corporate auth
Provider name	aws-user	aws-credentials

Use Case from GitHub Issue

User's organization sources temporary AWS credentials from an external process and wants to use Atmos's credential_process standard to integrate with their existing tooling.

Configuration Examples

Generic External Process (GitHub Issue Use Case)

auth:
  identities:
    staging:
      kind: aws/credentials
      credentials:
        credential_process: '/home/myuser/.local/bin/external-process staging'
        region: eu-west-1

Comparison with aws/user

auth:
  identities:
    # For IAM Users with long-lived credentials
    break-glass-user:
      kind: aws/user
      credentials:
        access_key_id: !env AWS_ACCESS_KEY_ID
        secret_access_key: !env AWS_SECRET_ACCESS_KEY
        mfa_arn: 'arn:aws:iam::123456789012:mfa/emergency-user'
        region: us-east-1
      session:
        duration: '12h'  # Atmos calls GetSessionToken with MFA

    # For external credential processes (SSO, SAML, etc.)
    corporate-sso:
      kind: aws/credentials
      credentials:
        credential_process: '/usr/local/bin/corporate-credential-helper prod'
        region: us-east-1
      # No session config - external process determines expiration

Identity Chaining

auth:
  identities:
    corp-base:
      kind: aws/credentials
      credentials:
        credential_process: '/usr/local/bin/corporate-sso-helper'

    staging-poweruser:
      kind: aws/assume-role
      via:
        identity: corp-base
      principal:
        role_arn: 'arn:aws:iam::111111111111:role/PowerUser'

Additional Example Tools

PRD includes examples for common credential helper tools:

• aws-sso-cli
• Okta AWS CLI
• Custom SAML scripts
• aws-vault
• Multi-level identity chaining

🤖 Generated with Claude Code

[coderabbitai[bot]]

[!WARNING]

Rate limit exceeded

@osterman has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 4 minutes and 36 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 81253091683c13b730019078d3bc6e8cb36cfc79 and 17138cc561847d1da4050a364f6aef6c3e92189d.

📒 Files selected for processing (1)

• docs/prd/aws-credential-process.md (1 hunks)

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch osterman/aws-credential-process

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions[bot]]

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

[codecov[bot]]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 70.67%. Comparing base (8125309) to head (17138cc). :warning: Report is 56 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1795      +/-   ##
==========================================
+ Coverage   70.66%   70.67%   +0.01%     
==========================================
  Files         451      451              
  Lines       42397    42397              
==========================================
+ Hits        29958    29966       +8     
+ Misses       9911     9903       -8     
  Partials     2528     2528              

Flag	Coverage Δ
unittests	70.67% <ø> (+0.01%)	:arrow_up:

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

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.