Criação da sua integração

Noções básicas sobre o ciclo de vida de solicitações

Antes de criar sua integração, é importante entender o fluxo das solicitações de delegação, desde a sua criação até a conclusão.

Estados das solicitações

Uma solicitação de delegação passa pelos seguintes estados:

Estado	Descrição
Não atribuída	Solicitação criada, mas ainda não associada a uma conta de cliente e a uma entidade principal do IAM. A solicitação pode ter sido criada sem a especificação de uma conta de destino ou com um ID da conta de destino, mas ainda não reivindicada pelo proprietário da conta.
Atribuída	Solicitação associada a uma conta de cliente e aguardando análise.
Aprovação pendente	O cliente encaminhou a solicitação a um administrador para aprovação.
Aceito	Solicitação aprovada pelo cliente, mas o token de troca ainda não foi liberado.
Finalizada	Token de troca liberado para o provedor do produto. O período de delegação (validade do token de troca) começa quando a solicitação chega ao estado Finalizada.
Rejeitado	Solicitação rejeitada pelo cliente.
Expirada	A solicitação expirou devido à inatividade ou ao tempo limite.

Transições de estados

Fluxo normal (caminho de aprovação)

• Não atribuída → Atribuída: o cliente associa a solicitação à sua conta

• Atribuída → Aceita OU Atribuída → Aprovação pendente: o cliente aprova a solicitação diretamente OU encaminha ao administrador para análise

• Aprovação pendente → Aceita: o administrador aprova a solicitação

• Aceita → Finalizada: o cliente libera o token de troca

Caminho da rejeição

• Atribuída → Rejeitada: o cliente rejeita a solicitação

• Aprovação pendente → Rejeitada: o administrador rejeita a solicitação

• Aceita → Rejeitada: o cliente revoga a aprovação antes de liberar o token

Caminho da expiração

As solicitações expiram automaticamente quando nenhuma ação é executada dentro do prazo especificado:

• Não atribuída → Expirada (1 dia)

• Atribuída → Expirada (7 dias)

• Aprovação pendente → Expirada (7 dias)

• Aceita → Expirada (7 dias)

• Rejeitada → Expirada (7 dias)

• Finalizada → Expirada (7 dias)

Status terminais

Os seguintes estados são terminais (sem mais transições):

• Finalizada: token de troca enviado

• Rejeitada: a solicitação foi negada

• Expirada: a solicitação atingiu o tempo limite ou o período de delegação terminou

As solicitações expiradas são excluídas do sistema após o período de retenção.

Gerenciamento dos estados de solicitação de delegação em sua aplicação

Como parceiro, você deve rastrear os estados de solicitação de delegação em seu sistema e apresentá-los aos seus clientes. Ao receber notificações do SNS sobre mudanças de estado, armazene essas atualizações em seu backend e as reflita na interface de usuário voltada para o cliente. Preste atenção especial ao estado Aprovação pendente: quando um cliente encaminha uma solicitação a um administrador para análise, a AWS envia uma notificação de Aprovação pendente para você. As solicitações podem permanecer nesse estado por até sete dias enquanto aguardam a ação do administrador. Durante esse período, mostre aos clientes que a solicitação deles está pendente e precisa da aprovação do administrador em sua aplicação. Considere fornecer um link direto para o Console da AWS, onde os clientes possam verificar o status da solicitação ou entrar em contato com o administrador. O gerenciamento correto da máquina de estado em seu backend e a apresentação das informações de estado corretas aos clientes em cada estágio é importante para uma boa experiência de integração.

Configuração de notificações

O IAM usa o Amazon Simple Notification Service (SNS) para comunicar a você as alterações de estado da solicitação de delegação. Ao criar uma solicitação de delegação, você deve fornecer um ARN do tópico do SNS da sua conta registrada da AWS. O IAM publicará mensagens sobre esse tópico para eventos importantes, incluindo quando os clientes aprovarem ou rejeitarem solicitações e quando o token de troca estiver pronto.

nota

Os tópicos do SNS não podem estar em regiões de aceitação da AWS. Seu tópico do SNS deve estar em uma região da AWS habilitada por padrão. Para obter uma lista de regiões de aceitação, consulte Gerenciamento de regiões da AWS no Guia de gerenciamento de contas da AWS.

Configuração do tópico do SNS

Para receber notificações de solicitações de delegação, você deve configurar seu tópico do SNS para conceder permissões ao IAM para publicar mensagens nele. Adicione a seguinte instrução de política à política do tópico do 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"
        }
    ]
}

Importante

O tópico do SNS deve estar em uma de suas contas registradas da AWS. O IAM não aceitará tópicos do SNS de outras contas. Se a política do tópico não estiver configurada corretamente, você não receberá notificações de alteração de estado ou o token de troca.

Tipos de notificação

O IAM envia dois tipos de notificações:

Notificações de StateChange

Enviadas quando uma solicitação de delegação passa para um novo estado (Atribuída, Aprovação pendente, Aceita, Finalizada, Rejeitada, Expirada).

Notificações de ExchangeToken

Enviadas quando um cliente libera o token de delegação (estado Finalizada). Essa notificação inclui o token de troca de que você precisa para obter as credenciais.

Estados das notificações

É possível receber notificações para os seguintes estados de solicitações de delegação:

Estado	Tipo de notificação	Descrição
ATRIBUÍDA	StateChange	A solicitação foi associada a uma conta de cliente
APROVAÇÃO PENDENTE	StateChange	O cliente encaminhou a solicitação a um administrador para aprovação.
ACEITA	StateChange	O cliente aprovou a solicitação, mas ainda não liberou o token
FINALIZADA	StateChange	O cliente liberou o token de troca
FINALIZADA	ExchangeToken	Essa notificação contém o token de troca
REJEITADA	StateChange	O cliente rejeitou a solicitação
EXPIRADA	StateChange	A solicitação expirou antes da conclusão

Formato das mensagens de notificação

O IAM publica notificações padrão do SNS. As informações da solicitação de delegação encontram-se no campo Mensagem como uma string JSON.

Campos comuns (todas as notificações)

Campo	Tipo	Descrição
Type	String	“StateChange” ou “ExchangeToken”
RequestId	String	O ID da solicitação de delegação do IAM
RequestorWorkflowId	String	O ID do fluxo de trabalho que você forneceu ao criar a solicitação
Estado	String	Estado atual da solicitação
OwnerAccountId	String	ID da conta da AWS do cliente
UpdatedAt	String	Carimbo de data e hora em que o estado mudou (formato ISO 8601)

Campos adicionais (somente notificações de ExchangeToken)

Campo	Tipo	Descrição
ExchangeToken	String	O token a ser trocado por credenciais usando a API GetDelegatedAccessToken do AWS STS
ExpiresAt	String	Quando o acesso delegado expira (formato ISO 8601)

Exemplo de notificações

Notificação de 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": "..."
}

Notificação de 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": "..."
}

Tokens de troca

Um token de troca ou um token de intercâmbio é emitido pelo IAM quando um cliente aceita e finaliza uma solicitação de delegação. O provedor do produto usa esse token de troca ou de intercâmbio para chamar a API GetDelegatedAccessToken do AWS AWS STS e obter credenciais temporárias da AWS com as permissões aprovadas pelos clientes. O token de troca em si não concede acesso aos seus recursos da AWS; ele deve ser trocado por credenciais reais por meio do AWS STS.

O token de troca só pode ser resgatado pela conta do provedor do produto que criou a solicitação de delegação. A conta solicitante está incorporada ao token, garantindo que somente o provedor autorizado do produto possa obter as credenciais para acessar a conta do cliente.

Duração do acesso

O período de delegação começa quando o cliente libera o token de troca, não quando o provedor do produto o resgata. Depois que o cliente liberar o token:

• O provedor do produto recebe o token via notificação do SNS

• Ele pode trocá-lo imediatamente por credenciais

• As credenciais expiram em: hora da liberação + duração aprovada

• O provedor do produto pode trocar o token várias vezes antes do vencimento para obter novas credenciais, se necessário

Vários resgates

Os provedores de produtos podem trocar o token várias vezes durante o período de validade para obter novas credenciais. No entanto, todas as credenciais obtidas do mesmo token de troca expiram ao mesmo tempo, com base em quando você liberou o token.

Exemplo: se você aprovar uma solicitação de delegação de duas horas e liberar o token às 10h:

Hora de liberação do token	Tempo de troca do token	Expiração da credencial	Tempo utilizável
10:00 am	10:00 am	12:00h	2 horas
10:00 am	10h20	12:00h	1 hora e 40 minutos
10:00 am	11h40	12:00h	20 minutos
10:00 am	12:10h	Falha (o token expirou)	0 minuto

Conforme mostrado na tabela, trocar o token mais tarde no período de validade resulta em menos tempo de utilização para o provedor do produto.