如何正确配置python-amazon-sp-api的LWA认证与角色ARN？

Question

常见问题： 在使用 `python-amazon-sp-api` 集成Amazon SP API时，开发者常混淆LWA（Login with Amazon）认证与IAM角色ARN的职责边界——误将角色ARN直接填入LWA配置（如`client_id`/`client_secret`），或未正确配置跨账户委托信任策略，导致`AccessDeniedException`或`InvalidInput`错误；更典型的是，虽已创建IAM角色并附加`AmazonSPAPIFullAccess`策略，却遗漏在角色信任策略中显式授权`accounts.amazon.com`作为`Principal`，且未启用`sts:AssumeRoleWithWebIdentity`权限。此外，部分开发者忽略LWA访问令牌（access_token）需通过`refresh_token`定期刷新，而库默认不自动续期，引发403失效问题。如何确保LWA凭据、IAM角色ARN、STS AssumeRole调用三者严格解耦又协同工作，是配置成功的关键前提。

Answer 1

```html

一、职责边界澄清：LWA 与 IAM 角色的职能解耦

开发者常将 client_id/client_secret（LWA 凭据）与 role_arn（IAM 角色ARN）混为一谈。本质区别如下：

• LWA：仅用于用户身份认证与授权，生成短期 access_token 和长期 refresh_token，属于OAuth 2.0 Web Identity Flow；
• IAM 角色：是 AWS 资源访问的权限载体，需通过 STS AssumeRoleWithWebIdentity 接口，以 LWA token 为“身份凭证”临时扮演该角色；
• 角色ARN绝不可填入 LWA 配置字段——它只在 SP API SDK 初始化时作为 role_arn 参数传入，与 client_id 完全正交。

二、信任策略诊断：为什么 AccessDeniedException 频发？

即使已附加 AmazonSPAPIFullAccess 策略，若信任策略缺失关键要素，STS 调用必然失败。典型错误配置示例如下：

缺失项	后果	合规写法（片段）
未声明 accounts.amazon.com 为 Principal	STS 拒绝假设角色	"Principal": {"Federated": "accounts.amazon.com"}
未启用 sts:AssumeRoleWithWebIdentity	权限不足，返回 InvalidInput	"Action": "sts:AssumeRoleWithWebIdentity"

三、令牌生命周期管理：403 失效的根源与自动化方案

python-amazon-sp-api 默认不自动刷新 access_token（TTL=1h），导致请求在 token 过期后持续返回 403。正确实践需实现：

1. 捕获 AccessTokenExpiredError 异常；
2. 调用 auth.refresh_access_token(refresh_token)；
3. 持久化新 token 对（含新 refresh_token，因 Amazon 可轮换）；
4. 重试原请求（建议封装为 retryable session wrapper）。

四、端到端协同流程图（Mermaid）

sequenceDiagram
    participant D as Developer App
    participant L as Login with Amazon (LWA)
    participant S as AWS STS
    participant R as IAM Role
    participant A as SP API Endpoint

    D->>+L: POST /auth/o2/token (grant_type=refresh_token, client_id, client_secret, refresh_token)
    L-->>-D: {access_token, refresh_token, expires_in}
    D->>+S: AssumeRoleWithWebIdentity(RoleArn, WebIdentityToken=access_token, RoleSessionName)
    S-->>-D: {Credentials: {AccessKeyId, SecretAccessKey, SessionToken}}
    D->>+A: SP API Request (with SigV4 signed by STS creds)
    A-->>-D: Valid response or error

五、生产级配置验证清单

• ✅ LWA 应用状态为 Published（非 Development），且已配置正确的 Allowed Return URLs；
• ✅ IAM 角色信任策略中 Condition.StringEquals."accounts.amazon.com:app_id" 与 LWA App ID 严格一致；
• ✅ 角色策略显式允许 spapi:*（而非仅依赖托管策略，因 AmazonSPAPIFullAccess 不含 sts:*）；
• ✅ SDK 初始化时传入参数分离清晰：client_id, client_secret, refresh_token → LWA；role_arn, aws_region → STS；
• ✅ 所有 token 存储使用加密安全方式（如 AWS Secrets Manager 或 KMS 加密文件），禁止硬编码或明文日志输出。

六、调试技巧：快速定位故障层级

当出现 AccessDeniedException 时，按以下顺序逐层验证：

1. 用 curl -X POST https://api.amazon.com/auth/o2/token 手动测试 LWA token 获取是否成功；
2. 用 AWS CLI 手动调用 aws sts assume-role-with-web-identity，传入刚获取的 access_token；
3. 检查返回的 Credentials 是否能成功调用 aws sts get-caller-identity；
4. 确认 Python SDK 中 credentials_duration_seconds ≤ 3600（SP API 要求最大 1h）；
5. 启用 logging.getLogger("sp_api").setLevel(logging.DEBUG) 查看完整 SigV4 签名上下文。

```