# Uso de un rol de IAM de la AWS CLI
Un [rol de AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) es una herramienta de autorización que permite a un usuario conseguir permisos adicionales o distintos, u obtener permisos para realizar acciones en otra cuenta de AWS.
**Topics**
+ [
## Requisitos previos
](#cli-role-prereqs)
+ [
## Información general del uso de roles de IAM
](#cli-role-overview)
+ [
## Configuración y uso de un rol
](#cli-role-prepare)
+ [
## Uso de la autenticación multifactor
](#cli-configure-role-mfa)
+ [
## Roles entre cuentas e ID externo
](#cli-configure-role-xaccount)
+ [
## Especificación de un nombre de sesión de rol para simplificar las auditorías
](#cli-configure-role-session-name)
+ [
## Adopción de un rol con una identidad web
](#cli-configure-role-oidc)
+ [
## Borrado de las credenciales almacenadas en memoria caché
](#cli-configure-role-cache)
## Requisitos previos
Para utilizar los comandos de `iam`, debe instalar y configurar AWS CLI. Esto incluye la configuración de un perfil definido, como asumir que un rol está combinado con otro método de credenciales. Para obtener más información, consulte [Instalación o actualización de la versión más reciente de AWS CLI](getting-started-install.md).
## Información general del uso de roles de IAM
Puede configurar la AWS Command Line Interface (AWS CLI) para utilizar un rol de IAM definiendo un perfil para dicho rol en el archivo `~/.aws/config`.
En el siguiente ejemplo se muestra un perfil de rol llamado `marketingadmin`. Si ejecuta comandos con `--profile marketingadmin` (o lo especifica con la variable de entorno [AWS\$1DEFAULT\$1PROFILE](cli-configure-envvars.md)), la AWS CLI utiliza las credenciales definidas en un perfil separado de `user1` para adoptar el rol con el nombre de recurso de Amazon (ARN) `arn:aws:iam::123456789012:role/marketingadminrole`. Puede ejecutar cualquier operación permitida por los permisos asignados a ese rol.
```
[profile marketingadmin]
role_arn = arn:aws:iam::123456789012:role/marketingadminrole
source_profile = user1
```
Debe especificar un `source_profile` que apunte a un perfil con nombre independiente que contenga credenciales de usuario con permiso para utilizar el rol. En el ejemplo anterior, el perfil `marketingadmin` utiliza las credenciales en el perfil `user1`. Al especificar que un comando de la AWS CLI debe utilizar el perfil `marketingadmin`, la AWS CLI busca automáticamente las credenciales del perfil `user1` vinculado y las utiliza para solicitar credenciales temporales para el rol de IAM especificado. La CLI usa la operación [sts:AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) en segundo plano para llevar esto a cabo. Estas credenciales temporales se utilizan para ejecutar el comando de la AWS CLI solicitado. El rol especificado debe tener políticas de permisos de IAM asociadas que permitan que el comando de la AWS CLI solicitado se ejecute.
Para ejecutar un comando AWS CLI desde una instancia Amazon Elastic Compute Cloud (Amazon EC2) o un contenedor de Amazon Elastic Container Service (Amazon ECS), puede utilizar un rol de IAM asociado al perfil de instancia o al contenedor. Si no especifica ningún perfil o no establece ninguna variable de entorno, ese rol se utiliza directamente. De este modo, puede evitar el almacenamiento de las claves de acceso de larga duración en las instancias. También puede utilizar esos roles de instancia o contenedor solo para obtener credenciales para otro rol. Para ello, utilice `credential_source` (en lugar de `source_profile`) para especificar cómo encontrar las credenciales. El atributo `credential_source` es compatible con los siguientes valores:
+ `Environment`: recupera las credenciales fuente de las variables de entorno.
+ `Ec2InstanceMetadata`: utiliza el rol de IAM asociado al perfil de instancia de Amazon EC2.
+ `EcsContainer`: utiliza el rol de IAM adjunto al contenedor de Amazon ECS.
En el siguiente ejemplo, se muestra el mismo rol `marketingadminrole` que se utilizó al hacer referencia a un perfil de instancia de Amazon EC2:
```
[profile marketingadmin]
role_arn = arn:aws:iam::123456789012:role/marketingadminrole
credential_source = Ec2InstanceMetadata
```
Cuando invoca un rol, tiene otras opciones que puede exigir; por ejemplo, el uso de la autenticación multifactor y de un ID externo (que compañías de terceros utilizan para acceder a los recursos de sus clientes). También puede especificar nombres de sesión de roles únicos que puedan auditarse más fácilmente en registros AWS CloudTrail.
## Configuración y uso de un rol
Cuando se ejecutan comandos utilizando un perfil que especifica un rol de IAM, la AWS CLI emplea las credenciales del perfil fuente para llamar a AWS Security Token Service (AWS STS) y solicitar credenciales temporales para el rol especificado. El usuario del perfil fuente debe tener permiso para llamar a `sts:assume-role` en el rol del perfil especificado. El rol debe tener una relación de confianza que permita al usuario del perfil de origen utilizarlo. El proceso de recuperación y posterior uso de credenciales temporales en un rol a menudo se denomina *asumir el rol*.
Puede crear un rol en IAM con los permisos que quiera que adopten los usuarios siguiendo el procedimiento de [Creación de un rol para delegar permisos a un usuario de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) de la *Guía del usuario de AWS Identity and Access Management*. Si el rol y el usuario de del perfil de origen se encuentran en la misma cuenta, puede introducir su propio ID de cuenta al configurar la relación de confianza del rol.
Después de crear el rol, modifique la relación de confianza para permitir que el usuario de lo asuma.
En el siguiente ejemplo se muestra una política de confianza que puede asociarse a un rol. Esta política permite asumir el rol a cualquier usuario de la cuenta 123456789012, ***si*** el administrador de dicha cuenta le concede de forma explícita el permiso `sts:AssumeRole`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:root"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
La política de confianza no concede permisos. El administrador de la cuenta debe delegar el permiso para asumir el rol a usuarios individuales asociando una política a los permisos adecuados. En el siguiente ejemplo, se muestra una política que puede asociarse a un usuario y que le permite asumir únicamente el rol `marketingadminrole`. Para obtener más información acerca de cómo conceder permisos de acceso a los usuarios para asumir un rol, consulte [Conceción de permisos de usuario para cambiar de rol](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html) en la *Guía del usuario de IAM*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::123456789012:role/marketingadminrole"
}
]
}
```
------
El usuario no necesita permisos adicionales para ejecutar los comandos de la AWS CLI con el perfil del rol. En cambio, los permisos para ejecutar el comando proceden de los asociados al *rol*. Puede asociar políticas de permisos al rol para especificar qué acciones pueden realizarse en relación con qué recursos de AWS. Para obtener más información acerca de cómo asociar permisos a un rol (que funciona exactamente igual que para un usuario), consulte [Cambio de permisos de un usuario de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) en la *Guía del usuario de IAM*.
Ahora que ya tiene el perfil del rol, los permisos del rol, la relación de confianza del rol y los permisos de usuario configurados correctamente, puede utilizar el rol en la línea de comandos invocando la opción `--profile`. Por ejemplo, el siguiente comando llama al comando Amazon S3 de `ls` utilizando los permisos adjuntos al rol `marketingadmin` que se definieron en el ejemplo que se incluye al principio de este tema.
```
$ aws s3 ls --profile marketingadmin
```
Si desea utilizar el rol para varias llamadas, puede configurar la variable de entorno `AWS_PROFILE` para la sesión actual desde la línea de comandos. Siempre que esa variable de entorno se haya definido, no será necesario especificar la opción `--profile` en cada comando.
**Linux o macOS**
```
$ export AWS_PROFILE=marketingadmin
```
**Windows**
```
C:\> setx AWS_PROFILE marketingadmin
```
Para obtener información acerca de la configuración de los usuarios y los roles, consulte [Identidades de IAM (usuarios, grupos y roles)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) y [Roles de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id-roles.html) en la *Guía del usuario de IAM*.
## Uso de la autenticación multifactor
Para mayor seguridad, puede pedir a los usuarios que proporcionen una clave única generada a partir de un dispositivo de autenticación multifactor (MFA), un dispositivo U2F o una aplicación móvil cuando realicen una llamada utilizando el perfil del rol.
En primer lugar, puede elegir modificar la relación de confianza del rol de IAM para el que se requiere MFA. Esto impide que una persona utilice el rol sin autenticarse primero mediante MFA. A modo de ejemplo, vea la línea `Condition` en el siguiente ejemplo. Esta política permite a un usuario llamado `anika` adoptar el rol asociado a la política, pero solo si se autentica mediante MFA.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::123456789012:user/anika" },
"Action": "sts:AssumeRole",
"Condition": { "Bool": { "aws:multifactorAuthPresent": true } }
}
]
}
```
------
A continuación, agregue una línea al perfil del rol que especifique el ARN del dispositivo MFA del usuario. El siguiente archivo `config` de ejemplo muestra dos perfiles de rol que utilizan las claves de acceso del usuario `anika` para solicitar credenciales temporales para el rol `cli-role`. El usuario `anika` tiene permisos para asumir el rol, concedidos por la política de confianza del rol.
```
[profile role-without-mfa]
region = us-west-2
role_arn= arn:aws:iam::128716708097:role/cli-role
source_profile=cli-user
[profile role-with-mfa]
region = us-west-2
role_arn= arn:aws:iam::128716708097:role/cli-role
source_profile = cli-user
mfa_serial = arn:aws:iam::128716708097:mfa/cli-user
[profile cli-user]
region = us-west-2
output = json
```
El valor `mfa_serial` puede ser un ARN, tal como se muestra, o el número de serie de un token de MFA de hardware.
El primer perfil, `role-without-mfa`, no requiere MFA. Sin embargo, como la política de confianza asociada al rol del ejemplo anterior requiere MFA, cualquier intento de ejecutar un comando con este perfil produce un error.
```
$ aws iam list-users --profile role-without-mfa
An error occurred (AccessDenied) when calling the AssumeRole operation: Access denied
```
La segunda entrada del perfil, `role-with-mfa`, identifica el dispositivo MFA que se va a utilizar. Cuando el usuario intenta ejecutar un comando de la AWS CLI con este perfil, la AWS CLI le pide al usuario que introduzca la contraseña de un solo uso (OTP) proporcionada a través del dispositivo MFA. Si la autenticación MFA se realiza correctamente, el comando realiza la operación solicitada. La OTP no se muestra en la pantalla.
```
$ aws iam list-users --profile role-with-mfa
Enter MFA code for arn:aws:iam::123456789012:mfa/cli-user:
{
"Users": [
{
...
```
## Roles entre cuentas e ID externo
Puede permitir que los usuarios de utilicen roles que pertenezcan a diferentes cuentas si configura el rol como un rol entre cuentas. Al crear un rol, establezca el tipo de rol en **Another AWS account (Otra cuenta de )**, tal como se describe en [Creating a Role to Delegate Permissions to an IAM user (Creación de un rol para delegar permisos a un usuario de IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html). Si lo desea, seleccione **Require MFA (Requerir MFA)**. La opción **Require MFA (Requerir NFA)** configura la condición apropiada en la relación de confianza, tal y como se describe en [Uso de la autenticación multifactor](#cli-configure-role-mfa).
Si utiliza un [ID externo](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) para ofrecer mayor control sobre quién puede utilizar un rol entre cuentas, también debe añadir el parámetro `external_id` al perfil del rol. Esto se utiliza normalmente solo cuando la otra cuenta la controla alguien ajeno a su empresa u organización.
```
[profile crossaccountrole]
role_arn = arn:aws:iam::234567890123:role/SomeRole
source_profile = default
mfa_serial = arn:aws:iam::123456789012:mfa/saanvi
external_id = 123456
```
## Especificación de un nombre de sesión de rol para simplificar las auditorías
Cuando muchas personas comparten un rol, la auditoría se convierte en un desafío más. Deseará asociar cada operación invocada con la persona que invocó la acción. Sin embargo, cuando la persona utiliza un rol, la asunción del rol por parte de la persona es una acción independiente de la invocación de una operación y debe relacionar manualmente las dos.
Puede simplificar este proceso especificando nombres de sesión de rol únicos cuando los usuarios asumen un rol. Para ello, añada un parámetro `role_session_name` a cada perfil con nombre en el archivo `config` que especifica un rol. El valor `role_session_name` se pasa a la operación `AssumeRole` y pasa a formar parte del ARN de la sesión de rol. También se incluye en los registros de AWS CloudTrail de todas las operaciones registradas.
Por ejemplo, podría crear un perfil basado en roles de la siguiente manera.
```
[profile namedsessionrole]
role_arn = arn:aws:iam::234567890123:role/SomeRole
source_profile = default
role_session_name = Session_Maria_Garcia
```
De este modo, la sesión del rol tendría el siguiente ARN.
```
arn:aws:iam::234567890123:assumed-role/SomeRole/Session_Maria_Garcia
```
Además, todos los registros de AWS CloudTrail incluyen el nombre de la sesión del rol en la información obtenida para cada operación.
## Adopción de un rol con una identidad web
Puede configurar un perfil para indicar que la AWS CLI debe asumir un rol mediante la [identidad federada web y Open ID Connect (OIDC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html). Al especificar esto en un perfil, la AWS CLI realiza automáticamente la llamada a AWS STS de `AssumeRoleWithWebIdentity` correspondiente.
**nota**
Cuando especifica un perfil que utiliza un rol de IAM, la AWS CLI realiza las llamadas correspondientes para recuperar las credenciales temporales. Estas credenciales se guardan en `~/.aws/cli/cache`. Los comandos de la AWS CLI posteriores que especifican el mismo perfil utilizan las credenciales temporales almacenadas en caché hasta que caducan. En ese momento, la AWS CLI actualiza automáticamente las credenciales.
Para recuperar y utilizar credenciales temporales utilizando identidades federadas web, puede especificar los siguientes valores de configuración en un perfil compartido:
[role\$1arn](#cli-configure-role)
Especifica el ARN del rol que se va a adoptar.
web\$1identity\$1token\$1file
Especifica la ruta a un archivo que contiene un token de acceso de OAuth 2.0 o un ID de token de OpenID Connect proporcionado por el proveedor de identidad. La AWS CLI carga este archivo y pasa su contenido como el argumento `WebIdentityToken` de la operación `AssumeRoleWithWebIdentity`.
[role\$1session\$1name](#cli-configure-role-session-name)
Especifica un nombre opcional que se aplica a esta sesión de asunción de rol.
A continuación, se muestra un ejemplo de la configuración mínima necesaria para configurar un rol de adopción con un perfil de identidad web:
```
# In ~/.aws/config
[profile web-identity]
role_arn=arn:aws:iam:123456789012:role/RoleNameToAssume
web_identity_token_file=/path/to/a/token
```
También puede establecer esta configuración utilizando [variables de entorno](cli-configure-envvars.md):
AWS\$1ROLE\$1ARN
ARN del rol que se va a adoptar.
AWS\$1WEB\$1IDENTITY\$1TOKEN\$1FILE
La ruta al archivo de token de identidad web.
AWS\$1ROLE\$1SESSION\$1NAME
El nombre aplicado a esta sesión de asunción de rol.
**nota**
Actualmente, estas variables de entorno solo se aplican al rol que se va a adoptar con un proveedor de identidades web. No se aplican a la configuración general del proveedor de roles de adopción.
## Borrado de las credenciales almacenadas en memoria caché
Al utilizar un rol, la AWS CLI almacena en caché localmente las credenciales temporales hasta que caducan. La próxima vez que intente utilizarlas, la AWS CLI intentará renovarlas en su nombre.
Si las credenciales temporales del rol se [revocan](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html), no se renuevan automáticamente y se producirá un error al intentar utilizarlas. Sin embargo, puede eliminar la caché para obligar a la AWS CLI a que recupere nuevas credenciales.
**Linux o macOS**
```
$ rm -r ~/.aws/cli/cache
```
**Windows**
```
C:\> del /s /q %UserProfile%\.aws\cli\cache
```