View a markdown version of this page

AgentCore Puerta de enlace y política en los permisos AgentCore de IAM - Amazon Bedrock AgentCore
Descripción general deFunción de ejecución de GatewayFunción de administración de recursos¿Cuándo se requieren las actualizaciones de roles?Resolución de problemasEjemplo: creación de ambos roles de IAMPrácticas recomendadas

AgentCore Puerta de enlace y política en los permisos AgentCore de IAM

Esta guía proporciona los permisos de IAM necesarios para usar Amazon Bedrock AgentCore Gateway with Policy in AgentCore para un control de autorización detallado mediante políticas de Cedar.

Descripción general de

Al integrar Amazon Bedrock AgentCore Gateway con Policy in AgentCore, se requieren dos funciones de IAM distintas:

  1. Función de ejecución de puerta de enlace: la función de IAM que Amazon Bedrock AgentCore Gateway asume en tiempo de ejecución para invocar los objetivos y evaluar las políticas de Cedar

  2. Función de administración de recursos: la función de IAM que utilizan los administradores para crear y administrar Amazon Bedrock AgentCore Gateway y sus políticas en los recursos AgentCore

Ambas funciones tienen diferentes propósitos y requieren permisos específicos. El rol de ejecución de Gateway necesita permisos para ejecutar las operaciones de Amazon Bedrock AgentCore Gateway, mientras que el rol de administración de recursos necesita permisos para configurar y administrar Amazon Bedrock AgentCore Gateway y la política de los recursos. AgentCore

Función de ejecución de Gateway

El servicio Amazon Bedrock Gateway asume la función de ejecución de AgentCore Gateway al procesar las solicitudes. Esta función requiere permisos para:

  • Evalúe las políticas de Cedar mediante la política en AgentCore

  • Invoque objetivos como funciones de Lambda y puntos finales de API Gateway

  • Escriba registros y trazas en y CloudWatch X-Ray

  • Secretos de acceso para las configuraciones de autenticación

importante

La función de ejecución debe incluir estos tres permisos para utilizar Amazon Bedrock AgentCore Gateway with Policy en AgentCore:. bedrock-agentcore:AuthorizeAction - Evalúa las políticas de Cedar para las decisiones de autorización. bedrock-agentcore:PartiallyAuthorizeActions - Enumera las herramientas que la persona que llama está autorizada a invocar. bedrock-agentcore:GetPolicyEngine - Recupera la configuración del motor de políticas Sin estos permisos, la puerta de enlace no puede realizar la autorización de políticas. Esto se manifiesta de dos maneras: si se conecta un motor de políticas a una puerta de enlace existente, se generará una InternalServerException, y todas las invocaciones a las herramientas se denegarán de forma predeterminada, incluso si se han configurado las políticas de permisos.

Política de confianza

El rol de ejecución de Gateway debe confiar en el director del bedrock-agentcore.amazonaws.com servicio.

importante

Sustituya los siguientes marcadores de posición: * us-east-1 por la AWS región * por el 123456789012 ID de la AWS cuenta

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBedrockAgentCoreAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}

Política de permisos

Esta política otorga a Amazon Bedrock AgentCore Gateway los permisos necesarios para evaluar las políticas de Cedar a través de Policy in AgentCore. Los permisos se dividen en dos declaraciones siguiendo los principios del mínimo privilegio.

importante

Sustituya estos marcadores de posición: * us-east-1 por la AWS región * 123456789012 por el ID de AWS cuenta * <gateway-id> por el ID de puerta de enlace (o utilice * para todas las puertas de enlace) * <policy-engine-id> por el ID del motor de políticas (o utilice * para todos los motores de políticas)

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
      ]
    }
  ]
}
nota

* Es posible que se requieran permisos adicionales según el tipo de integración de Amazon Bedrock AgentCore Gateway (por ejemplo, funciones de Lambda o puntos de enlace de API Gateway). Estos permisos no se incluyen aquí, ya que varían en función de la integración específica. * Para producción: sustituya los marcadores de posición por identificadores de recursos específicos (por ejemplo, policy-engine/my-policy-engine-id en lugar depolicy-engine/<policy-engine-id>) para seguir los principios de privilegios mínimos, o utilice caracteres comodín (*) para permitir el acceso a todos los recursos de ese tipo.

Función de administración de recursos

Los administradores utilizan el rol de administración de recursos para crear y administrar Amazon Bedrock AgentCore Gateway y la política en AgentCore los recursos. Esta función requiere permisos para:

  • Crear, actualizar y eliminar puertas de enlace y destinos de puertas de enlace

  • Cree, actualice y elimine políticas de Policy Engines y Cedar

  • Llame al Gateway durante la creación de la política (InvokeGateway) para que Policy in AgentCore pueda validar las acciones de una declaración de Cedar en función de las capacidades del Gateway objetivo

  • Transfiera la función de ejecución de Gateway a los recursos de Amazon Bedrock AgentCore Gateway durante la creación

  • Etiquete los recursos para su organización y administración

  • Lea la información sobre las funciones de IAM para validar las configuraciones de las funciones de ejecución

Esta función es independiente de la función de ejecución de Gateway y solo se necesita al configurar o modificar Amazon Bedrock AgentCore Gateway y la política en AgentCore las configuraciones.

Política de permisos

importante

Sustituya estos marcadores de posición: * por us-east-1 la AWS región * por el ID 123456789012 de la cuenta AWS 

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GatewayManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateGateway",
        "bedrock-agentcore:UpdateGateway",
        "bedrock-agentcore:GetGateway",
        "bedrock-agentcore:DeleteGateway",
        "bedrock-agentcore:ListGateways",
        "bedrock-agentcore:InvokeGateway",
        "bedrock-agentcore:CreateGatewayTarget",
        "bedrock-agentcore:UpdateGatewayTarget",
        "bedrock-agentcore:GetGatewayTarget",
        "bedrock-agentcore:DeleteGatewayTarget",
        "bedrock-agentcore:ListGatewayTargets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    },
    {
      "Sid": "PolicyEngineManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicyEngine",
        "bedrock-agentcore:UpdatePolicyEngine",
        "bedrock-agentcore:GetPolicyEngine",
        "bedrock-agentcore:DeletePolicyEngine",
        "bedrock-agentcore:ListPolicyEngines"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicy",
        "bedrock-agentcore:UpdatePolicy",
        "bedrock-agentcore:GetPolicy",
        "bedrock-agentcore:DeletePolicy",
        "bedrock-agentcore:ListPolicies"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy/*"
      ]
    },
    {
      "Sid": "PolicyGeneration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartPolicyGeneration",
        "bedrock-agentcore:GetPolicyGeneration",
        "bedrock-agentcore:ListPolicyGenerations",
        "bedrock-agentcore:ListPolicyGenerationAssets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy-generation/*"
      ]
    },
    {
      "Sid": "IAMPassRole",
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*BedrockAgentCore*"
      ],
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "bedrock-agentcore.amazonaws.com"
        }
      }
    },
    {
      "Sid": "IAMReadAccess",
      "Effect": "Allow",
      "Action": [
        "iam:GetRole",
        "iam:GetRolePolicy",
        "iam:ListAttachedRolePolicies",
        "iam:ListRolePolicies"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*"
      ]
    },
    {
      "Sid": "PolicyScopeManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:ManageResourceScopedPolicy",
        "bedrock-agentcore:ManageAdminPolicy"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}
importante

bedrock-agentcore:InvokeGatewayes necesario para crear o actualizar las políticas de Cedar, no solo para invocar el Gateway en tiempo de ejecución. CreatePolicyy UpdatePolicy valide las acciones de su declaración de Cedar contra Gateway, una operación autorizada InvokeGateway según el ARN de Gateway. Sin él, la política pasa a ser «CREATE_FAILEDconInsufficient permissions to call gateway with ID <gateway-id>».

importante

Las ManageAdminPolicy acciones ManageResourceScopedPolicy y las acciones son puertas que solo permiten permisos y controlan los tipos de políticas de Cedar que pueden crear los administradores: * ManageResourceScopedPolicy - Otorga permiso para crear políticas de Cedar que se dirijan a ARN de puerta de enlace específicos (por ejemplo, políticas a las que se aplica una puerta de enlacegateway/my-gateway-123) * ManageAdminPolicy - Otorga permiso para crear políticas de Cedar con caracteres comodín/*. Ambos permisos son necesarios para poder gestionar plenamente las políticas. No se trata de operaciones de API, sino de comprobaciones de autorización que determinan el alcance de las políticas de Cedar que se pueden crear a través de las API de administración de políticas.

nota

Si bien el campo Recurso se incluye por motivos de coherencia, estas acciones que solo permiten permisos limitan principalmente la capacidad a nivel de acción y no a nivel de recursos.

¿Cuándo se requieren las actualizaciones de roles?

Determine si la política de AgentCore permisos debe añadirse a la función de ejecución de Amazon Bedrock AgentCore Gateway en función de cómo se creó Amazon Bedrock AgentCore Gateway.

Escenario 1: Puerta de enlace creada con AgentCore CLI

Estado: Es necesaria una acción

La AgentCore CLI crea una función de ejecución de puerta de enlace con permisos específicos para la invocación de destino y la autenticación saliente, pero no incluye la política en los permisos. AgentCore Debe agregar manualmente los GetPolicyEngine permisos y los AuthorizeAction permisos documentados en esta guía a la función de ejecución de la puerta de enlace. PartiallyAuthorizeActions

Escenario 2: rol de ejecución personalizado

Estado: es necesaria una acción

Las funciones de IAM personalizadas requieren que la política de AgentCore permisos documentada en esta guía se añada manualmente. Siga las políticas de permisos de las secciones anteriores.

Escenario 3: Least-Privilege Configuración de producción

Estado: es necesaria una acción

En el caso de los entornos de producción, limite la política a AgentCore los permisos para los ARN de recursos específicos, en lugar de utilizar caracteres comodín. Sustituya policy-engine/* y gateway/* por el motor de políticas y los ID de puerta de enlace específicos en sus políticas de permisos.

Resolución de problemas

En esta sección se describen los problemas más comunes a la hora de configurar los permisos de IAM para Amazon Bedrock AgentCore Gateway con la política incluida. AgentCore

InternalServerException Durante la evaluación de la política

Síntoma: la puerta de enlace regresa InternalServerException - Policy evaluation failed al conectar un motor de políticas a una puerta de enlace existente y, de forma predeterminada, se deniegan todas las invocaciones a las herramientas, incluso con las políticas de permisos configuradas.

Causa principal: la función de ejecución de la puerta de enlace no incluye la política requerida en AgentCore los permisos. Sin estos permisos, la puerta de enlace no puede realizar la autorización de políticas.

Solución: asegúrese de que la función de ejecución de la puerta de enlace incluya estos tres permisos:

{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:PartiallyAuthorizeActions",
    "bedrock-agentcore:AuthorizeAction",
    "bedrock-agentcore:GetPolicyEngine"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:policy-engine/*",
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:gateway/*"
  ]
}
nota

Si conecta un motor de políticas a una puerta de enlace existente mediante la consola de Policy Engine, es posible que los permisos de IAM no se actualicen automáticamente. Debe añadir estos permisos manualmente a la Service-Linked función de la puerta de enlace.

«Permisos insuficientes para llamar a la puerta de enlace» está activada CreatePolicy

Síntoma: CreatePolicy devuelve unpolicyId, pero la política pasa a ser CREATE_FAILED con, Insufficient permissions to call gateway with ID <gateway-id> incluso cuando la función de ejecución de Gateway tiene AuthorizeActionPartiallyAuthorizeActions, yGetPolicyEngine.

Causa principal: la brecha está en la función de administración de recursos a la que se dirigeCreatePolicy, no en la función de ejecución de Gateway. La validación de políticas llama a la puerta de enlace (autorizada comobedrock-agentcore:InvokeGateway); el error nombra a la puerta de enlace, pero la solución está en la función de creación de políticas.

Solución: agregue bedrock-agentcore:InvokeGateway (con el alcance del ARN de la puerta de enlace) a la función de administración de recursos:

{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:InvokeGateway"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
  ]
}

Fallos silenciosos en el modo LOG_ONLY

Síntoma: el motor de políticas parece funcionar en el modo LOG_ONLY, pero falla silenciosamente sin los mensajes de error adecuados.

Causa principal: la falta de bedrock-agentcore:GetPolicyEngine permiso provoca errores silenciosos que solo aparecen al cambiar al modo FORCED.

Solución: inclúyalo siempre bedrock-agentcore:GetPolicyEngine en la función de ejecución de Gateway, incluso cuando se utilice el modo LOG_ONLY para las pruebas.

Error: no se encontró el motor de políticas

Síntoma: Amazon Bedrock AgentCore Gateway devuelve errores que indican que no puede encontrar el motor de políticas ni acceder a él.

Causa principal: la política del rol de ejecución de puerta de enlace utiliza patrones de ARN incorrectos o falta el recurso del motor de políticas.

Solución: asegúrese de que los ARN del motor de políticas y de la puerta de enlace estén incluidos en la matriz de recursos:

"Resource": [
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
]
nota

Ambos PartiallyAuthorizeActions requieren acceso AuthorizeAction tanto al motor de políticas como a los recursos de la puerta de enlace.

Consejos de depuración

  1. Habilitar CloudWatch registros: configure el registro detallado para Amazon Bedrock AgentCore Gateway a fin de capturar los detalles de la evaluación de las políticas

  2. Revise los X-Ray rastreos: compruebe los AWS X-Ray rastreos para identificar dónde fallan las comprobaciones de autorización

  3. Comience con el modo LOG_ONLY: utilice el modo LOG_ONLY inicialmente para probar las políticas de Cedar sin bloquear las solicitudes

  4. Verifique que los cuatro permisos: asegúrese AuthorizeAction de que AND estén todos PartiallyAuthorizeActions presentes GetPolicyEngine

  5. Cambie al modo FORCED: solo después de comprobar que todos los permisos funcionan en el modo LOG_ONLY, cambie al modo FORCED

Ejemplo: creación de ambos roles de IAM

En el siguiente ejemplo, se muestra cómo crear las dos funciones de IAM necesarias mediante la AWS CLI.

Paso 1: Crear el rol de ejecución de Gateway

# Create the trust policy file
cat > gateway-trust-policy.json <<EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}
EOF

# Create the IAM role
aws iam create-role \
  --role-name MyGatewayExecutionRole \
  --assume-role-policy-document file://gateway-trust-policy.json

Paso 2: Adjuntar permisos a la función de ejecución de la puerta de enlace

# Create the permission policy file
cat > gateway-permissions.json <<EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}
EOF

# Attach the policy to the role
aws iam put-role-policy \
  --role-name MyGatewayExecutionRole \
  --policy-name GatewayPolicyEnginePermissions \
  --policy-document file://gateway-permissions.json
nota

En este ejemplo, solo se muestra la política de AgentCore permisos. Se deben añadir permisos adicionales para los objetivos de Amazon Bedrock AgentCore Gateway (Lambda, API Gateway, etc.) en función de sus requisitos de integración específicos.

Paso 3: Próximos pasos

Tras configurar el rol de ejecución con la política requerida en AgentCore los permisos, proceda a crear y configurar los recursos de la política. Para obtener una guía detallada, consulte:

Prácticas recomendadas

  1. Utilice funciones distintas: mantenga funciones distintas para la ejecución y la administración de recursos de Amazon Bedrock AgentCore Gateway

  2. Aplique el mínimo de privilegios: comience con ARN de recursos específicos en lugar de utilizar caracteres comodín en la fase de producción

  3. Pruebe con el modo LOG_ONLY: pruebe siempre la integración del motor de políticas en el modo LOG_ONLY antes de aplicar las políticas

  4. Habilite la supervisión: configure los CloudWatch registros y el seguimiento para la resolución de problemas y la observabilidad X-Ray

  5. Políticas de control de versiones: almacene las políticas de Cedar en el control de versiones junto con el código de infraestructura

  6. Utilice etiquetas de recursos: aplique etiquetas para organizar y gestionar Amazon Bedrock AgentCore Gateway y sus políticas en AgentCore los recursos

  7. Auditorías de seguridad periódicas: revise periódicamente las políticas de IAM para asegurarse de que siguen los principios de privilegios mínimos