통합 구축
통합 구축 (Building your integration)
출처: 문서
요청 수명 주기 이해
통합을 구축하기 전에 위임 요청이 생성부터 완료까지 어떻게 진행되는지 이해하는 것이 중요해요.
요청 상태 (Request States)
위임 요청은 다음 상태를 거쳐 진행돼요.
| 상태 | 설명 |
|---|---|
| Unassigned | 요청이 생성됐지만 아직 고객 계정과 IAM principal에 연결되지 않음. 대상 계정을 지정하지 않고 생성되었거나, 대상 계정 ID가 있지만 계정 소유자가 아직 청구(claim)하지 않은 상태 |
| Assigned | 고객 계정과 연결되고 검토를 기다리는 상태 |
| Pending Approval | 고객이 승인을 위해 요청을 관리자에게 전달한 상태 |
| Accepted | 고객이 요청을 승인했지만 교환 토큰이 아직 릴리스되지 않은 상태 |
| Finalized | 교환 토큰이 제품 제공자에게 릴리스됨. 위임 기간(교환 토큰 유효성)은 요청이 Finalized 상태에 도달할 때 시작됨 |
| Rejected | 고객이 요청을 거부한 상태 |
| Expired | 비활동 또는 타임아웃으로 요청이 만료된 상태 |
상태 전환 (State Transitions)
정상 흐름 (승인 경로)
- Unassigned → Assigned: 고객이 요청을 자신의 계정과 연결
- Assigned → Accepted OR Assigned → Pending Approval: 고객이 직접 승인하거나 관리자에게 검토 전달
- Pending Approval → Accepted: 관리자가 요청 승인
- Accepted → Finalized: 고객이 교환 토큰 릴리스
거부 경로 (Rejection Path)
- Assigned → Rejected: 고객이 요청 거부
- Pending Approval → Rejected: 관리자가 요청 거부
- Accepted → Rejected: 고객이 토큰 릴리스 전에 승인 철회
만료 경로 (Expiration Path)
지정된 기간 안에 조치가 없으면 요청이 자동으로 만료돼요.
- Unassigned → Expired (1일)
- Assigned → Expired (7일)
- Pending Approval → Expired (7일)
- Accepted → Expired (7일)
- Rejected → Expired (7일)
- Finalized → Expired (7일)
최종 상태 (Terminal States)
다음 상태는 최종이며(추가 전환 없음):
- Finalized: 교환 토큰 전송됨
- Rejected: 요청이 거부됨
- Expired: 요청이 타임아웃되거나 위임 기간이 종료됨
만료된 요청은 보존 기간(retention period) 후 시스템에서 결국 삭제돼요.
애플리케이션에서 위임 요청 상태 관리
파트너로서 시스템에서 위임 요청 상태를 추적하고 고객에게 표시해야 해요. 상태 변경에 대한 SNS 알림을 받으면 백엔드에 이 업데이트를 저장하고 고객용 UI에 반영하세요. Pending Approval 상태에 특별한 주의를 기울이세요 — 고객이 검토를 위해 관리자에게 요청을 전달하면 AWS가 여러분에게 Pending Approval 알림을 보내요. 요청은 관리자 조치를 기다리는 동안 최대 7일 동안 이 상태로 남을 수 있어요. 이 기간 동안 애플리케이션에서 고객에게 요청이 관리자 승인을 기다리는 중임을 표시하세요. 고객이 요청 상태를 확인하거나 관리자와 후속 조치할 수 있도록 AWS 콘솔에 대한 딥 링크를 제공하는 것을 고려하세요. 백엔드에서 상태 머신을 적절히 처리하고 각 단계에서 고객에게 올바른 상태 정보를 표시하는 것은 좋은 통합 경험에 중요해요.
알림 구성
IAM은 Amazon Simple Notification Service(SNS)를 사용해 위임 요청 상태 변경을 여러분에게 통신해요. 위임 요청을 만들 때 등록된 AWS 계정의 SNS 주제 ARN을 제공해야 해요. IAM은 고객이 요청을 승인·거부하거나 교환 토큰이 준비됐을 때 같은 중요한 이벤트에 대해 이 주제로 메시지를 게시해요.
참고
SNS 주제는 opt-in AWS 리전에 있을 수 없어요. SNS 주제는 기본적으로 활성화된 AWS 리전에 있어야 합니다. opt-in 리전 목록은 AWS 계정 관리 가이드의 Managing AWS Regions를 참고하세요.
SNS 주제 구성
위임 요청 알림을 받으려면 SNS 주제가 IAM에 메시지를 게시할 권한을 부여하도록 구성해야 해요. SNS 주제 정책에 다음 정책 구문을 추가하세요.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowIAMServiceToPublish",
"Effect": "Allow",
"Principal": {
"Service": "iam.amazonaws.com"
},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:us-east-1:111122223333:TOPIC-NAME"
}
]
}
중요
SNS 주제는 등록된 AWS 계정 중 하나에 있어야 합니다. IAM은 다른 계정의 SNS 주제를 수락하지 않아요. 주제 정책이 올바르게 구성되지 않으면 상태 변경 알림이나 교환 토큰을 받지 못합니다.
알림 유형
IAM은 두 가지 유형의 알림을 보내요.
- StateChange 알림 — 위임 요청이 새 상태(Assigned, Pending Approval, Accepted, Finalized, Rejected, Expired)로 전환될 때 전송됩니다.
- ExchangeToken 알림 — 고객이 위임 토큰을 릴리스할 때(상태 Finalized) 전송됩니다. 이 알림에는 자격 증명을 얻는 데 필요한 교환 토큰이 포함됩니다.
알림 상태
다음 위임 요청 상태에 대한 알림을 받게 돼요.
| 상태 | 알림 유형 | 설명 |
|---|---|---|
| ASSIGNED | StateChange | 요청이 고객 계정과 연결됨 |
| PENDING APPROVAL | StateChange | 고객이 승인을 위해 요청을 관리자에게 전달함 |
| ACCEPTED | StateChange | 고객이 요청을 승인했지만 아직 토큰을 릴리스하지 않음 |
| FINALIZED | StateChange | 고객이 교환 토큰을 릴리스함 |
| FINALIZED | ExchangeToken | 이 알림이 교환 토큰을 포함 |
| REJECTED | StateChange | 고객이 요청을 거부함 |
| EXPIRED | StateChange | 완료 전에 요청이 만료됨 |
알림 메시지 형식
IAM은 표준 SNS 알림을 게시해요. 위임 요청 정보는 Message 필드에 JSON 문자열로 포함돼요.
공통 필드 (모든 알림)
| 필드 | 유형 | 설명 |
|---|---|---|
| Type | 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\":\"eyJhbG...VCJ9...\",\"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": "..."
}
교환 토큰 (Exchange Tokens)
교환 토큰(exchange token)은 고객이 위임 요청을 수락하고 확정할 때 IAM이 발행해요. 제품 제공자는 이 교환 토큰을 사용해 AWS STS GetDelegatedAccessToken API를 호출해 고객이 승인한 권한이 있는 임시 AWS 자격 증명을 얻어요. 교환 토큰 자체는 AWS 리소스에 대한 액세스를 부여하지 않아요. AWS STS를 통해 실제 자격 증명으로 교환되어야 해요.
교환 토큰은 위임 요청을 만든 제품 제공자 계정만 상환할 수 있어요. 요청 계정이 토큰에 내장되어 인증된 제품 제공자만 고객 계정에 액세스할 수 있는 자격 증명을 얻을 수 있음을 보장해요.
액세스 기간
위임 기간은 제품 제공자가 상환할 때가 아니라 고객이 교환 토큰을 릴리스할 때 시작돼요. 고객이 토큰을 릴리스한 후:
- 제품 제공자는 SNS 알림을 통해 토큰을 받습니다.
- 즉시 자격 증명으로 교환할 수 있습니다.
- 자격 증명은 릴리스 시각 + 승인된 기간에 만료됩니다.
- 제품 제공자는 필요하면 만료 전에 토큰을 여러 번 교환해 새 자격 증명을 얻을 수 있습니다.
다중 상환 (Multiple Redemptions)
제품 제공자는 유효 기간 동안 토큰을 여러 번 교환해 새 자격 증명을 얻을 수 있어요. 단 같은 교환 토큰에서 얻은 모든 자격 증명은 토큰을 릴리스한 시점을 기준으로 동시에 만료돼요.
예시: 2시간 위임 요청을 승인하고 10:00 AM에 토큰을 릴리스했다고 가정해요.
| 토큰 릴리스 시각 | 토큰 교환 시각 | 자격 증명 만료 | 사용 가능 시간 |
|---|---|---|---|
| 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분 |
표에서 보듯, 유효 기간 내에서 토큰을 나중에 교환할수록 제품 제공자의 사용 가능 시간이 줄어들어요.