View a markdown version of this page

Configura la autorización de entrada para tu puerta de enlace - Amazon Bedrock AgentCore
IAM-based autorización entranteAutorización de entrada basada en un token web JSON (JWT)Autorización de entrada descargada

Configura la autorización de entrada para tu puerta de enlace

Antes de crear la 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. Puede crear un JWT con cualquiera de los proveedores de identidad en Configuración y configuración del proveedor.

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

  • Tipos de autorización descargados: 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 interceptora. Esta categoría incluye solo la autenticación y la ausencia de autorización. Para obtener más información y orientación, consulta Autorización entrante descargada.

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 mediante Amazon Cognito durante la creación de la puerta de enlace. Si planea usar la configuración de autorización predeterminada, puede omitir este requisito previo.

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

IAM-based autorización entrante

IAM-based la autorización entrante le permite utilizar las credenciales de IAM de la persona que llama a la puerta de enlace para la autorización. Puede usar esta opción si desea crear una identidad de IAM mediante la cual se pueda autenticar a los usuarios que llaman a su puerta de enlace.

Para configurar IAM-based la autorización entrante

  1. Cree o utilice una identidad de IAM existente para las personas que llaman a su puerta de enlace.

  2. Cree 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 manera que el Resource campo se refiera 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

En el siguiente ejemplo, se muestra una política que se puede adjuntar a una identidad para que pueda invocar una puerta de enlace con ese identificador 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 de entrada basada en un token web JSON (JWT)

Un token web JSON (JWT) es un token seguro y compacto que se utiliza para la autorización. Puede 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

Si se utiliza una autorización entrante basada en los tokens JWT, se registrarán algunas reclamaciones del token JWT. CloudTrail La entrada incluye el asunto del token de identidad web proporcionado. Le recomendamos que evite utilizar cualquier información de identificación personal (PII) en este campo. Por ejemplo, podría utilizar en su lugar un GUID o un identificador por pares, como se sugiere en la especificación OIDC.

Puede usar la AgentCore CLI para configurar un JWT predeterminado o crear uno manualmente con un proveedor de identidades compatible. Para obtener más información sobre los distintos métodos de configuración de un JWT, seleccione uno de los siguientes temas:

Configure un JWT predeterminado

La AgentCore CLI le permite crear fácilmente una configuración de autorización predeterminada mediante Amazon Cognito que, a continuación, puede utilizar al crear una puerta de enlace. Cuando se ejecutaagentcore create, la CLI le pide que configure la autorización de entrada y puede configurar automáticamente un grupo de usuarios de Amazon Cognito para usted.

agentcore create

Una vez completado el comando, la AgentCore CLI proporciona la información de autenticación y autorización:

  • Utilizará la configuración del autorizador al crear la puerta de enlace.

  • Para la autorización entrante al invocar tu puerta de enlace, necesitarás obtener un token de acceso utilizando tu ID de cliente, tu secreto de cliente y el punto final del token. Para obtener más información sobre cómo obtener su token de acceso, consulte el ejemplo en Use an AgentCore gateway o The token issuer endpoint 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 CustomJWTAuthorizerConfigurational crear una puerta de enlace, si son aplicables a tu caso de uso:

  • 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 de 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 una declaración. aud

  • Á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 Ámbitos de OAuth.

  • Otros valores de notificación obligatorios: según el autorizador que utilices, es posible que tengas que especificar las reglas y los campos de notificación personalizados necesarios para que coincidan 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 utilizó Amazon Cognito, consulte El punto final del emisor del token en la Guía para desarrolladores de Amazon Cognito.

Publicidad sobre el alcance de 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 necesarios. Esto sigue el formato de desafío del token Bearer RFC 6750 y permite a los MCP-compliant clientes descubrir automáticamente los ámbitos necesarios para la adquisición del token.

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

  • 401 No autorizada: la solicitud no contiene ningún token o un token no es válido. El WWW-Authenticate encabezado incluye resource_metadata 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 por 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 compatibles.

Usa 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 para que pueda acceder customJWTAuthorizer AgentCore a sus puntos finales privados de detección, token y JWKS del OIDC sin exponerlos a la Internet pública.

Su director de IAM debe tener el iam:CreateServiceLinkedRole permiso para identity-network.bedrock-agentcore.amazonaws.com que AgentCore Identity pueda crear el rol AWSServiceRoleForBedrockAgentCoreIdentity vinculado al servicio en su nombre si aún no existe.

privateEndpointEsto se aplica al dominio de. discoveryUrl Si su proveedor de identidad usa dominios diferentes para otros puntos de enlace (por ejemplo, el token o el punto final de JWKS se resuelve 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 gestionado:

{
  "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 su token o los puntos de enlace de JWKS utilizan un dominio diferente al de la URL de detección, añada 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, configuraciones multicuenta y configuraciones avanzadas, consulte Conectarse a recursos privados de su VPC mediante VPC Lattice. Para obtener una guía completa que cubre los escenarios de IdP privados entrantes y salientes, consulte Conectarse a proveedores de identidad privados.

Autorización de entrada descargada

Con la autorización entrante descargada, la puerta de enlace 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 adjunto a la puerta de enlace, que evalúa las políticas de acceso.

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

AgentCore ofrece dos tipos descargados:

  • Solo autenticar (AUTHENTICATE_ONLY): la puerta de enlace 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 que llame autenticada se reenvía al destino.

  • 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 destino.

Con cualquiera de los dos tipos, usted decide 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 utiliza con frecuencia junto con OAuth.

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

  • Destino descendente: deje que el objetivo aplique la autorización a la solicitud que reciba. Esto resulta útil para la experimentación y la incorporación progresiva (por ejemplo, para 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 forma que pueda adoptar las capacidades de la puerta de enlace de forma gradual mientras el tiempo de ejecución sigue aplicando la autenticación en la que ya confía.

importante

Si eliges una de las dos opciones para eliminar la autorización entranteNONE, AgentCore Gateway no AUTHENTICATE_ONLY aplicará la autorización por sí sola. En este escenario, debe transferir la autorización a un componente independiente (un motor de políticas, una función Lambda interceptora o el objetivo descendente); de lo contrario, cualquier persona que llame podrá alcanzar su objetivo.

Authenticate-only autorización

Con la autorización únicamente autenticada (AUTHENTICATE_ONLY), la puerta de enlace 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 propia. Cualquier principal de IAM autenticado puede invocar la puerta de enlace independientemente de sus permisos, y la solicitud se reenvía al destino. La autorización se delega al servicio de destino descendente o a 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 debida autorización a nivel de política de destino o puerta de enlace, cualquier persona que llame autenticada podrá ponerse en contacto con sus servicios de backend.

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 desautenticarse.

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 indican a continuación. Si necesita una lógica de autenticación personalizada, considere la posibilidad de utilizar una función Lambda interceptora para gestionar la autenticación antes de que las solicitudes lleguen a sus objetivos.

Prácticas recomendadas de seguridad

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

  2. No utilice pasarelas sin autorización por conveniencia para realizar pruebas. Deben usarse para las puertas de enlace que desee hacer públicas, pero que haya implementado sus propias reglas de regulación y controles personalizados 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 destinos se configuran con sus propias configuraciones de autorización, es mejor añadir otra capa de seguridad a la puerta de enlace.

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

Al combinar un tipo de autorización de entrada descargada con un tipo de autorización de salida coincidente que reenvía la identidad de la persona que llama al entorno de ejecución, la incorporación a una puerta de enlace puede ser tan simple como configurar una anulación del punto final en el cliente actual, sin necesidad de realizar cambios de autenticación:

  • Tiempos de ejecución de IAM: combine AUTHENTICATE_ONLY la autorización entrante con las credenciales de IAM de la persona que llama () la autorización saliente. CALLER_IAM_CREDENTIALS La puerta de enlace autentica a la persona que llama SigV4 y, a continuación, firma la solicitud en el 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 siga aplicándose sin cambios. Para obtener más información, consulta 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 tiempo de ejecución valida el token exactamente como lo hace en la actualidad. (La transferencia del token reenvía un token portador, por lo que requiere un tipo de entrada: autorización de JWT-bearing entrada de JWT o. NONE No está disponible conAUTHENTICATE_ONLY, que lo es ni lleva consigo, un SigV4-based token portador). Para obtener más información, consulta la sección Transferencia de fichas.

    nota

    El método recomendado para la producción JWT_PASSTHROUGH no es el método recomendado para la producción. Si reenvías el token entrante sin cambios, tanto la puerta de enlace como el destino final aceptan el mismo token, por lo que debe tener un alcance más preciso; por ejemplo, la audiencia de cada token (aud) debe restringirse al recurso previsto. El patrón recomendado es el intercambio de fichas en nombre de (OBO), en el que la puerta de enlace intercambia el token de la persona que llama por un token nuevo con alcance de audiencia para el objetivo en lugar de reproducir el token de la persona que llama. Utilice la transferencia de fichas para experimentar, probar e incorporar con facilidad, y opte por 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 incorporarse sin interrupciones. En el caso de una puerta de enlace de producción, aplique la autorización en la puerta de enlace: configure la autorización de entrada de JWT o IAM, adjunte un motor de políticas o utilice una función Lambda interceptora. Para asegurarse de que las personas que llaman no puedan evitar la puerta de enlace una vez que la haya adoptado, consulte Reforzar el tráfico a través de la puerta de enlace.