Creación de una integración

Descripción del ciclo de vida de una solicitud

Antes de crear la integración, es importante entender cómo avanzan las solicitudes de delegación desde su creación hasta su finalización.

Estados de las solicitudes

Una solicitud de delegación pasa por los siguientes estados:

Estado	Descripción
Sin asignar	Solicitud creada, pero aún no asociada a ninguna cuenta de cliente ni entidad principal de IAM. Es posible que la solicitud se haya creado sin especificar una cuenta de destino o con un ID de cuenta de destino, pero el propietario de la cuenta aún no la reclamó.
Asignada	Solicitud asociada a una cuenta de cliente y pendiente de revisión.
Aprobación pendiente	El cliente reenvió la solicitud a un administrador para su aprobación.
Aceptada	El cliente aprobó la solicitud, pero el token de intercambio aún no se liberó.
Finalizada	El token de intercambio se liberó al proveedor del producto. El periodo de delegación (validez del token de intercambio) comienza cuando la solicitud alcanza el estado Finalizada.
Rechazada	Solicitud rechazada por el cliente.
Vencido	Solicitud vencida debido a inactividad o a que se agotó el tiempo de espera.

Transiciones de los estados

Flujo normal (ruta de aprobación)

• Sin asignar → Asignada: el cliente asocia la solicitud a su cuenta.

• Asignada → Aceptada O Asignada → Aprobación pendiente: el cliente aprueba la solicitud directamente O la reenvía al administrador para que la revise.

• Aprobación pendiente → Aceptada: el administrador aprueba la solicitud.

• Aceptada → Finalizada: el cliente libera el token de intercambio.

Ruta de rechazo

• Asignada → Rechazada: el cliente rechaza la solicitud.

• Aprobación pendiente → Rechazada: el administrador rechaza la solicitud.

• Aceptada → Rechazada: el cliente revoca la aprobación antes de liberar el token.

Ruta de vencimiento

Las solicitudes vencen automáticamente si no se lleva a cabo ninguna acción en el plazo especificado:

• Sin asignar → Vencida (1 día)

• Asignada → Vencida (7 día)

• Aprobación pendiente → Vencida (7 días)

• Aceptada → Vencida (7 día)

• Rechazada → Vencida (7 día)

• Finalizada → Vencida (7 días)

Estados terminales

Los siguientes estados son terminales (no hay más transiciones):

• Finalizada: se envió el token de intercambio.

• Rechazada: se denegó la solicitud.

• Vencida: se agotó el tiempo de espera de la solicitud o finalizó el periodo de delegación.

Las solicitudes vencidas se eliminan finalmente del sistema una vez finalizado el periodo de retención.

Administración de los estados de las solicitudes de delegación en su aplicación

Como socio, debe hacer un seguimiento de los estados de las solicitudes de delegación en su sistema y mostrarlos a sus clientes. Cuando reciba notificaciones de SNS sobre cambios de estado, almacene estas actualizaciones en su backend y refléjelas en la interfaz de usuario dirigida al cliente. Preste especial atención al estado Aprobación pendiente; cuando un cliente reenvía una solicitud a un administrador para que la revise, AWS le envía una notificación de aprobación pendiente. Las solicitudes pueden permanecer en este estado durante un máximo de 7 días mientras esperan una acción del administrador. Durante este tiempo, muestre a los clientes que su solicitud está pendiente de aprobación del administrador en tu aplicación. Considere la posibilidad de proporcionar un enlace profundo a la Consola de AWS donde los clientes puedan comprobar el estado de la solicitud o hacer un seguimiento con su administrador. Para una buena experiencia de integración, es importante gestionar correctamente la máquina de estados de su backend y mostrar a los clientes la información de estado correcta en cada etapa.

Configuración de notificaciones

IAM utiliza Amazon Simple Notification Service (SNS) para comunicarle los cambios de estado de las solicitudes de delegación. Al crear una solicitud de delegación, debe proporcionar el ARN de un tema de SNS de su cuenta de AWS registrada. IAM publicará mensajes en este tema sobre eventos importantes, como cuando los clientes aprueben o rechacen las solicitudes y cuando el token de intercambio esté listo.

nota

Los temas de SNS no pueden estar en las regiones de AWS registradas. Su tema de SNS debe estar en una región de AWS que esté habilitada de forma predeterminada. Para ver una lista de las regiones registradas, consulte Administración de regiones de AWS en la Guía de administración de cuentas de AWS.

Configuración de temas de SNS

Para recibir notificaciones de solicitudes de delegación, debe configurar su tema de SNS para conceder permisos de IAM a fin de publicar mensajes en él. Agregue la siguiente instrucción de política a la política del tema de 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

El tema de SNS debe estar en una de sus cuentas de AWS registradas. IAM no aceptará temas de SNS de otras cuentas. Si la política del tema no está configurada correctamente, no recibirá notificaciones de cambio de estado ni el token de intercambio.

Tipos de notificaciones

IAM envía dos tipos de notificaciones:

Notificaciones de StateChange

Se envía cuando una solicitud de delegación pasa a un nuevo estado (Asignada, Pendiente de aprobación, Aceptada, Finalizada, Rechazada o Vencida).

Notificaciones de ExchangeToken

Se envía cuando un cliente libera el token de delegación (estado Finalizada). Esta notificación incluye el token de intercambio que necesita para obtener las credenciales.

Estados de las notificaciones

Recibirá notificaciones de los siguientes estados de las solicitudes de delegación:

Estado	Tipo de notificación	Descripción
ASIGNADA	Cambio de estado	La solicitud se asoció a una cuenta de cliente.
APROBACIÓN PENDIENTE	Cambio de estado	El cliente reenvió la solicitud a un administrador para su aprobación.
ACEPTADA	Cambio de estado	El cliente aprobó la solicitud, pero el token de intercambio aún no se liberó.
FINALIZADA	Cambio de estado	El cliente liberó el token de intercambio.
FINALIZADA	ExchangeToken	Esta notificación contiene el token de intercambio.
REJECTED	Cambio de estado	El cliente rechazó la solicitud.
EXPIRED	Cambio de estado	La solicitud venció antes de completarse.

Formato de los mensajes de notificación

IAM publica notificaciones de SNS estándar. La información de la solicitud de delegación se incluye en el campo Message en forma de cadena JSON.

Campos comunes (todas las notificaciones)

Campo	Tipo	Descripción
Tipo	Cadena	“StateChange” o “ExchangeToken”.
RequestId	Cadena	ID de la solicitud de delegación de IAM.
RequestorWorkflowId	Cadena	ID del flujo de trabajo que proporcionó al crear la solicitud.
Estado	Cadena	Estado actual de la solicitud.
OwnerAccountId	Cadena	ID de la cuenta de AWS del cliente.
UpdatedAt	Cadena	Marca de tiempo del momento en que se cambió el estado (formato ISO 8601).

Campos adicionales (solo notificaciones de ExchangeToken)

Campo	Tipo	Descripción
ExchangeToken	Cadena	Token que se va a intercambiar por credenciales mediante la API GetDelegatedAccessToken de AWS STS.
ExpiresAt	Cadena	Momento en que vence el acceso delegado (formato ISO 8601).

Notificaciones de ejemplo

Notificación 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": "..."
}

Notificación 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 intercambio

IAM emite un token de intercambio cuando un cliente acepta y finaliza una solicitud de delegación. El proveedor del producto utiliza este token de intercambio para llamar a la API GetDelegatedAccessToken de AWS AWS STS y obtener credenciales temporales de AWS con los permisos aprobados por los clientes. El token de intercambio en sí no otorga acceso a sus recursos de AWS; debe intercambiarse por credenciales reales a través de AWS STS.

El token de intercambio solo lo puede canjear la cuenta del proveedor del producto que creó la solicitud de delegación. La cuenta solicitante está incrustada en el token, lo que garantiza que solo el proveedor del producto autorizado pueda obtener las credenciales para acceder a la cuenta del cliente.

Duración del acceso

El periodo de delegación comienza cuando el cliente libera el token de intercambio, no cuando el proveedor del producto lo canjea. Una vez que el cliente libere el token:

• El proveedor del producto recibe el token mediante una notificación de SNS.

• Puede intercambiarlo inmediatamente por credenciales.

• Las credenciales caducan en: hora de liberación + duración aprobada.

• El proveedor del producto puede intercambiar el token varias veces antes de que venza para obtener credenciales nuevas si es necesario.

Varios canjes

Los proveedores de productos pueden intercambiar el token varias veces durante el periodo de validez para obtener credenciales nuevas. Sin embargo, todas las credenciales obtenidas del mismo token de intercambio caducan al mismo tiempo, según el momento en que se haya liberado el token.

Ejemplo: Si aprueba una solicitud de delegación de 2 horas y libera el token a las 10:00 h:

Hora de liberación del token	Hora de intercambio del token	Vencimiento de la credencial	Tiempo de uso
10:00 am	10:00 am	12:00 pm	2 horas
10:00 am	10:20 a. m.	12:00 pm	1 hora y 40 minutos
10:00 am	11:40 a. m.	12:00 pm	20 minutos
10:00 am	12:10 pm	Error (token vencido)	0 minutos

Como se muestra en la tabla, intercambiar el token más adelante en el periodo de validez reduce el tiempo de uso para el proveedor del producto.