# Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador Además de utilizar [roles y políticas de IAM](permissions.md) o [autorizadores de Lambda](apigateway-use-lambda-authorizer.md) (que anteriormente se denominaban autorizadores personalizados), también puede utilizar un [grupo de usuarios de Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) para controlar quién puede tener acceso a la API en Amazon API Gateway. Para utilizar un grupo de usuarios de Amazon Cognito con la API, primero debe crear un autorizador del tipo `COGNITO_USER_POOLS` y configurar después un método de API para que utilice ese autorizador. Una vez implementada la API, lo primero que debe hacer el cliente es registrar al usuario en el grupo de usuarios, obtener un [token de acceso o identidad](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) para el usuario y llamar al método de API con uno de los tokens, que normalmente están establecidos en el encabezado `Authorization` de la solicitud. La llamada a la API solo tendrá éxito si se suministra el token solicitado y este es válido; de lo contrario, el cliente no tendrá autorización para hacer la llamada, ya que carecerá de las credenciales que permitirían autorizarlo. El token de identidad se utiliza para autorizar las llamadas a la API en función de las solicitudes de identidad del usuario conectado. El token de acceso se utiliza para autorizar las llamadas a la API en función de los ámbitos personalizados de los recursos con protección de acceso especificados. Para obtener más información, consulte [Uso de tokens con grupos de usuarios](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) y [Servidor de recursos y ámbitos personalizados](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Si desea crear y configurar un grupo de usuarios de Amazon Cognito para la API, debe realizar las siguientes tareas: + Utilice la API, la CLI, el SDK o la consola de Amazon Cognito para crear un grupo de usuarios; también puede utilizar un grupo de usuarios que pertenezca a otra cuenta de AWS. + Utilice la API, la CLI, el SDK o la consola de API Gateway para crear un autorizador de API Gateway con el grupo de usuarios elegido. + Utilice la API, la CLI, el SDK o la consola de API Gateway para habilitar el autorizador de los métodos de API seleccionados. Para llamar a los métodos de API con un grupo de usuarios habilitado, los clientes de la API tienen que realizar las siguientes tareas: + Utilice la API, la CLI o el SDK de Amazon Cognito para registrar el usuario en el grupo de usuarios elegido y obtener un token de identidad o acceso. Para obtener más información sobre el uso de los SDK, consulte [Ejemplos de código de Amazon Cognito con AWS SDK](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html). + Utilice una plataforma específica del cliente para llamar a la API de API Gateway implementada y proporcione el token apropiado en el encabezado `Authorization`. Como desarrollador de la API, debe proporcionar a los desarrolladores del cliente el ID del grupo de usuarios, el ID del cliente y, probablemente, los secretos del cliente asociados que se hayan definido con el grupo de usuarios. **nota** Si desea permitir que un usuario inicie sesión con las credenciales de Amazon Cognito y pueda obtener también unas credenciales temporales para utilizarlas con los permisos de un rol de IAM, utilice las [identidades federadas de Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html). Para cada método HTTP de punto de enlace de recurso de API, establezca el tipo de autorización, categoría `Method Execution`, en `AWS_IAM`. En esta sección, se explica cómo crear un grupo de usuarios, cómo integrar una API de API Gateway con el grupo de usuarios y cómo invocar una API que está integrada con el grupo de usuarios. **Topics** + [Creación de un grupo de usuarios de Amazon Cognito para una API REST](apigateway-create-cognito-user-pool.md) + [Integración de una API REST con un grupo de usuarios de Amazon Cognito](apigateway-enable-cognito-user-pool.md) + [Llamar a una API REST integrada con un grupo de usuarios de Amazon Cognito](apigateway-invoke-api-integrated-with-cognito-user-pool.md) + [Configuración de un autorizador de Amazon Cognito entre cuentas para una API REST mediante la consola de API Gateway](apigateway-cross-account-cognito-authorizer.md) + [Cree un autorizador de Amazon Cognito para una API de REST con CloudFormation](apigateway-cognito-authorizer-cfn.md) # Creación de un grupo de usuarios de Amazon Cognito para una API REST Antes de integrar la API con un grupo de usuarios, debe crear el grupo de usuarios en Amazon Cognito. La configuración del grupo de usuarios debe cumplir con todas las [cuotas de recursos de Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). Todas las variables de Amazon Cognito definidas por el usuario, como grupos, usuarios y roles, deben usar solo caracteres alfanuméricos. Para obtener instrucciones sobre cómo crear un grupo de usuarios, consulte [Tutorial: Creación de un grupo de usuarios](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) en la *Guía para desarrolladores de Amazon Cognito*. Apunte el ID del grupo de usuarios, el ID del cliente y la clave secreta del cliente. El cliente debe proporcionarlos a Amazon Cognito para que el usuario pueda registrarse en el grupo de usuarios, para iniciar sesión en el grupo de usuarios y para obtener un token de identidad o acceso, que debe incluirse en las solicitudes para llamar a los métodos de la API configurados con el grupo de usuarios. Además, se debe especificar el nombre del grupo de usuarios al configurar el grupo de usuarios como autorizador de API Gateway, tal y como se describe a continuación. Si utiliza tokens de acceso para autorizar las llamadas a los métodos de la API, asegúrese de configurar la integración de aplicaciones con el grupo de usuarios para establecer los ámbitos que desee en un determinado servidor de recursos. Para obtener más información sobre el uso de tokens con grupos de usuarios de Amazon Cognito, consulte [Uso de tokens con grupos de usuarios](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Para obtener más información acerca de los servidores de recursos, consulte [Definir servidores de recursos para su grupo de usuarios](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Anote los identificadores del servidor de recursos configurados y los nombres de ámbito personalizados. Los necesita para generar los nombres completos de los ámbitos de acceso de **OAuth Scopes (Ámbitos de OAuth)** que el autorizador de `COGNITO_USER_POOLS` utiliza. ![\[Ámbitos y servidores de recursos de un grupo de usuarios de Amazon Cognito\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png) # 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). # Llamar a una API REST integrada con un grupo de usuarios de Amazon Cognito Para llamar a un método con un autorizador de grupo de usuarios configurado, el cliente debe hacer lo siguiente: + Permitir al usuario inscribirse en el grupo de usuarios. + Permitir al usuario iniciar sesión en el grupo de usuarios. + Obtenga un [token de identidad o acceso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) del usuario conectado del grupo de usuarios. + Incluya el token en el encabezado `Authorization` (u otro encabezado que haya especificado al crear el autorizador). Puede utilizar [AWS Amplify]() para realizar estas tareas. Consulte [Integrating Amazon Cognito With Web and Mobile Apps](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) para obtener más información. + Para Android, consulte [Getting Started with Amplify for Android](https://docs.amplify.aws/android/build-a-backend/auth/). + Para utilizar iOS, consulte [Getting started with Amplify for iOS](https://docs.amplify.aws/swift/build-a-backend/auth/). + Para utilizar JavaScript, consulte [Getting Started with Amplify for Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/). # Configuración de un autorizador de Amazon Cognito entre cuentas para una API REST mediante la consola de API Gateway Ahora también se puede utilizar un grupo de usuarios de Amazon Cognito perteneciente a otra cuenta de AWS como el autorizador de la API. El grupo de usuarios de Amazon Cognito puede utilizar estrategias de autenticación de token al portador como OAuth o SAML. Esto permite administrar y compartir fácilmente de forma centralizada un autorizador de grupo de usuarios de Amazon Cognito en distintas API de API Gateway. En esta sección, mostramos cómo configurar un grupo de usuarios de Amazon Cognito entre cuentas mediante la consola de Amazon API Gateway. En estas instrucciones, se presupone que usted ya dispone de una API de API Gateway en una cuenta de AWS y de un grupo de usuarios de Amazon Cognito en otra cuenta. ## Creación de un autorizador de Amazon Cognito entre cuentas para una API de REST Inicie sesión en la consola de Amazon API Gateway en la cuenta que tiene la API y, a continuación, haga lo siguiente: 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**, ingrese el ARN completo del grupo de usuarios que tiene en la segunda cuenta. **nota** En la consola de Amazon Cognito, puede encontrar el ARN de su grupo de usuarios en el campo **Pool ARN (ARN de grupo)** del panel **General Settings (Configuración general)**. 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**. # Cree un autorizador de Amazon Cognito para una API de REST con CloudFormation Puede utilizar CloudFormation para crear un grupo de usuarios de Amazon Cognito y un autorizador de Amazon Cognito. En la plantilla de CloudFormation de ejemplo se realiza lo siguiente: + Cree un grupo de usuarios de Amazon Cognito. El cliente primero registrar al usuario en el grupo de usuarios y obtener una [identidad o un token de acceso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Si utiliza tokens de acceso para autorizar las llamadas a los métodos de la API, asegúrese de configurar la integración de aplicaciones con el grupo de usuarios para establecer los ámbitos que desee en un determinado servidor de recursos. + Crea una API de API Gateway con un método `GET`. + Crea un autorizador de Amazon Cognito que utiliza el encabezado `Authorization` como origen del token. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: UserPool: Type: AWS::Cognito::UserPool Properties: AccountRecoverySetting: RecoveryMechanisms: - Name: verified_phone_number Priority: 1 - Name: verified_email Priority: 2 AdminCreateUserConfig: AllowAdminCreateUserOnly: true EmailVerificationMessage: The verification code to your new account is {####} EmailVerificationSubject: Verify your new account SmsVerificationMessage: The verification code to your new account is {####} VerificationMessageTemplate: DefaultEmailOption: CONFIRM_WITH_CODE EmailMessage: The verification code to your new account is {####} EmailSubject: Verify your new account SmsMessage: The verification code to your new account is {####} UpdateReplacePolicy: Retain DeletionPolicy: Retain CogAuthorizer: Type: AWS::ApiGateway::Authorizer Properties: Name: CognitoAuthorizer RestApiId: Ref: Api Type: COGNITO_USER_POOLS IdentitySource: method.request.header.Authorization ProviderARNs: - Fn::GetAtt: - UserPool - Arn Api: Type: AWS::ApiGateway::RestApi Properties: Name: MyCogAuthApi ApiDeployment: Type: AWS::ApiGateway::Deployment Properties: RestApiId: Ref: Api DependsOn: - CogAuthorizer - ApiGET ApiDeploymentStageprod: Type: AWS::ApiGateway::Stage Properties: RestApiId: Ref: Api DeploymentId: Ref: ApiDeployment StageName: prod ApiGET: Type: AWS::ApiGateway::Method Properties: HttpMethod: GET ResourceId: Fn::GetAtt: - Api - RootResourceId RestApiId: Ref: Api AuthorizationType: COGNITO_USER_POOLS AuthorizerId: Ref: CogAuthorizer Integration: IntegrationHttpMethod: GET Type: HTTP_PROXY Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets Outputs: ApiEndpoint: Value: Fn::Join: - "" - - https:// - Ref: Api - .execute-api. - Ref: AWS::Region - "." - Ref: AWS::URLSuffix - / - Ref: ApiDeploymentStageprod - / ```