Integración de una API REST con un grupo de usuarios de Amazon Cognito

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.

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.

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 Extensiones de OpenAPI para API Gateway.