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.

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

En esta guía se proporcionan los permisos de IAM necesarios para utilizar Amazon Bedrock AgentCore Gateway con la política de inicio de un control detallado de las AgentCore autorizaciones mediante las 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:

Ambas funciones tienen diferentes finalidades y requieren permisos específicos. La función de ejecución de Gateway necesita permisos para ejecutar las operaciones de Amazon Bedrock AgentCore Gateway, mientras que la función de administración de recursos necesita permisos para configurar y administrar Amazon Bedrock AgentCore Gateway y la política de recursos. AgentCore

Función de ejecución de Gateway

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

Política de confianza

La función de ejecución de Gateway debe confiar en el principal del bedrock-agentcore.amazonaws.com servicio.

{
"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 la política en. AgentCore Los permisos se dividen en dos declaraciones siguiendo los principios de mínimo privilegio.

{
"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>"
      ]
    }
  ]
}

Permisos de IAM para políticas temporales

Las políticas temporales requieren que la puerta de enlace propague la identidad de la sesión de la persona que llama a toda la solicitud mediante la creación de un token de acceso a la carga de trabajo (WAT). En el flujo entrante AWS de IAM, esta moneda llama. GetWorkloadAccessToken Otorgue la función de ejecución de Gatewaybedrock-agentcore:GetWorkloadAccessToken, con el alcance del directorio de identidades y cargas de trabajo de Gateway. Agregue este permiso además de los tres permisos de política (AuthorizeAction,PartiallyAuthorizeActions,GetPolicyEngine) ya documentados en esta página. Este permiso solo es necesario cuando la política temporal está activa (se proporciona un identificador de sesión de política y se adjunta un motor de políticas); no es necesario cuando la política temporal está deshabilitada.

Agregue la siguiente declaración a la política de permisos del rol de ejecución de Gateway:

{
  "Sid": "PolicySessionWorkloadIdentity",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetWorkloadAccessToken"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/<gatewayId>*"
  ]
}

Sin este permiso, las invocaciones de las herramientas fallan en el paso inicial una vez que se AccessDenied habilita la GetWorkloadAccessToken política temporal. Para la producción, sustitúyalo por <gatewayId> el ID de Gateway específico para seguir los principios de privilegios mínimos.

Para obtener una descripción general de este requisito en el contexto de las consideraciones de política temporal, consulta los permisos de IAM obligatorios.

Función de administración de recursos

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

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

Política de permisos

{
"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/*"
      ]
    }
  ]
}

¿Cuándo es necesario actualizar los roles?

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

Resolución de problemas

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

InternalServerException Durante la evaluación de la política

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

Causa principal: al rol de ejecución de Gateway le falta la política requerida en AgentCore cuanto a 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/*"
  ]
}

La opción «Permisos insuficientes para llamar a Gateway» 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 la pasarela tiene AuthorizeActionPartiallyAuthorizeActions, yGetPolicyEngine.

Causa principal: la brecha está en la función de administración de recursos que llamaCreatePolicy, no en la función de ejecución de la puerta de enlace. La validación de políticas llama a la puerta de enlace (autorizada comobedrock-agentcore:InvokeGateway); el error asigna un nombre 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 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 la puerta de enlace, incluso cuando utilice el modo LOG_ONLY para realizar pruebas.

Error de motor de políticas no encontrado

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 Gateway usa 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>"
]

Consejos de depuración

Ejemplo: crear ambos roles de IAM

El siguiente ejemplo 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 los permisos al rol de ejecución de Gateway

# 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

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