# Integración de una API REST con un grupo de usuarios de Amazon Cognito Después de crear un grupo de usuarios de Amazon Cognito, en API Gateway, debe crear un autorizador `COGNITO_USER_POOLS` que utilice el grupo de usuarios. El siguiente procedimiento muestra cómo hacer esto con la consola de API Gateway. **nota** Puede utilizar la acción [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) para crear un autorizador de `COGNITO_USER_POOLS` que utilice varios grupos de usuarios. Puede usar hasta 1000 grupos de usuarios para un autorizador de `COGNITO_USER_POOLS`. Este límite no se puede aumentar. **importante** Después de realizar cualquiera de los procedimientos que aparecen a continuación, deberá implementar o volver a implementar la API para propagar los cambios. Para obtener más información acerca cómo implementar una API, consulte [Implementación de las API de REST en API Gateway](how-to-deploy-api.md). **Para crear un autorizador `COGNITO_USER_POOLS` mediante la consola de API Gateway** 1. Cree una nueva API o seleccione una existente en API Gateway. 1. En el panel de navegación principal, elija **Autorizadores**. 1. Elija **Crear autorizador**. 1. Si desea configurar el nuevo autorizador para que utilice un grupo de usuarios, realice lo siguiente: 1. En **Nombre del autorizador**, ingrese un nombre. 1. En **Tipo de autorizador**, seleccione **Cognito**. 1. En **Grupo de usuarios de Cognito**, elija la Región de AWS donde creó Amazon Cognito y seleccione un grupo de usuarios disponible. Puede utilizar una variable de etapa para definir su grupo de usuarios. Utilice el formato siguiente para su grupo de usuarios: `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`. 1. En **Origen del token**, escriba **Authorization** como nombre del encabezado al que se va a pasar el token de identidad o acceso devuelto por Amazon Cognito cuando el usuario inicie sesión correctamente. 1. (Opcional) Ingrese una expresión regular en el campo **Validación de token** para validar el campo `aud` (audiencia) del token de identidad antes de autorizar la solicitud con Amazon Cognito. Tenga en cuenta que cuando se utiliza un token de acceso, esta validación rechaza la solicitud debido al token de acceso que no contiene el campo `aud`. 1. Elija **Crear autorizador**. 1. Después de crear el autorizador de `COGNITO_USER_POOLS`, puede realizar una prueba e invocarlo proporcionando un token de identidad aprovisionado desde el grupo de usuarios. No puede usar un token de acceso para realizar una prueba e invocar el autorizador. Puede obtener este token de identidad llamando al [SDK de identidad de Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) para realizar el inicio de sesión del usuario. También puede usar la acción [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html). Si no configura ningún **Ámbito de autorización**, API Gateway trata el token suministrado como un token de identidad. El procedimiento anterior crea un autorizador `COGNITO_USER_POOLS` que utiliza el grupo de usuarios de Amazon Cognito que acaba de crearse. En función del modo en que se habilite el autorizador en un método de la API, puede utilizar un token de identidad o un token de acceso aprovisionado desde el grupo de usuarios integrados. **Para configurar un autorizador de `COGNITO_USER_POOLS` en los métodos** 1. Seleccione **Recursos**. Elija un nuevo método o elija un método existente. Si es necesario, cree un recurso. 1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**. 1. En **Autorizador**, en el menú desplegable, seleccione los **autorizadores del grupo de usuarios de Amazon Cognito** que acaba de crear. 1. Para utilizar un token de identidad, haga lo siguiente: 1. Mantenga los **ámbitos de autorización** vacíos. 1. Si fuera necesario, en la **Solicitud de integración**, agregue las expresiones `$context.authorizer.claims['property-name']` o `$context.authorizer.claims.property-name` a una plantilla de asignación de cuerpo para pasar la propiedad especificada de las reclamaciones de identidad desde el grupo de usuarios al backend. En el caso de los nombres de propiedades sencillos, como `sub` o `custom-sub`, las dos notaciones son idénticas. En el caso de los nombres de propiedades complejos, como `custom:role`, no se puede usar la notación de puntos. Por ejemplo, las siguientes expresiones de asignación pasan los [campos estándar](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) `sub` y `email` de la reclamación al backend: ``` { "context" : { "sub" : "$context.authorizer.claims.sub", "email" : "$context.authorizer.claims.email" } } ``` Si declaró un campo de reclamación personalizado al configurar un grupo de usuarios, puede seguir el mismo patrón para obtener acceso a los campos personalizados. El siguiente ejemplo obtiene un campo `role` personalizado de una reclamación: ``` { "context" : { "role" : "$context.authorizer.claims.role" } } ``` Si el campo personalizado de la reclamación está declarado como `custom:role`, utilice el siguiente ejemplo para obtener la propiedad de la reclamación: ``` { "context" : { "role" : "$context.authorizer.claims['custom:role']" } } ``` 1. Para utilizar un token de acceso, haga lo siguiente: 1. En **Ámbitos de autorización**, escriba uno o varios nombres completos de un ámbito que se haya configurado cuando se creó el grupo de usuarios de Amazon Cognito. Por ejemplo, siguiendo el ejemplo de [Creación de un grupo de usuarios de Amazon Cognito para una API REST](apigateway-create-cognito-user-pool.md), uno de los ámbitos es `https://my-petstore-api.example.com/cats.read`. En tiempo de ejecución, la llamada al método se realiza correctamente si el ámbito especificado en el método durante este paso coincide con el ámbito solicitado en el token de entrada. De lo contrario, la solicitud envía una respuesta de error `401 Unauthorized`. 1. Seleccione **Save**. 1. Repita estos pasos con otros métodos que elija. Con el autorizador `COGNITO_USER_POOLS`, si la opción **OAuth Scopes** no está especificada, API Gateway trata el token proporcionado como un token de identidad y comprueba si la identidad solicitada se corresponde con alguna del grupo de usuarios. De lo contrario, API Gateway trata el token suministrado como un token de acceso y comprueba si los ámbitos de acceso solicitados en el token tienen coincidencias con los ámbitos de autorización declarados en el método. En lugar de utilizar la consola de API Gateway, también puede habilitar un grupo de usuarios de Amazon Cognito en un método especificando un archivo de definición de OpenAPI e importando la definición de la API en API Gateway. **Para importar un autorizador COGNITO\$1USER\$1POOLS con un archivo de definición de OpenAPI** 1. Cree (o exporte) un archivo de definición de OpenAPI para la API. 1. Especifique la definición JSON del autorizador `COGNITO_USER_POOLS` (`MyUserPool`) en la sección `securitySchemes` de OpenAPI 3.0 o en la sección `securityDefinitions` de Open API 2.0, tal como se indica a continuación: ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. Para utilizar el token de identidad en la autorización del método, agregue `{ "MyUserPool": [] }` a la definición `security` del método, tal y como se muestra en el siguiente método GET del recurso raíz. ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": [] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Si desea utilizar el token de acceso para la autorización del método, cambie la definición de seguridad anterior a `{ "MyUserPool": [resource-server/scope, ...] }`: ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Si es necesario, puede establecer otra configuración de la API utilizando las definiciones o extensiones de OpenAPI correspondientes. Para obtener más información, consulte [Extensiones de OpenAPI para API Gateway](api-gateway-swagger-extensions.md).