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 CreateAuthorizer 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 una API de REST en Amazon API Gateway.

Para crear un autorizador `COGNITO_USER_POOLS` mediante la consola de API Gateway

Cree una nueva API o seleccione una existente en API Gateway.
En el panel de navegación principal, elija Autorizadores.
Elija Crear autorizador.
Si desea configurar el nuevo autorizador para que utilice un grupo de usuarios, realice lo siguiente:
1. En Nombre del autorizador, ingrese un nombre.
2. En Tipo de autorizador, seleccione Cognito.
3. 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}.
4. 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.
5. (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.
6. Elija Crear autorizador.
Después de crear el autorizador de COGNITO_USER_POOLS, si lo desea, puede realizar una prueba e invocarlo proporcionando un token de identidad aprovisionado desde el grupo de usuarios. Puede obtener este token de identidad llamando al SDK de identidad de Amazon Cognito para realizar el inicio de sesión del usuario. También puede usar la acción InitiateAuth. 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

Seleccione Recursos. Elija un nuevo método o elija un método existente. Si es necesario, cree un recurso.
En la pestaña Solicitud de método, en Configuración de solicitud de método, elija Editar.
En Autorizador, en el menú desplegable, seleccione los autorizadores del grupo de usuarios de Amazon Cognito que acaba de crear.
Para utilizar un token de identidad, haga lo siguiente:
1. Mantenga los ámbitos de autorización vacíos.
2. 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 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']"
    }
}
```
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, 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.
2. Seleccione Guardar.
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_USER_POOLS con un archivo de definición de OpenAPI

Cree (o exporte) un archivo de definición de OpenAPI para la API.

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:

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"
        }
      },
      ...
   }

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"
        }
      },
      ...
   }

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 Trabajar con extensiones de API Gateway para OpenAPI.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Creación de un grupo de usuarios de Amazon Cognito para una API REST

Llamar a una API de REST integrada con un grupo de usuarios