cevoaustralia/aws-google-auth

aws-google-auth

该命令行工具允许使用Google Apps作为联合（单点登录，SSO）提供商获取AWS临时（STS）凭证。

镜像概述和主要用途

aws-google-auth是一个用于通过Google Apps SAML SSO认证获取AWS临时访问凭证的工具。它解决了需要通过Google账户单点登录访问AWS资源的场景，无需手动管理长期AWS访问密钥，提高了安全性和操作便捷性。

核心功能和特性

• 支持通过Google Apps SAML SSO获取AWS STS临时凭证
• 兼容多种Google 2Factor认证方式（TOTP、SMS、Google Prompt、安全密钥等）
• 支持凭证缓存和AWS配置文件自动更新
• 可通过环境变量或命令行参数配置
• 提供Docker镜像，支持容器化运行
• 支持U2F安全密钥认证（原生Python环境）
• 与密码管理器集成，支持从stdin输入密码

使用场景和适用范围

• 企业环境中使用Google Workspace作为身份提供商管理AWS访问
• 需要通过单点登录方式安全访问AWS资源的团队
• 希望避免使用长期AWS访问密钥的开发和运维人员
• 需要自动化获取AWS临时凭证的脚本或CI/CD流程

前置设置

Google与AWS SAML SSO配置

需先将Google Apps配置为AWS的SAML身份提供商（IdP），涉及Google Apps和AWS双方的配置。参考文档：

• 如何使用Google Apps设置联合单点登录到AWS
• 使用Google Apps SAML SSO实现AWS一键登录

如需简单分配用户到AWS账户角色，可参考工具https://github.com/cevoaustralia/google-aws-federator%E3%80%82

重要配置数据

需获取以下两个关键参数：

• GOOGLE_SP_ID：在Google Admin控制台中，通过应用 > SAML应用 > AWS SSO设置，URL中包含类似...#AppDetails:service=123456789012...的部分，其中数字即SP ID
• GOOGLE_IDP_ID：在Google Admin控制台中，通过安全 > 设置单点登录(SSO)，SSO URL中类似https://accounts.google.com/o/saml2/idp?idpid=aBcD01AbC的部分，等号后的字符串即IDP ID

安装方法

本地Python安装

shell
# 基础安装
localhost$ sudo pip install aws-google-auth

# 带U2F支持的安装
localhost$ sudo pip install aws-google-auth[u2f]

注意：使用ZSH时需引用安装命令：

shell
localhost$ sudo pip install "aws-google-auth[u2f]"

Docker安装

shell
# 本地构建镜像
localhost$ cd ..../aws-google-auth && docker build -t aws-google-auth .

# 使用Docker Hub镜像
localhost$ docker pull cevoaustralia/aws-google-auth

使用方法

命令行参数说明

shell
$ aws-google-auth -h
usage: aws-google-auth [-h] [-u USERNAME] [-I IDP_ID] [-S SP_ID] [-R REGION]
                       [-d DURATION] [-p PROFILE] [-D] [-q]
                       [--bg-response BG_RESPONSE]
                       [--saml-assertion SAML_ASSERTION] [--no-cache]
                       [--print-creds] [--resolve-aliases]
                       [--save-failure-html] [--save-saml-flow] [-a | -r ROLE_ARN] [-k]
                       [-l {debug,info,warn}] [-V]

Acquire temporary AWS credentials via Google SSO

可选参数:
  -h, --help            显示帮助信息并退出
  -u USERNAME, --username USERNAME
                        Google Apps用户名 ($GOOGLE_USERNAME)
  -I IDP_ID, --idp-id IDP_ID
                        Google SSO IDP标识符 ($GOOGLE_IDP_ID)
  -S SP_ID, --sp-id SP_ID
                        Google SSO SP标识符 ($GOOGLE_SP_ID)
  -R REGION, --region REGION
                        AWS区域端点 ($AWS_DEFAULT_REGION)
  -d DURATION, --duration DURATION
                        凭证有效期（默认使用$DURATION环境变量，否则为43200秒）
  -p PROFILE, --profile PROFILE
                        AWS配置文件（默认使用$AWS_PROFILE环境变量，否则为'sts'）
  -D, --disable-u2f     禁用U2F功能
  -q, --quiet           安静输出模式
  --bg-response BG_RESPONSE
                        覆盖默认bgresponse挑战令牌 ($GOOGLE_BG_RESPONSE)
  --saml-assertion SAML_ASSERTION
                        要使用的Base64编码SAML断言
  --no-cache            不缓存SAML断言
  --print-creds         打印凭证信息
  --resolve-aliases     解析AWS账户别名
  --save-failure-html   将HTML失败响应写入文件用于故障排除
  --save-saml-flow      将所有与Google的GET/PUT请求和HTML响应写入文件用于故障排除
  -a, --ask-role        始终提示选择角色
  -r ROLE_ARN, --role-arn ROLE_ARN
                        要承担的角色ARN ($AWS_ROLE_ARN)
  -k, --keyring         使用keyring存储密码
  -l {debug,info,warn}, --log {debug,info,warn}
                        选择日志级别（默认：warn）
  -V, --version         显示程序版本号并退出

注意：如需会话时长超过AWS默认的3600秒（1小时），必须修改IAM角色以允许更长的会话时间，详见AWS文档。

原生Python使用

1. 执行命令：aws-google-auth
2. 根据提示输入所需参数

注意：可通过命令行参数或环境变量跳过交互提示。

Docker使用

1. 设置环境变量：

   • GOOGLE_USERNAME：Google账户***
   • GOOGLE_IDP_ID：Google IDP标识符（见前置设置）
   • GOOGLE_SP_ID：Google SP标识符（见前置设置）
   • AWS_PROFILE：可选，AWS配置文件名称（默认：'sts'）
   • ROLE_ARN：可选，要承担的角色ARN

2. 运行Docker容器：

shell
docker run -it -e GOOGLE_USERNAME -e GOOGLE_IDP_ID -e GOOGLE_SP_ID -e AWS_PROFILE -e ROLE_ARN -v ~/.aws:/root/.aws cevoaustralia/aws-google-auth

注意：Docker环境不支持U2F安全密钥，可能会出现"RuntimeWarning: U2F Device Not Found"错误。如有多个可用角色且未设置ROLE_ARN，将提示选择角色。

从stdin输入密码

支持从stdin输入密码（适用于密码管理器集成）：

shell
$ password-manager show password | aws-google-auth
Google Password: MFA token:
Assuming arn:aws:iam::123456789012:role/admin
Credentials Expiration: ...

注意：此功能用于密码管理器集成，不建议从命令行直接传递密码，以避免密码泄露到shell历史记录。

配置文件存储

使用-p或--profile标志指定AWS配置文件时，工具会将用户名、IDP和SP详情存储在~/.aws/config文件中。再次使用相同配置文件认证时，将记住这些值以加快认证过程。

可创建别名简化认证命令：

shell
alias aws-development='unset AWS_PROFILE; aws-google-auth -I $GOOGLE_IDP_ID -S $GOOGLE_SP_ID -u $USERNAME -p aws-dev ; export AWS_PROFILE=aws-dev'

已建立配置文件后：

shell
alias aws-development='unset AWS_PROFILE; aws-google-auth -p aws-dev ; export AWS_PROFILE=aws-dev'

认证方式说明

Google支持多种双因素认证方案，每种方案在登录过程中会产生不同的"next" URL。以下是工具支持的认证方式及对应的URL片段：

开发说明

如需开发该工具，可使用以下命令本地安装：

shell
# 无U2F支持
pip install -e .

# 带U2F支持
pip install -e .[u2f]

开发前请查看行为准则和贡献指南。

致谢

本工具的开发受https://github.com/wheniwork/keyme%E5%90%AF%E5%8F%91%EF%BC%8C%E5%85%B6%E5%AF%B9Google SAML认证机制的研究为该工具提供了基础。属性管理和凭证注入AWS配置文件的功能主要借鉴自https://github.com/venth/aws-adfs%E3%80%82