View a markdown version of this page

Configure la autorización de entrada para su puerta de enlace - Base amazónica AgentCore
IAM-based autorización entranteAutorización entrante basada en JSON Web Token (JWT)Autorización entrante transferida

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Configure la autorización de entrada para su puerta de enlace

Antes de crear su puerta de enlace, debe configurar la autorización de entrada. La autorización entrante valida a los usuarios que intentan acceder a los destinos a través de su puerta de enlace. AgentCore AgentCore admite los siguientes tipos de autorización entrante:

  • Token web JSON (JWT): un token seguro y compacto que se utiliza para la autorización. Tras crear el JWT, debe especificarlo como configuración de autorización al crear la puerta de enlace. Puedes crear un JWT con cualquiera de los proveedores de identidad en Provider Setup and Configuration.

  • Identidad de IAM: autoriza el intento de acceder a la puerta de enlace mediante las credenciales de la identidad de AWS IAM.

  • Tipos de autorización transferidos: la puerta de enlace no toma ninguna decisión de autorización propia y, en su lugar, transfiere la autorización a otro componente, como el objetivo descendente, un motor de políticas conectado a la puerta de enlace o una función Lambda de intercepción. Esta categoría incluye la autenticación exclusiva y la no autorización. Para obtener más información y orientación, consulta la sección Autorización entrante transferida.

nota

Si utiliza la consola de AWS administración o la AgentCore CLI para crear la puerta de enlace, puede crear una configuración de autorización de entrada predeterminada con Amazon Cognito durante la creación de la puerta de enlace. Si piensa utilizar la configuración de autorización predeterminada, puede omitir este requisito previo.

Si no tiene previsto utilizar la configuración de autorización predeterminada con Amazon Cognito, seleccione el tema que corresponda al tipo de autorización que va a utilizar para obtener información sobre cómo configurarla:

IAM-based autorización entrante

IAM-based la autorización entrante le permite usar las credenciales de IAM de la persona que llama a la puerta de enlace para la autorización. Puedes usar esta opción si quieres crear una identidad de IAM a través de la cual los usuarios que llamen a tu puerta de enlace puedan autenticarse.

Para configurar IAM-based la autorización entrante

  1. Crea o usa una identidad de IAM existente para las personas que llaman a la puerta de enlace.

  2. Crea una política de IAM basada en la identidad que contenga los siguientes permisos:

    • bedrock-agentcore:InvokeGateway— Tras crear la puerta de enlace, debe modificar esta política de forma que el Resource campo se limite a la puerta de enlace que haya creado, como práctica recomendada de seguridad.

  3. Adjunte la política a la identidad de la persona que llama a la puerta de enlace.

Política de ejemplo

El siguiente ejemplo muestra una política que puedes adjuntar a una identidad para que pueda invocar una puerta de enlace con el ID my-gateway-12345 

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowGatewayInvocation",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:InvokeGateway"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-12345"
      ]
    }
  ]
}

Recursos

Autorización entrante basada en JSON Web Token (JWT)

Un token web JSON (JWT) es un token seguro y compacto que se utiliza para la autorización. Puedes crear un JWT con un proveedor de identidad compatible. Tras crear un JWT, puede recuperarlo y especificarlo como configuración de autorización al crear la puerta de enlace.

importante

El uso de la autorización entrante basada en los tokens de JWT hará que se registren algunas solicitudes del token de JWT. CloudTrail La entrada incluye el asunto del token de identidad web proporcionado. Le recomendamos que evite el uso de cualquier información de identificación personal (PII) en este campo. Por ejemplo, puedes usar en su lugar un GUID o un identificador por pares, tal como se sugiere en la especificación del OIDC.

Puede usar la AgentCore CLI para configurar una puerta de enlace con un proveedor de identidad de JWT existente. Para obtener más información sobre los métodos de configuración de JWT, seleccione uno de los siguientes temas:

Configure un autorizador de JWT

Cree una aplicación y un cliente con un proveedor de identidades compatible. Para ver un ejemplo de Amazon Cognito, consulte Introducción a Amazon Cognito. Anote la URL de descubrimiento del OIDC y el ID de cliente.

Ejecute el siguiente comando en el directorio de un AgentCore proyecto:

agentcore add gateway \
  --name MyGateway \
  --protocol-type MCP \
  --authorizer-type CUSTOM_JWT \
  --discovery-url <OIDC_DISCOVERY_URL> \
  --allowed-clients <CLIENT_ID>

La AgentCore CLI consume la configuración de OIDC existente; no crea los recursos del proveedor de identidades. Para invocar la puerta de enlace, obtenga un token de acceso de su proveedor. Para Amazon Cognito, consulte el punto final del emisor del token en la guía para desarrolladores de Amazon Cognito.

Configure un JWT manualmente

Amazon Bedrock AgentCore admite los JWT de todos los proveedores de identidad. Puede ver algunos ejemplos en Configuración y configuración del proveedor.

Durante el proceso de creación del JWT, toma nota de los siguientes valores, que rellenarás CustomJWTAuthorizerConfiguration cuando crees una puerta de enlace, si son aplicables a tu caso práctico:

  • URL de descubrimiento: la URL desde la que se pueden recuperar las credenciales de inicio de sesión y el punto final del token.

  • ID de cliente: el identificador público de una aplicación cliente que solicita un token, validado en función de la client_id reclamación.

  • Secreto del cliente: la clave privada que autentica el acceso a la aplicación cliente para recuperar un token.

  • Público permitido: el identificador que valida a los destinatarios o consumidores previstos de un token mediante la aud reclamación.

  • Ámbitos permitidos: los ámbitos que definen las limitaciones del acceso de una aplicación a la cuenta de un usuario. Para obtener más información, consulta los ámbitos de OAuth.

  • Otros valores de notificación obligatorios: según el autorizador que utilices, es posible que tengas que especificar reglas y campos de notificación personalizados obligatorios para hacer coincidir el valor del campo de notificación con el valor del campo de notificación para la autenticación.

Necesitarás estos valores para hacer lo siguiente:

  • Cree la puerta de enlace especificando los valores en la configuración del autorizador.

  • Obtenga las credenciales de autorización para invocar la puerta de enlace. Para obtener información sobre cómo obtener sus credenciales, consulte la documentación de su proveedor de identidad. Por ejemplo, si usó Amazon Cognito, consulte El punto final del emisor del token en la guía para desarrolladores de Amazon Cognito.

Incluya la publicidad en los desafíos de autenticación

Cuando un cliente envía una solicitud a una JWT-authorized puerta de enlace sin un token de acceso válido, la puerta de enlace devuelve una respuesta de error con un WWW-Authenticate encabezado que anuncia los ámbitos de OAuth requeridos. Sigue el formato RFC 6750 Bearer token challenge y permite a los MCP-compliant clientes descubrir automáticamente los ámbitos necesarios para la adquisición de los tokens.

La pasarela devuelve las siguientes respuestas en función del error:

  • 401 No autorizado: la solicitud no tiene ningún token o es un token no válido. El WWW-Authenticate encabezado incluye resource_metadata los scope parámetros.

  • 403 Prohibido: el token es válido pero no contiene los alcances requeridos. El WWW-Authenticate encabezado incluye error="insufficient_scope"scope, y resource_metadata parámetros.

El scope valor contiene los ámbitos delimitados por espacios configurados como ámbitos permitidos en la puerta de enlace. CustomJWTAuthorizerConfiguration El resource_metadata valor apunta al documento de metadatos de recursos protegidos de OAuth de la puerta de enlace/.well-known/oauth-protected-resource, que los clientes pueden consultar para descubrir el servidor de autorización y los ámbitos admitidos.

Utilice un proveedor de identidad privado () VPC-hosted

AgentCore Gateway admite JWT-based la autorización entrante con proveedores de identidad alojados en su VPC. Puede configurar una privateEndpoint opción customJWTAuthorizer para poder acceder AgentCore a sus puntos finales privados de descubrimiento, token y JWKS de OIDC sin exponerlos a la Internet pública.

Su director de IAM debe tener el iam:CreateServiceLinkedRole permiso para elloidentity-network.bedrock-agentcore.amazonaws.com, de modo que AgentCore Identity pueda crear la función AWSServiceRoleForBedrockAgentCoreIdentity vinculada al servicio en su nombre si aún no existe.

privateEndpointEsto se aplica al dominio del. discoveryUrl Si su proveedor de identidad usa dominios diferentes para otros puntos finales (por ejemplo, el token o el punto final de JWKS se convierte en un dominio diferente al de la URL de descubrimiento), utilícelo privateEndpointOverrides para especificar una configuración de punto final privado independiente para cada dominio adicional.

En el siguiente ejemplo, se crea una puerta de enlace con un proveedor de identidad privado mediante Lattice administrado:

{
  "name": "my-private-idp-gateway",
  "protocolType": "MCP",
  "roleArn": "arn:aws:iam::123456789012:role/my-gateway-role",
  "authorizerType": "CUSTOM_JWT",
  "authorizerConfiguration": {
    "customJWTAuthorizer": {
      "allowedAudience": [
        "my-audience"
      ],
      "discoveryUrl": "https://my-idp.internal.example.com/.well-known/openid-configuration",
      "privateEndpoint": {
        "managedVpcResource": {
          "vpcIdentifier": "vpc-0abc123def456",
          "subnetIds": ["subnet-0abc123", "subnet-0def456"],
          "endpointIpAddressType": "IPV4",
          "securityGroupIds": ["sg-0abc123def"]
        }
      }
    }
  }
}

Si tu token o tus puntos finales de JWKS usan un dominio diferente al de la URL de descubrimiento, agrega una privateEndpointOverrides entrada para cada dominio adicional. Actualmente, solo privateEndpointOverrides es compatible con los recursos de Lattice autogestionados:

{
  ...
  "authorizerConfiguration": {
    "customJWTAuthorizer": {
      "allowedAudience": ["my-audience"],
      "discoveryUrl": "https://my-idp.internal.example.com/.well-known/openid-configuration",
      "privateEndpoint": {
        "selfManagedLatticeResource": {
          "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-abc123"
        }
      },
      "privateEndpointOverrides": [
        {
          "domain": "my-token-server.internal.example.com",
          "privateEndpoint": {
            "selfManagedLatticeResource": {
              "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-def456"
            }
          }
        }
      ]
    }
  }
}

Para obtener información sobre Lattice autogestionado, las configuraciones multicuenta y las configuraciones avanzadas, consulta Cómo conectarse a los recursos privados de tu VPC mediante VPC Lattice. Para obtener una guía completa sobre los escenarios de IdP privados entrantes y salientes, consulta Cómo conectarse a proveedores de identidad privados. Conéctese a proveedores de identidad privada

Autorización entrante transferida

Con la autorización entrante transferida, la pasarela no toma ninguna decisión de autorización por sí misma. En su lugar, transfiere la autorización a otro componente:

  • El servicio de destino descendente, que autoriza la solicitud que recibe.

  • Un motor de políticas conectado a la puerta de enlace, que evalúa las políticas de acceso.

  • Una función Lambda de intercepción, que ejecuta tu lógica personalizada de autenticación o autorización antes de que las solicitudes lleguen a tus objetivos.

AgentCore ofrece dos tipos de descarga:

  • Autenticar únicamente (AUTHENTICATE_ONLY): la pasarela verifica la firma SIGv4 de la persona que llama para autenticar a la persona que llama, pero no toma ninguna decisión de autorización. Las solicitudes deben estar firmadas, pero cualquier persona autenticada que llame se reenvía al destinatario.

  • Sin autorización (NONE): la puerta de enlace no realiza ninguna autenticación o autorización entrante. Las solicitudes se pueden desautenticar y cualquier persona que llame se reenvía al destinatario.

Con cualquiera de los dos tipos, tú decides dónde se aplica realmente la autorización:

  • Motor de políticas: conecte un motor de políticas a la puerta de enlace para evaluar las políticas de acceso de forma centralizada. Este es un patrón recomendado para las pasarelas de producción y se usa con frecuencia junto con OAuth.

  • Función Lambda de Interceptor: ejecuta tu propia lógica de autenticación o autorización antes de que las solicitudes lleguen a tus objetivos. Esto se recomienda para las pasarelas de producción cuando las opciones de autorización entrante integradas no cumplen con sus requisitos.

  • Objetivo descendente: deje que el objetivo exija la autorización en la solicitud que reciba. Esto es útil para la experimentación y la incorporación progresiva (por ejemplo, colocar una puerta de enlace delante de un entorno de ejecución existente sin cambiar la autenticación y la autorización del tiempo de ejecución), de modo que puedes adoptar las funciones de puerta de enlace de forma gradual mientras el tiempo de ejecución sigue imponiendo la autenticación en la que ya confía.

importante

Si eliminas la autorización entrante eligiendo una de las dos opcionesNONE, AgentCore Gateway no aplica AUTHENTICATE_ONLY la autorización por sí sola. En este caso, debe transferir la autorización a un componente independiente (un motor de políticas, una función de Lambda interceptora o el objetivo descendente); de lo contrario, cualquier persona que llame podrá llegar a su objetivo.

Authenticate-only autorización

Con la autorización (AUTHENTICATE_ONLY) únicamente para autenticar, la pasarela verifica la firma de la versión 4 (SIGv4) de la persona que llama para confirmar su identidad, pero no toma ninguna decisión de autorización por sí sola. Cualquier director de IAM autenticado puede invocar la puerta de enlace independientemente de sus permisos, y la solicitud se reenvía al destinatario. La autorización se delega en el servicio de destino descendente o en un motor de políticas conectado a la puerta de enlace.

importante

ConAUTHENTICATE_ONLY, la puerta de enlace no aplica ninguna política de autorización. Cualquier SigV4-signed solicitud válida se reenviará al destino. Asegúrese de que sus objetivos intermedios implementen su propia lógica de autorización o adjunte un motor de políticas a la puerta de enlace para controlar el acceso. Sin la autorización adecuada a nivel de la política de destino o puerta de enlace, cualquier persona que llame autenticada puede ponerse en contacto con sus servicios de back-end.

Sin autorización

Puede crear una puerta de enlace que esté configurada sin autorización medianteauthorizerType=NONE. La puerta de enlace no realizará ninguna autorización en la solicitud de puerta de enlace entrante y la solicitud puede no autenticarse.

importante

No utilice pasarelas sin autorización para las cargas de trabajo de producción a menos que haya implementado todas las prácticas recomendadas de seguridad que se enumeran a continuación. Si necesitas una lógica de autenticación personalizada, considera usar una función Lambda de interceptor para gestionar la autenticación antes de que las solicitudes lleguen a tus objetivos.

Mejores prácticas de seguridad

  1. Utilice la clave de bedrock-agentcore:GatewayAuthorizerType condición para allow/deny acceder de forma selectiva dentro de su organización y crear puertas de enlace con authorizerType=NONE

  2. No utilice las pasarelas sin autorización por conveniencia para realizar las pruebas. Deben usarse en las pasarelas que pretenda hacer públicas, pero que hayan implementado sus propias reglas de limitación y comprobaciones personalizadas para garantizar que su puerta de enlace pública pueda gestionar usuarios no autenticados

  3. No utilices pasarelas sin autorización con objetivos que puedan responder con información confidencial. Si bien los objetivos se configuran con sus propias configuraciones de autorización, es mejor agregar otra capa de seguridad en la puerta de enlace.

Incorpore un entorno de ejecución existente sin cambiar su autenticación

Cuando combinas un tipo de autorización entrante descargado con un tipo de autorización saliente coincidente que reenvía la identidad de la persona que llama al tiempo de ejecución, la incorporación a una puerta de enlace puede ser tan simple como configurar una anulación de punto final en tu cliente actual, sin necesidad de realizar cambios en la autenticación:

  • Tiempos de ejecución de IAM: combine AUTHENTICATE_ONLY la autorización entrante con la autorización saliente de las credenciales de IAM de la persona que llama (). CALLER_IAM_CREDENTIALS La puerta de enlace autentica a la persona que llama mediante SigV4 y, a continuación, firma la solicitud para enviarla al motor de ejecución con la misma identidad de la persona que llama, de modo que la autorización de IAM existente en el tiempo de ejecución sigue aplicándose sin cambios. Para obtener más información, consulte Credenciales de IAM de la persona que llama. Autorización de credenciales de IAM de la persona que llama

  • Tiempos de ejecución de OAuth: combina la autorización entrante sin autorización con la autorización saliente mediante token passthrough (). JWT_PASSTHROUGH La puerta de enlace reenvía el JWT entrante al motor de ejecución sin modificarlo, de modo que el motor de ejecución valida el token exactamente como lo hace en la actualidad. (La transferencia de tokens reenvía un token portador, por lo que requiere un tipo de JWT-bearing entrada: autorización entrante JWT o. NONE No está disponible conAUTHENTICATE_ONLY, es decir, ni lleva consigo ningún token de portador SigV4-based .) Para obtener más información, consulte Transferencia de tokens.

    nota

    Token passthrough (JWT_PASSTHROUGH) no es el enfoque recomendado para la producción. Si reenvías el token entrante sin cambios, tanto la puerta de enlace como el objetivo descendente aceptan el mismo token, por lo que se debe establecer un ámbito estricto; por ejemplo, la audiencia de cada token (aud) debe restringirse al recurso deseado. El patrón recomendado es el intercambio de tokens en nombre de (OBO), en el que la pasarela intercambia el token de la persona que llama por un token nuevo y dirigido al público objetivo en lugar de reproducir el token de la persona que llama. Usa el método de transferencia de tokens para experimentar, probar e incorporar fácilmente, y pasa a OBO para cargas de trabajo de producción a largo plazo.

aviso

Las configuraciones de reenvío de identidades de esta sección se basan únicamente en el tiempo de ejecución posterior para autorizar las solicitudes; la pasarela no añade ninguna autorización propia. Están pensadas para realizar pruebas, experimentar e incorporar sin interrupciones. En el caso de una pasarela de producción, exige la autorización en la puerta de enlace: configura la autorización entrante de JWT o IAM, conecta un motor de políticas o usa una función Lambda de interceptor. Para garantizar que las personas que llaman no puedan eludir la puerta de enlace una vez que la adoptes, consulta Cómo hacer cumplir el tráfico a través de la puerta de enlace.