# 构建您的集成
<a name="temporary-delegation-building-integration"></a>

## 了解请求生命周期
<a name="temporary-delegation-request-lifecycle"></a>

在构建集成之前，了解委派请求从创建到完成的过程非常重要。

### 请求状态
<a name="temporary-delegation-request-states"></a>

委派请求会经历以下状态：


| 州 | 说明 | 
| --- | --- | 
| 未分配 | 请求已创建，但尚未与客户账户和 IAM 主体关联。该请求可能是在未指定目标账户的情况下创建的，也可能已指定目标账户 ID 但账户所有者尚未认领。 | 
| 已分配 | 与客户账户关联且正在等待审查的请求 | 
| 待批准 | 客户已将请求转发给管理员进行批准 | 
| 已接受 | 请求已获得客户批准，但交换令牌尚未发放 | 
| 已最终确定 | 交换令牌已发放给产品提供商。委派期限（交换令牌有效期）从请求达到“已最终确定”状态时开始 | 
| 已拒绝 | 请求被客户拒绝 | 
| 已过期 | 由于不活动或超时，请求已过期 | 

### 状态变换
<a name="temporary-delegation-state-transitions"></a>

*正常流程（批准路径）*
+ 未分配 → 已分配：客户将请求与其账户关联
+ “已分配 → 已接受”或“已分配 → 待批准”：客户直接批准请求或转发给管理员进行审查
+ 待批准 → 已接受：管理员批准该请求
+ 已接受 → 已最终确定：客户发放交换令牌

*拒绝路径*
+ 已分配 → 已拒绝：客户拒绝该请求
+ 待批准 → 已拒绝：管理员拒绝该请求
+ 已接受 → 已拒绝：客户在发放令牌之前撤销批准

*到期路径*

如果在指定时间范围内未采取任何行动，则请求将自动过期：
+ 未分配 → 已过期（1 天）
+ 已分配 → 已过期（7 天）
+ 待批准 → 已过期（7 天）
+ 已接受 → 已过期（7 天）
+ 已拒绝 → 已过期（7 天）
+ 已最终确定 → 已过期（7 天）

*终端状态*

以下状态是终止状态（不再有进一步的转换）：
+ 已最终确定：交换令牌已发送
+ 已拒绝：请求被拒绝
+ 已过期：请求超时或委派期限结束

保留期过后，过期的请求最终会从系统中删除。

### 管理应用程序中的委派请求状态
<a name="temporary-delegation-managing-states"></a>

作为合作伙伴，您必须在系统中跟踪委派请求状态，并将其呈现给客户。当您收到有关状态变更的 SNS 通知时，请将这些更新存储在后端，并在面向客户的 UI 中显示。请特别注意“待批准”状态：当客户将请求转发给管理员进行审查时，Amazon 会向您发送待批准通知。在等待管理员操作期间，请求可以保持此状态长达 7 天。在此期间，在您的应用程序中向客户展示其请求正在等待管理员的批准。考虑提供指向 Amazon 管理控制台的深层链接，客户可以在其中查看请求状态或与其管理员跟进沟通。正确处理后端的状态机并在每个阶段向客户呈现正确的状态信息对于获得良好的集成体验非常重要。

![状态图显示了从“未分配”到“已分配”、“待批准”，再到“已接受”、“已拒绝”、“已完成”、“已过期”或“已删除”状态的授权请求流。](http://docs.amazonaws.cn/IAM/latest/UserGuide/images/delegation-states.png)


## 配置 通知
<a name="temporary-delegation-configuring-notifications"></a>

IAM 使用 Amazon Simple Notification Service（SNS）向您传达委派请求状态的更改。创建委派请求时，必须提供注册 Amazon 账户中的 SNS 主题 ARN。IAM 将向该主题发布重要事件的消息，包括客户批准或拒绝请求时以及交换令牌准备就绪时。

**注意**  
SNS 主题不能位于可选择加入的 Amazon 区域。您的 SNS 主题必须位于默认启用的 Amazon 区域中。有关选择加入区域的列表，请参阅 Amazon 账户管理指南中的“管理 Amazon 区域”。

### SNS 主题配置
<a name="temporary-delegation-sns-topic-configuration"></a>

要接收委派请求通知，您必须将 SNS 主题配置为授予向其发布消息的 IAM 权限。将以下策略语句添加到 SNS 主题策略：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowIAMServiceToPublish",
            "Effect": "Allow",
            "Principal": {
                "Service": "iam.amazonaws.com"
            },
            "Action": "SNS:Publish",
            "Resource": "arn:aws:sns:REGION:ACCOUNT-ID:TOPIC-NAME"
        }
    ]
}
```

**重要**  
SNS 主题必须位于您的其中一个注册 Amazon 账户中。IAM 不接受来自其他账户的 SNS 主题。如果主题策略配置不正确，您将不会收到状态更改通知或交换令牌。

### 通知类型
<a name="temporary-delegation-notification-types"></a>

IAM 发送两种类型的通知：

*StateChange 通知*

当委派请求转换到新状态（已分配、待批准、已接受、已最终确定、已拒绝、已过期）时发送。

*ExchangeToken 通知*

当客户发放委派令牌时发送（状态为“已最终确定”）。此通知包含您获取凭证所需的交换令牌。

### 通知系统
<a name="temporary-delegation-notification-states"></a>

您将收到以下委派请求状态的通知：


| 州 | 通知类型 | 说明 | 
| --- | --- | --- | 
| 已分配 | StateChange | 请求已与客户账户关联 | 
| 待批准 | StateChange | 客户已将请求转发给管理员进行批准 | 
| 已接受 | StateChange | 客户已批准请求，但尚未发放令牌 | 
| 已最终确定 | StateChange | 客户已发放交换令牌 | 
| 已最终确定 | ExchangeToken | 此通知包含交换令牌 | 
| REJECTED | StateChange | 客户已拒绝该请求 | 
| EXPIRED | StateChange | 请求在完成前已过期 | 

### 通知消息格式
<a name="temporary-delegation-notification-message-format"></a>

IAM 发布标准 SNS 通知。委派请求信息以 JSON 字符串的形式包含在“消息”字段中。

*常用字段（所有通知）*


| 字段 | Type | 说明 | 
| --- | --- | --- | 
| 类型 | 字符串 | “StateChange”或“ExchangeToken” | 
| RequestId | 字符串 | IAM 委派请求 ID | 
| RequestorWorkflowId | 字符串 | 您在创建请求时提供的工作流程 ID | 
| 州 | 字符串 | 请求的当前状态 | 
| OwnerAccountId | 字符串 | 客户的 Amazon 账户 ID | 
| UpdatedAt | 字符串 | 状态更改时的时间戳（ISO 8601 格式） | 

*其他字段（仅限 ExchangeToken 通知）*


| 字段 | Type | 说明 | 
| --- | --- | --- | 
| ExchangeToken | 字符串 | 使用 Amazon STS GetDelegatedAccessToken API 交换凭证的令牌 | 
| ExpiresAt | 字符串 | 委派访问权限过期时间（ISO 8601 格式） | 

### 示例通知
<a name="temporary-delegation-example-notifications"></a>

*StateChange 通知*

```
{
  "Type": "Notification",
  "MessageId": "61ee8ad4-6eec-56b5-8f3d-eba57556aa13",
  "TopicArn": "arn:aws:sns:us-east-1:123456789012:partner-notifications",
  "Message": "{\"RequestorWorkflowId\":\"workflow-12345\",\"Type\":\"StateChange\",\"RequestId\":\"dr-abc123\",\"State\":\"ACCEPTED\",\"OwnerAccountId\":\"111122223333\",\"UpdatedAt\":\"2025-01-15T10:30:00.123Z\"}",
  "Timestamp": "2025-01-15T10:30:00.456Z",
  "SignatureVersion": "1",
  "Signature": "...",
  "SigningCertURL": "...",
  "UnsubscribeURL": "..."
}
```

*ExchangeToken 通知*

```
{
  "Type": "Notification",
  "MessageId": "e44e5435-c72c-5333-aba3-354406782f5b",
  "TopicArn": "arn:aws:sns:us-east-1:123456789012:partner-notifications",
  "Message": "{\"RequestId\":\"dr-abc123\",\"RequestorWorkflowId\":\"workflow-12345\",\"State\":\"FINALIZED\",\"OwnerAccountId\":\"111122223333\",\"ExchangeToken\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\"ExpiresAt\":\"2025-01-15T18:30:00.123Z\",\"UpdatedAt\":\"2025-01-15T10:30:00.456Z\",\"Type\":\"ExchangeToken\"}",
  "Timestamp": "2025-01-15T10:30:00.789Z",
  "SignatureVersion": "1",
  "Signature": "...",
  "SigningCertURL": "...",
  "UnsubscribeURL": "..."
}
```

## 交换令牌
<a name="temporary-delegation-exchange-tokens"></a>

当客户接受并最终确定委派请求时，IAM 会发布交换令牌或交易令牌。产品提供商使用此交换或交易令牌调用 Amazon STS GetDelegatedAccessToken API，以获取具有客户批准权限的临时 Amazon 凭证。交换令牌本身不授予对 Amazon 资源的访问权限；必须通过 Amazon STS 将其交换为实际凭证。

交换令牌只能由创建委派请求的产品提供商账户兑换。请求账户嵌入在令牌中，确保只有授权的产品提供商才能获得访问客户账户的凭证。

### 访问持续时间
<a name="temporary-delegation-access-duration"></a>

委派期限从客户发放交换令牌时开始，而不是从产品提供商兑换令牌时开始。客户发放令牌后：
+ 产品提供商通过 SNS 通知接收令牌
+ 其可以立即用该令牌交换凭证
+ 凭证到期时间：发放时间 \+ 批准的持续时间
+ 如果需要，产品提供商可以在令牌到期前多次交换该令牌以获取新的凭证

### 多次兑换
<a name="temporary-delegation-multiple-redemptions"></a>

产品提供商可以在有效期内多次交换令牌以获得新的凭证。但是，根据您发放令牌的时间，从同一个交换令牌获得的所有凭证会同时过期。

示例：如果您批准了 2 小时的委派请求并在上午 10:00 发放令牌：


| 令牌发放时间 | 令牌交换时间 | 凭证到期时间 | 可用时间 | 
| --- | --- | --- | --- | 
| 10:00 am | 10:00 am | 12:00 pm | 2 小时 | 
| 10:00 am | 10:20 am | 12:00 pm | 1 小时 40 分钟 | 
| 10:00 am | 11:40 am | 12:00 pm | 20 分钟 | 
| 10:00 am | 12:10 pm | 失效（令牌已过期） | 0 分钟 | 

如表中所示，在有效期内较晚的时间交换令牌会导致产品提供商的可用时间缩短。