If you’re working with AWS and encountering errors related to policies in AgentCore, it can be confusing to determine what exactly is causing the problem. The official AWS documentation explains that error messages mentioning a resource or permission might not point directly to the real issue. For example, if you see an error about “GetPolicyEngine,” it doesn’t necessarily mean that this specific component is what was denied access.
One common mistake is assuming that the error message points to the resource that’s missing permission. In reality, the problem often involves the need for access to multiple resources. Particularly, both “AuthorizeAction” and “PartiallyAuthorizeActions” require permissions for two different ARNs: the policy engine and the gateway. These permissions are documented as needing access to both ARNs in the resource list. If either is missing, authorization will fail.
This becomes tricky during the creation process of a gateway because the ARN for the gateway doesn’t exist yet at the time the permissions are checked. So, scoping permissions to a specific ARN that isn’t created yet won’t work. Instead, you should use wildcards like “gateway/” to cover all potential gateway ARNs or pre-compute the ARN if possible. However, in most cases, especially when deploying using CloudFormation where the gateway ID is generated by the service, using “gateway/” is the practical approach. The same applies to the policy engine ARN as well.
Interestingly, this scenario explains why your test from the CloudFormation execution role might succeed even though the exact ARN permissions aren’t in place. CloudFormation roles often have broader prefix-scoped privileges, allowing access to all ARNs starting with a specific prefix, unlike scopes limited to an exact ARN.
Another key point is understanding why your IAM simulation tools might give you a false sense of security. Simulating policies on “bedrock-agentcore:GetPolicyEngine” alone may seem allowed, but this doesn’t cover the broader permissions needed for “AuthorizeAction” and “PartiallyAuthorizeActions.” For a more accurate assessment, run simulations that include those actions with the gateway ARN in the resource field. Typically, these will result in an “implicitDeny,” confirming the permission gap.
It’s also important to know that the simulation tools evaluate policies, boundaries, and Service Control Policies (SCPs), but do NOT evaluate grants from KMS or context values injected at runtime. This means a grant-related failure on KMS might still show as “allowed” during simulation, even though the real call could fail.
A significant finding is that policy in AgentCore uses KMS grants created via FAS (Forward Access Session), not just the role’s identity policy. When you create a policy engine with a customer-managed KMS key, the system automatically creates grants to access that key. These grants are authorized by the account principal (not a service principal) through a “CreateGrant” call made with your credentials during FAS. These grants allow cryptographic activities without additional permission checks, meaning your Gateway’s role permissions don’t directly control decryption operations once the grants are in place.
You can verify if these grants exist by listing them with the AWS CLI. For each policy engine, two grants should be present: one for managing policies and another for evaluation, each constrained by an encryption context that includes the policy engine ARN. If the grants are missing or only one exists, it indicates an issue with grant creation, which could cause permission errors.
It’s also wise to confirm that your role and permission boundaries allow both “kms:CreateGrant” and other necessary actions on your KMS keys. If permissions are missing on boundaries, grant creation may silently fail, leaving your setup incomplete.
When troubleshooting, start by simulating the missing permissions—specifically, running “AuthorizeAction” and “PartiallyAuthorizeActions” with the gateway ARN as the resource. Expect that these simulations will show “implicitDeny” if permissions are missing. If they do, you can then proceed to add the required actions to your Gateway roles, scope them appropriately, and ensure your permission boundaries permit these actions. Afterward, check the KMS grants to confirm they’re correctly created.
If problems persist, the next step is to contact AWS Support. Provide them with request IDs, the ARN of the assumed role, and the DryRun logs. They can investigate details like the actual “kms:ViaService” value used during internal validation and whether grants or role assumptions are affecting decryption permissions.
In summary, to resolve these issues:
- Simulate the “AuthorizeAction” and “PartiallyAuthorizeActions” with your gateway resource ARNs.
- Ensure your Gateway roles have permissions for both actions, scoped to wildcard ARNs if the resource isn’t yet created.
- Confirm your permission boundaries allow “kms:CreateGrant” and related KMS operations.
- List your KMS grants to verify they exist and are constrained correctly.
- If errors persist, work with AWS Support with detailed logs and requests.
By following this systematic approach, you’ll have a clearer understanding of where permission gaps exist and how to fix them. Remember, permissions involving grants and session policies can be tricky, but careful checking and targeted permissions adjustments usually resolve these issues.