Membangun integrasi Anda

Memahami Siklus Hidup Permintaan

Sebelum membangun integrasi Anda, penting untuk memahami bagaimana permintaan delegasi berkembang dari pembuatan hingga penyelesaian.

Minta Negara

Permintaan delegasi berlangsung melalui status berikut:

Status	Deskripsi
Tidak ditugaskan	Permintaan dibuat tetapi belum dikaitkan dengan akun pelanggan dan prinsipal IAM. Permintaan mungkin telah dibuat tanpa menentukan akun target, atau dengan ID akun target tetapi belum diklaim oleh pemilik akun.
Ditugaskan	Permintaan terkait dengan akun pelanggan dan menunggu peninjauan
Persetujuan Tertunda	Pelanggan telah meneruskan permintaan ke administrator untuk persetujuan
Diterima	Permintaan disetujui oleh pelanggan tetapi token pertukaran belum dirilis
Selesai	Token pertukaran dirilis ke penyedia produk. Periode delegasi (validitas token pertukaran) dimulai ketika permintaan mencapai status Finalized
Ditolak	Permintaan ditolak oleh pelanggan
Kadaluarsa	Permintaan kedaluwarsa karena tidak aktif atau batas waktu

Transisi Negara

Aliran Normal (Jalur Persetujuan)

• Tidak Ditugaskan → Ditugaskan: Pelanggan mengaitkan permintaan dengan akun mereka

• Ditugaskan → Diterima ATAU Ditugaskan → Persetujuan Tertunda: Pelanggan menyetujui permintaan secara langsung ATAU meneruskan ke administrator untuk ditinjau

• Persetujuan Tertunda → Diterima: Administrator menyetujui permintaan

• Diterima → Selesai: Pelanggan merilis token pertukaran

Jalur Penolakan

• Ditugaskan → Ditolak: Pelanggan menolak permintaan

• Persetujuan Tertunda → Ditolak: Administrator menolak permintaan

• Diterima → Ditolak: Pelanggan mencabut persetujuan sebelum merilis token

Jalur Kedaluwarsa

Permintaan secara otomatis kedaluwarsa jika tidak ada tindakan yang diambil dalam jangka waktu yang ditentukan:

• Tidak Ditugaskan → Kedaluwarsa (1 hari)

• Ditugaskan → Kedaluwarsa (7 hari)

• Persetujuan Tertunda → Kedaluwarsa (7 hari)

• Diterima → Kedaluwarsa (7 hari)

• Ditolak → Kedaluwarsa (7 hari)

• Finalisasi → Kedaluwarsa (7 hari)

Negara Terminal

Status berikut adalah terminal (tidak ada transisi lebih lanjut):

• Selesai: Token Pertukaran dikirim

• Ditolak: Permintaan ditolak

• Kedaluwarsa: Waktu permintaan habis atau periode delegasi berakhir

Permintaan kedaluwarsa akhirnya dihapus dari sistem setelah periode retensi.

Mengelola status permintaan delegasi dalam aplikasi Anda

Sebagai mitra, Anda harus melacak status permintaan delegasi di sistem Anda dan memunculkannya ke pelanggan Anda. Saat Anda menerima pemberitahuan SNS tentang perubahan status, simpan pembaruan ini di backend Anda dan cerminkan di UI yang menghadap pelanggan. Berikan perhatian khusus pada status Persetujuan Tertunda — saat pelanggan meneruskan permintaan ke administrator untuk ditinjau, AWS mengirimkan pemberitahuan Persetujuan Tertunda kepada Anda. Permintaan dapat tetap dalam status ini hingga 7 hari sambil menunggu tindakan administrator. Selama waktu ini, tunjukkan kepada pelanggan bahwa permintaan mereka sedang menunggu persetujuan administrator dalam aplikasi Anda. Pertimbangkan untuk menyediakan tautan dalam ke AWS Konsol tempat pelanggan dapat memeriksa status permintaan atau menindaklanjuti dengan administrator mereka. Menangani mesin status dengan benar di backend Anda dan menampilkan informasi status yang benar kepada pelanggan di setiap tahap penting untuk pengalaman integrasi yang baik.

Mengkonfigurasi Pemberitahuan

IAM menggunakan Amazon Simple Notification Service (SNS) untuk mengkomunikasikan perubahan status permintaan delegasi kepada Anda. Saat Anda membuat permintaan delegasi, Anda harus memberikan ARN topik SNS dari akun terdaftar Anda. AWS IAM akan mempublikasikan pesan ke topik ini untuk acara penting, termasuk ketika pelanggan menyetujui atau menolak permintaan dan ketika token pertukaran siap.

catatan

Topik SNS tidak dapat berada di Wilayah keikutsertaan AWS . Topik SNS Anda harus berada di AWS Wilayah yang diaktifkan secara default. Untuk daftar Wilayah keikutsertaan, lihat Mengelola AWS Wilayah dalam panduan Manajemen AWS Akun.

Konfigurasi Topik SNS

Untuk menerima pemberitahuan permintaan delegasi, Anda harus mengonfigurasi topik SNS Anda untuk memberikan izin IAM untuk mempublikasikan pesan ke sana. Tambahkan pernyataan kebijakan berikut ke kebijakan topik SNS Anda:

{
    "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"
        }
    ]
}

penting

Topik SNS harus ada di salah satu AWS akun terdaftar Anda. IAM tidak akan menerima topik SNS dari akun lain. Jika kebijakan topik tidak dikonfigurasi dengan benar, Anda tidak akan menerima pemberitahuan perubahan status atau token pertukaran.

Jenis Pemberitahuan

IAM mengirimkan dua jenis notifikasi:

StateChange Pemberitahuan

Dikirim ketika permintaan delegasi bertransisi ke status baru (Ditugaskan, Menunggu Persetujuan, Diterima, Diselesaikan, Ditolak, Kedaluwarsa).

ExchangeToken Pemberitahuan

Dikirim saat pelanggan merilis token delegasi (status Finalized). Pemberitahuan ini mencakup token pertukaran yang Anda butuhkan untuk mendapatkan kredensyal.

Status Pemberitahuan

Anda akan menerima pemberitahuan untuk status permintaan delegasi berikut:

Status	Jenis Pemberitahuan	Deskripsi
DITETAPKAN	StateChange	Permintaan telah dikaitkan dengan akun pelanggan
MENUNGGU PERSETUJUAN	StateChange	Pelanggan telah meneruskan permintaan ke administrator untuk persetujuan
DITERIMA	StateChange	Pelanggan telah menyetujui permintaan tetapi belum merilis token
DISELESAIKAN	StateChange	Pelanggan telah merilis token pertukaran
DISELESAIKAN	ExchangeToken	Pemberitahuan ini berisi Token Exchange
MENOLAK	StateChange	Pelanggan telah menolak permintaan
KEDALUWARSA	StateChange	Permintaan kedaluwarsa sebelum selesai

Format Pesan Pemberitahuan

IAM menerbitkan pemberitahuan SNS standar. Informasi permintaan delegasi terkandung dalam bidang Pesan sebagai string JSON.

Bidang Umum (Semua Pemberitahuan)

Bidang	Tipe	Deskripsi
Tipe	String	Entah "StateChange" atau "ExchangeToken”
RequestId	String	ID permintaan delegasi IAM
RequestorWorkflowId	String	ID alur kerja yang Anda berikan saat membuat permintaan
Status	String	Status permintaan saat ini
OwnerAccountId	String	ID AWS Rekening Nasabah
UpdatedAt	String	Stempel waktu saat status berubah (format ISO 8601)

Bidang Tambahan (Hanya ExchangeToken Pemberitahuan)

Bidang	Tipe	Deskripsi
ExchangeToken	String	Token untuk ditukar dengan kredensyal menggunakan API AWS STS GetDelegatedAccessToken
ExpiresAt	String	Ketika akses yang didelegasikan kedaluwarsa (format ISO 8601)

Contoh Pemberitahuan

StateChange Pemberitahuan

{
  "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 Pemberitahuan

{
  "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": "..."
}

Token Pertukaran

Token pertukaran atau perdagangan token dikeluarkan oleh IAM ketika pelanggan menerima dan menyelesaikan permintaan delegasi. Penyedia produk menggunakan pertukaran ini atau perdagangan token untuk memanggil AWS AWS STS GetDelegatedAccessToken API untuk mendapatkan AWS kredensi sementara dengan izin yang disetujui pelanggan. Token pertukaran itu sendiri tidak memberikan akses ke AWS sumber daya Anda; itu harus ditukar dengan kredensi aktual melalui STS. AWS

Token pertukaran hanya dapat ditukarkan oleh akun penyedia produk yang membuat permintaan delegasi. Akun yang meminta disematkan dalam token, memastikan bahwa hanya penyedia produk resmi yang dapat memperoleh kredensi untuk mengakses akun pelanggan.

Durasi Akses

Periode delegasi dimulai saat pelanggan merilis token pertukaran, bukan saat penyedia produk menebusnya. Setelah pelanggan merilis token:

• Penyedia produk menerima token melalui notifikasi SNS

• Mereka dapat segera menukarnya dengan kredensyal

• Kredensyal kedaluwarsa pada: waktu rilis+durasi yang disetujui

• Penyedia produk dapat menukar token beberapa kali sebelum kedaluwarsa untuk mendapatkan kredensyal baru jika diperlukan

Beberapa Penukaran

Penyedia produk dapat menukar token beberapa kali selama masa berlaku untuk mendapatkan kredensyal baru. Namun, semua kredensyal yang diperoleh dari token pertukaran yang sama kedaluwarsa pada saat yang sama, berdasarkan kapan Anda merilis token.

Contoh: Jika Anda menyetujui permintaan delegasi 2 jam dan melepaskan token pada pukul 10:00:

Waktu Rilis Token	Waktu Pertukaran Token	Kedaluwarsa Kredensi	Waktu yang Dapat Digunakan
10:00 pagi	10:00 pagi	12:00pm	2 jam
10:00 pagi	10:20 pagi	12:00pm	1 jam 40 menit
10:00 pagi	11:40am	12:00pm	20 menit
10:00 pagi	12:10pm	Gagal (token kedaluwarsa)	0 menit

Seperti yang ditunjukkan pada tabel, pertukaran token nanti dalam masa berlaku menghasilkan waktu yang kurang dapat digunakan untuk penyedia produk.