# 統合の構築
## リクエストのライフサイクルについて
統合を構築するときは、まず、委任リクエストの作成から完了までのプロセスを理解する必要があります。
### リクエストのステータス
委任リクエストは以下のステータスを経て進行します。
| 状態 | 説明 |
| --- | --- |
| 未割り当て | リクエストは作成済みですが、まだ顧客アカウントや IAM プリンシパルに関連付けられていない状態です。リクエストは、ターゲットアカウントを指定せずに作成されたか、ターゲットアカウントの ID は指定されているものの、そのアカウントの所有者からまだ請求されていない可能性があります。 |
| 割り当て済み | リクエストは顧客アカウントに関連付けられ、確認待ちの状態です |
| 承認待ち | リクエストは承認のため顧客から管理者に転送されています |
| 承諾 | リクエストは顧客によって承認済みですが、交換トークンはまだ発行されていない状態です |
| 完了 | 交換トークンは製品プロバイダーに発行済みです。委任期間 (交換トークンが有効な期間) は、リクエストのステータスが「完了」になったときから始まります |
| 拒否 | リクエストは顧客から拒否されています |
| 失効 | リクエストは非アクティブまたはタイムアウトのため期限が切れています |
### ステータスの移行
*通常のフロー (承認の流れ)*
+ 未割り当て → 割り当て済み: 顧客がリクエストを自分のアカウントに関連付ける
+ 割り当て済み → 承認済みまたは割り当て済み → 承認待ち: 顧客がリクエストを直接承認するまたは管理者に転送して承認を受ける
+ 承認待ち → 承諾済み: 管理者がリクエストを承認する
+ 承認済み → 完了: 顧客が交換トークンを発行する
*拒否の流れ*
+ 割り当て済み → 拒否: 顧客がリクエストを拒否する
+ 承認待ち → 拒否: 管理者がリクエストを拒否する
+ 承認済み → 拒否: 顧客がトークンの発行前に承認を取り消す
*期限切れの流れ*
指定した期間内にアクションが 1 つも実行されなかった場合、リクエストは自動的に期限切れになります。
+ 未割り当て → 期限切れ (1 日)
+ 割り当て済み → 期限切れ (7 日間)
+ 承認待ち → 期限切れ (7 日間)
+ 承認済み → 期限切れ (7 日間)
+ 拒否 → 期限切れ (7 日間)
+ 完了 → 期限切れ (7 日間)
*ターミナルステータス*
以下のステータスは「ターミナル」です (移行はここで終わりです)。
+ 完了: 交換トークンは送信済みです
+ 拒否: リクエストは拒否されました
+ 期限切れ: リクエストはタイムアウトしたか委任期間が終了しています
期限が切れたリクエストは、保持期間が過ぎるとシステムから削除されます。
### 委任リクエストのステータスをアプリケーションで管理する
パートナーであるユーザーは、委任リクエストのステータスを自分のシステムで追跡し、顧客に見せる必要があります。ステータスの変更に関する SNS 通知がお手元に届いたら、その更新をバックエンドに保存して顧客向けの UI に反映させます。特に「承認待ち」のステータスには注意が必要です。顧客が承認を受けるためリクエストを管理者に転送した場合、ユーザーには AWS から「承認待ち」の通知が届きます。リクエストは、管理者のアクションを待つ間、最大で 7 日間このステータスに留まることができます。この間、顧客には、リクエストが管理者の承認待ちであることをアプリケーション内で知らせます。顧客がリクエストのステータスをチェックしたり管理者をフォローしたりできる AWS コンソールの、ディープリンクを提供することを検討しましょう。バックエンドでステートマシンを適切に処理し、各段階で顧客に正しいステータス情報を見せることは、優れた統合体験の提供に欠かせません。
## 通知の設定
IAM は、委任リクエストのステータス変更の通知に Amazon Simple Notification Service (SNS) を使用します。委任リクエストを作成するときは、登録済みの AWS アカウントから SNS トピック ARN を指定する必要があります。IAM は、顧客がリクエストを承認または拒否したときや交換トークンの準備が完了したときなど、重要なイベントの際にこのトピックにメッセージを発行します。
**注記**
SNS トピックは、オプトインの AWS リージョンには配置できません。SNS トピックはデフォルトで有効になっている AWS リージョンに配置する必要があります。オプトインリージョンの一覧については「AWS アカウント管理ガイド」の「AWS リージョンの管理」を参照してください。
### SNS トピックの設定
委任リクエストの通知を受けとるには、IAM アクセス許可を付与してメッセージを発行するように、SNS トピックを設定する必要があります。以下のポリシーステートメントを 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 トピックは、登録済み AWS アカウントのうちの 1 つに配置する必要があります。IAM は、他のアカウントの SNS トピックは受け入れません。トピックポリシーが正しく設定されていないと、ステータスの変更通知や交換トークンを受けとれません。
### 通知タイプ
IAM は次の 2 種類の通知を送信します。
*StateChange 通知*
委任リクエストが新しいステータス (割り当て済み、承認待ち、承認済み、完了、拒否、期限切れ) に移行すると送信されます。
*ExchangeToken 通知*
顧客が委任トークンを発行すると送信されます (ステータスは「完了」)。この通知には、認証情報の取得に必要な交換トークンが含まれています。
### 通知のステータス
ユーザーには、以下の委任リクエストのステータスに関する通知が届きます。
| State | 通知タイプ | 説明 |
| --- | --- | --- |
| 割り当て済み | StateChange | リクエストは顧客アカウントに関連付けられています |
| 承認待ち | StateChange | リクエストは承認のため顧客から管理者に転送されています |
| 承認済み | StateChange | リクエストは顧客によって承認済みですが、交換トークンはまだ発行されていません |
| 完了 | StateChange | 交換トークンが顧客によって発行済みです |
| 完了 | ExchangeToken | この通知には交換トークンが含まれています |
| 拒否 | StateChange | リクエストは顧客によって拒否されました |
| EXPIRED | StateChange | リクエストは完了前に期限が切れました |
### 通知メッセージの書式
IAM は標準の SNS 通知を発行します。委任リクエストの情報は、「Message」のフィールドに JSON 文字列で含まれています。
*共通のフィールド (すべての通知)*
| フィールド | タイプ | 説明 |
| --- | --- | --- |
| タイプ | String | 「StateChange」または「ExchangeToken」のいずれか |
| RequestId | String | IAM 委任リクエストの ID |
| RequestorWorkflowId | String | リクエストの作成時に指定したワークフローの ID |
| State | String | リクエストの現在のステータス |
| OwnerAccountId | String | 顧客の AWS アカウントの ID |
| UpdatedAt | String | ステータスが変更された時点のタイムスタンプ (ISO 8601 形式) |
*その他のフィールド (ExchangeToken 通知のみ)*
| フィールド | タイプ | 説明 |
| --- | --- | --- |
| ExchangeToken | String | AWS STS GetDelegatedAccessToken API を使用して認証情報と交換するトークン |
| ExpiresAt | String | 委任されたアクセス許可の期限が切れたとき (ISO 8601 形式) |
### 通知の例
*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": "..."
}
```
## 交換トークン
交換トークンは、顧客が委任リクエストを承認して完了したときに IAM から発行されます。製品プロバイダーは、この交換トークンを使用して AWS STS GetDelegatedAccessToken API を呼び出し、顧客が承認したアクセス許可を持つ一時的な AWS 認証情報を取得します。交換トークン自体は AWS リソースへのアクセスを許可するものではなく、AWS STS を介して実際の認証情報と交換する必要があります。
交換トークンは、委任リクエストを作成した製品プロバイダーアカウントからのみ、引き換えが可能です。リクエストを行ったアカウントはこのトークンに埋め込まれ、承認された製品プロバイダーのみが、顧客アカウントにアクセスするための認証情報を取得できるようになっています。
### アクセス許可の有効期間
委任期間は顧客が交換トークンを発行した時点からはじまります。製品プロバイダーが交換トークンを引き替えた時点ではありません。顧客がトークンを発行すると、
+ 製品プロバイダーは SNS 通知を介してトークンを受けとります
+ トークンは直ちに認証情報と交換できます
+ 認証情報は、発行時間から承認済みの期間が経過すると期限が切れます。
+ 製品プロバイダーは、期限が切れる前にトークンを複数回交換し、必要に応じて新しい認証情報を取得することができます。
### 複数の引き換え
製品プロバイダーは、有効期間中にトークンを複数回交換して、新しい認証情報を取得することができます。ただし、同じ交換トークンから取得した認証情報はすべて、トークンを発行した時刻に基づき同時に期限が切れます。
例: 2 時間の委任リクエストを承認し、午前 10 時にトークンを発行する場合
| トークンの発行時刻 | トークン交換時刻 | 認証情報の有効期限 | 使用可能な時間 |
| --- | --- | --- | --- |
| 10:00 am | 10:00 am | 12:00 pm | 2 時間 |
| 10:00 am | 午前 10 時 20 分 | 12:00 pm | 1 時間 40 分 |
| 10:00 am | 午前 11 時 40 分 | 12:00 pm | 20 分 |
| 10:00 am | 12:10 pm | 失敗 (トークンの有効期限切れ) | 0 分 |
表に示すように、有効期間の後半でトークンを交換すると、製品プロバイダーの使用可能時間は短くなります。