# Control del acceso a una API de REST con permisos de IAM
Puede controlar el acceso a su API de Amazon API Gateway con [permisos de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html) controlando el acceso a los dos procesos de componentes de API Gateway siguientes:
+ Para crear, implementar y administrar una API en API Gateway, debe conceder al desarrollador de la API permisos para realizar las acciones necesarias admitidas por el componente de administración de la API de API Gateway.
+ Para llamar a una API implementada o para actualizar el almacenamiento en caché de la API, debe conceder al intermediario de la API permisos para realizar las acciones de IAM necesarias admitidas por el componente de ejecución de la API de API Gateway.
El control de acceso para los dos procesos implica diferentes modelos de permisos, que se explican a continuación.
## Modelo de permisos de API Gateway para crear y administrar una API
Para permitir a un desarrollador de API crear y administrar una API en API Gateway debe [crear políticas de permisos de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) que permitan a un desarrollador de la API especificado crear, actualizar, implementar, ver o eliminar las [entidades de API](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) necesarias. Al asociar la política de permisos a un usuario, rol o grupo.
Para dar acceso, agregue permisos a los usuarios, grupos o roles:
+ Usuarios y grupos en AWS IAM Identity Center:
Cree un conjunto de permisos. Siga las instrucciones de [Creación de un conjunto de permisos](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) en la *Guía del usuario de AWS IAM Identity Center*.
+ Usuarios gestionados en IAM a través de un proveedor de identidades:
Cree un rol para la federación de identidades. Siga las instrucciones descritas en [Creación de un rol para un proveedor de identidad de terceros (federación)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) en la *Guía del usuario de IAM*.
+ Usuarios de IAM:
+ Cree un rol que el usuario pueda aceptar. Siga las instrucciones descritas en [Creación de un rol para un usuario de IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) en la *Guía del usuario de IAM*.
+ (No recomendado) Adjunte una política directamente a un usuario o agregue un usuario a un grupo de usuarios. Siga las instrucciones descritas en [Adición de permisos a un usuario (consola)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) de la *Guía del usuario de IAM*.
Para obtener más información sobre cómo usar este modelo de permisos, consulte [Políticas basadas en identidades de API Gateway](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies).
## Modelo de permisos de API Gateway para invocar una API
Para permitir a un intermediario de la API invocar la API o actualizar su caché, debe crear políticas de IAM que permitan a un intermediario de la API especificado invocar el método de API para el que se ha habilitado la autenticación de usuarios. El desarrollador de la API establece la propiedad `authorizationType` del método en `AWS_IAM` para exigir que el intermediario envíe las credenciales del usuario que se va a autenticar. API Gateway admite Signature Version 4a (SigV4a) y Signature Version 4 (SigV4) para autenticar las credenciales del usuario. Para obtener más información, consulte [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). A continuación, adjunte la política a un usuario, rol o grupo.
En esta instrucción de política de permisos de IAM, el elemento `Resource` de IAM contiene una lista de métodos de la API implementada identificados por verbos HTTP y [rutas de recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API Gateway. El elemento `Action` de IAM contiene las acciones de ejecución de API de API Gateway necesarias. Estas acciones incluyen `execute-api:Invoke` o `execute-api:InvalidateCache`, donde `execute-api` designa el componente de ejecución de la API subyacente de API Gateway.
Para obtener más información sobre cómo usar este modelo de permisos, consulte [Controlar el acceso para invocar una API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
Cuando una API está integrada con un servicio de AWS (por ejemplo, AWS Lambda) en el backend, API Gateway también debe tener permisos para obtener acceso a los recursos de AWS integrados (por ejemplo, invocar una función de Lambda) en nombre de la persona que llama a la API. Para otorgar estos permisos, cree un rol de IAM del tipo **servicio de AWS para API Gateway**. Cuando crea este rol en la consola de administración de IAM, este rol resultante contiene la siguiente política de confianza de IAM que designa a API Gateway como la entidad de confianza capaz de asumir el rol:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Si crea el rol de IAM llamando al comando [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) de la CLI o a un método del SDK correspondiente, debe proporcionar la política de confianza anterior como el parámetro de entrada de `assume-role-policy-document`. No intente crear esta política directamente en la consola de administración de IAM ni llamando al comando de la AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) ni a un método del SDK correspondiente.
Para que API Gateway llame al servicio de AWS integrado, también debe adjuntar a este rol las políticas de permisos de IAM correspondientes para llamar a los servicios de AWS integrados. Por ejemplo, para llamar a una función de Lambda, debe incluir la siguiente política de permisos de IAM en el rol de IAM:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}
```
------
Tenga en cuenta que Lambda admite la política de acceso basada en recursos, que combina políticas de confianza y de permisos. Cuando integre una API con una función de Lambda mediante la consola de API Gateway, no se le pedirá que establezca este rol de IAM explícitamente, porque la consola establece los permisos basados en recursos en la función de Lambda por usted, con su consentimiento.
**nota**
Para establecer el control del acceso a un servicio de AWS, puede utilizar el modelo de permisos basado en el intermediario, donde una política de permisos se asocia directamente al usuario o grupo del intermediario, o el modelo de permisos basado en rol, donde una política de permisos se asocia a un rol de IAM que API Gateway puede asumir. Los permisos de políticas pueden ser diferentes en los dos modelos. Por ejemplo, la política basada en el intermediario bloquea el acceso, mientras que la política basada en roles lo permite. Puede aprovechar esto para exigir que un usuario tenga acceso a un servicio de AWS solo a través de la API de API Gateway.
# Controlar el acceso para invocar una API
En esta sección, obtendrá información sobre el modelo de permisos para controlar el acceso a su API mediante permisos de IAM. Cuando la autorización de IAM está habilitada, los clientes deben utilizar Signature Version 4a (SigV4a) y Signature Version 4 (SigV4) para firmar las solicitudes con credenciales de AWS. Para obtener más información, consulte [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html).
En esta sección, mostramos una plantilla de declaración de política de IAM y la referencia de la declaración de política. La referencia de la declaración de política incluye los formatos de los campos `Action` y `Resource` relacionados con el servicio de ejecución de la API. Utilice estas referencias para crear su declaración de política de IAM. Cuando cree la declaración de política de IAM, es posible que deba tener en cuenta la forma en que las políticas de recursos de API Gateway afectan al flujo de trabajo de autorización. Para obtener más información, consulte [Cómo afectan las políticas de recursos de API Gateway al flujo de trabajo de autorización](apigateway-authorization-flow.md).
Para API privadas, debe utilizar una combinación de una política de recursos de API Gateway y una política de punto de enlace de la VPC. Para obtener más información, consulte los siguientes temas:
+ [Control del acceso a una API de REST con políticas de recursos de API Gateway](apigateway-resource-policies.md)
+ [Uso de políticas de punto de conexión de VPC para API privadas en API Gateway](apigateway-vpc-endpoint-policies.md)
## Controlar quién puede llamar a una API de API Gateway con políticas de IAM
Para controlar quién puede o no puede llamar a una API implementada con permisos de IAM, cree un documento de política de IAM con los permisos necesarios. A continuación, se muestra una plantilla para un documento de política como este.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Permission",
"Action": [
"execute-api:Execution-operation"
],
"Resource": [
"arn:aws:execute-api:region:123456789012:api-id/stage/METHOD_HTTP_VERB/Resource-path"
]
}
]
}
```
------
Aquí, `Permission` se sustituirá por `Allow` o `Deny` dependiendo de si desea conceder o revocar los permisos incluidos. `Execution-operation` se sustituirá por las operaciones compatibles con el servicio de ejecución de la API. `METHOD_HTTP_VERB` hace referencia a un verbo HTTP compatible con los recursos especificados. `Resource-path` es el marcador de posición de la ruta URL de una instancia de `[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)` de la API implementada que admite el `METHOD_HTTP_VERB` mencionado. Para obtener más información, consulte [Referencia de instrucciones de políticas de IAM para ejecutar la API en API Gateway](#api-gateway-calling-api-permissions).
**nota**
Para que las políticas de IAM sean eficaces, debe haber habilitado la autenticación de IAM en los métodos de API configurando `AWS_IAM` para la propiedad `[authorizationType](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)` de los métodos. En caso contrario, estos métodos de API serán accesibles públicamente.
Por ejemplo, para conceder a un usuario permiso para ver una lista de mascotas expuesta por una API determinada, pero denegarle permiso para agregar una mascota a la lista, se podría incluir la siguiente instrucción en la política de IAM:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/*/POST/pets"
]
}
]
}
```
------
Para conceder a un usuario permiso para ver una mascota específica expuesta por una API que se configura como `GET /pets/{petId}`, podría incluir la siguiente declaración en la política de IAM:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/*/GET/pets/a1b2"
]
}
]
}
```
------
## Referencia de instrucciones de políticas de IAM para ejecutar la API en API Gateway
La siguiente información describe el formato de Action y Resource de las instrucciones de política de IAM de permisos de acceso para ejecutar una API.
### Formato de Action de permisos para ejecutar la API en API Gateway
La expresión `Action` de ejecución de API tiene el siguiente formato general:
```
execute-api:action
```
donde *action* es una acción de ejecución de API disponible:
+ **\$1**, que representa todas las acciones siguientes.
+ **Invoke**, que se utiliza para invocar una API previa solicitud del cliente.
+ **InvalidateCache**, que se utiliza para invalidar la caché de API previa solicitud del cliente.
### Formato de Resource de permisos para ejecutar la API en API Gateway
La expresión `Resource` de ejecución de API tiene el siguiente formato general:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier
```
donde:
+ *region* es la región de AWS (como **us-east-1** o **\$1** para todas las regiones de AWS) que se corresponde con la API implementada para el método.
+ *account-id* es el ID de cuenta de 12 dígitos de AWS del propietario de la API de REST.
+ *api-id* es el identificador que API Gateway asignó a la API para el método.
+ *stage-name* es el nombre de la etapa asociada al método.
+ *HTTP-VERB* es el verbo HTTP del método. Puede ser uno de las siguientes: GET, POST, PUT, DELETE, PATCH.
+ *resource-path-specifier* es la ruta al método deseado.
**nota**
Si especifica un comodín (`*`), la expresión `Resource` aplica el comodín al resto de la expresión.
Algunos ejemplos de expresiones de recursos incluyen:
+ **arn:aws:execute-api:\$1:\$1:\$1** para cualquier ruta de recurso en cualquier etapa, para cualquier API de cualquier región de AWS.
+ **arn:aws:execute-api:us-east-1:\$1:\$1** para cualquier ruta de recurso en cualquier etapa, para cualquier API en la región de AWS `us-east-1`.
+ **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1** para cualquier ruta de recurso en cualquier etapa, para la API con el identificador *api-id* de la región de AWS us-east-1.
+ **arn:aws:execute-api:us-east-1:\$1:*api-id*/`test`/\$1** para cualquier ruta de recurso en la etapa de `test`, para la API con el identificador de *api-id* de la región de AWS us-east-1.
Para obtener más información, consulte [Referencia del nombre de recurso de Amazon (ARN) de API Gateway](arn-format-reference.md).
# Ejemplos de política de IAM para permisos de ejecución de la API
Para ver el modelo de permisos y otra información de referencia, consulte [Controlar el acceso para invocar una API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
La siguiente instrucción de política otorga al usuario permiso para llamar a cualquier método POST en la ruta `mydemoresource`, en la etapa `test`, para la API con el identificador `a123456789`, suponiendo que la API correspondiente se ha implementado en la región de AWS us-east-1:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*"
]
}
]
}
```
------
La siguiente instrucción de política de ejemplo concede al usuario permiso para llamar a cualquier método en la ruta del recurso `petstorewalkthrough/pets`, en cualquier etapa, para la API con el identificador `a123456789`, en cualquier región de AWS en la que se haya implementado la API correspondiente:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets"
]
}
]
}
```
------