AWS bedrock-agentcore medium security documentation change
Summary
Added documentation for new Identity service-linked role (AWSServiceRoleForBedrockAgentCoreRuntimeIdentity) handling workload identity and OAuth credentials, updated permissions requirements, and expanded deletion procedures
Security assessment
The changes introduce security documentation for a new service-linked role managing sensitive authentication mechanisms (OAuth credentials, JWT tokens). The added policy shows concrete security controls for workload identity management and token exchange operations. The migration guidance indicates a security improvement over manual IAM policies.
Diff
diff --git a/bedrock-agentcore/latest/devguide/service-linked-roles.md b/bedrock-agentcore/latest/devguide/service-linked-roles.md index 54279fe6b..c337ffd2d 100644 --- a//bedrock-agentcore/latest/devguide/service-linked-roles.md +++ b//bedrock-agentcore/latest/devguide/service-linked-roles.md @@ -16,0 +17,9 @@ You can delete the roles only after first deleting their related resources. This +AgentCore uses the following service-linked roles: + + * `AWSServiceRoleForBedrockAgentCoreNetwork` \- Manages network interfaces in your VPC + + * `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity` \- Manages workload identity access tokens and OAuth credentials for agent runtimes + + + + @@ -18,0 +28,2 @@ You can delete the roles only after first deleting their related resources. This +### Network service-linked role + @@ -30 +41 @@ The role permissions policy allows AgentCore to complete the following actions o -You can view the complete policy at [BedrockAgentCoreNetworkServiceRolePolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreNetworkServiceRolePolicy.html). For more information about this policy, see [BedrockAgentCoreNetworkServiceRolePolicy](./security-iam-awsmanpol.html#security-iam-awsmanpol-BedrockAgentCoreNetworkServiceRolePolicy). +You can view the complete policy at [BedrockAgentCoreNetworkServiceRolePolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreNetworkServiceRolePolicy.html). @@ -112,0 +124,97 @@ You can view the complete policy at [BedrockAgentCoreNetworkServiceRolePolicy](h +### Identity service-linked role + +AgentCore uses the service-linked role named `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity` to allow AgentCore to manage workload identity access tokens and OAuth credentials on your behalf. + +The `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity` service-linked role trusts the following services to assume the role: + + * `runtime-identity.bedrock-agentcore.amazonaws.com` + + + + +The role permissions policy allows AgentCore to complete these actions on the specified resources. + +You can view the complete policy at [BedrockAgentCoreRuntimeIdentityServiceRolePolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreRuntimeIdentityServiceRolePolicy.html). + + + { + "Version": "2012-10-17", + "Statement": { + "Sid": "AllowWorkloadIdentityAccess", + "Effect": "Allow", + "Action": [ + "bedrock-agentcore:GetWorkloadAccessToken", + "bedrock-agentcore:GetWorkloadAccessTokenForJWT", + "bedrock-agentcore:GetWorkloadAccessTokenForUserId" + ], + "Resource": [ + "arn:aws:bedrock-agentcore:*:*:workload-identity-directory/default", + "arn:aws:bedrock-agentcore:*:*:workload-identity-directory/default/workload-identity/*" + ] + } + } + +For information about changes to this policy, see [AgentCore updates to AWS managed policies](./security-iam-awsmanpol.html#security-iam-awsmanpol-updates). + +###### Understanding the Identity Feature + +The service-linked role is used to support OAuth authentication and JWT bearer token features for AgentCore Runtime resources. This feature allows agent runtimes to securely manage workload identities and access external OAuth providers on behalf of users. + +###### Key Benefits of Identity Management + + * **Simplified Permission Management** : Eliminates the need to manually configure IAM policies for workload identity access + + * **Secure Token Management** : Provides secure access to workload access tokens for OAuth flows + + * **User Federation** : Enables three-legged OAuth flows for accessing external services like Google Drive, Microsoft Graph, etc. + + * **Automatic Provisioning** : Service-linked role is created automatically when needed + + + + +###### How Identity Management Works + +When you invoke an AgentCore Runtime with OAuth authentication or JWT bearer tokens: + + 1. You configure JWT authorizer settings (discovery URL, allowed clients, allowed audiences) during runtime creation + + 2. AgentCore creates the service-linked role automatically to manage workload identity permissions + + 3. The runtime uses the service-linked role to exchange JWT tokens for workload access tokens + + 4. Your agent code can use these tokens to access external OAuth providers and services + + 5. All token management is handled securely through the AgentCore Identity service + + + + +###### Migration from Legacy Approach + +For existing agents (created before October 13, 2025) + + + * Continue to use manual IAM policies attached to the agent execution role + + * No automatic migration - existing behavior is preserved + + + + +For new agents (created on or after October 13, 2025) + + + * Automatically use the service-linked role approach + + * No manual IAM policy configuration required + + * Simplified setup and management + + + + +The service-linked role ensures that AgentCore can only access workload identity resources that are explicitly associated with your agent runtimes, maintaining secure isolation and clear resource attribution. + +For implementation details, see [Authenticate and authorize with Inbound Auth and Outbound Auth](./runtime-oauth.html). + @@ -115 +223,7 @@ You can view the complete policy at [BedrockAgentCoreNetworkServiceRolePolicy](h -You don't need to manually create a service-linked role. When you create an AgentCore Runtime, Code Interpreter, or Browser resources with VPC configuration, AgentCore creates the service-linked role for you automatically. +You don't need to manually create service-linked roles. AgentCore creates them automatically when needed: + + * **Network service-linked role** : Created when you create an AgentCore Runtime, Code Interpreter, or Browser resources with VPC configuration + + * **Identity service-linked role** : Created when you create or update an AgentCore Runtime on or after **October 13, 2025** + + @@ -117 +231,2 @@ You don't need to manually create a service-linked role. When you create an Agen -If you delete this service-linked role and then need to create it again, you can use the same process to re-create the role in your account. When you create an AgentCore Runtime, Code Interpreter, or Browser resources with VPC configuration, AgentCore creates the service-linked role for you again. + +If you delete a service-linked role and then need to create it again, you can use the same process to re-create the role in your account. When you create the appropriate AgentCore resources, AgentCore creates the service-linked role for you again. @@ -121 +236,3 @@ If you delete this service-linked role and then need to create it again, you can -You must configure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or delete a service-linked role. The IAM entity needs to have the following permission: +You must configure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or delete a service-linked role. The IAM entity needs to have the following permissions: + +###### For the Network service-linked role @@ -135 +252,16 @@ You must configure permissions to allow an IAM entity (such as a user, group, or -This permission is already included in the AWS managed policy [BedrockAgentCoreFullAccess](./security-iam-awsmanpol.html#security-iam-awsmanpol-BedrockAgentCoreFullAccess). +###### For the Identity service-linked role + + + { + "Sid": "CreateBedrockAgentCoreRuntimeIdentityServiceLinkedRolePermissions", + "Effect": "Allow", + "Action": "iam:CreateServiceLinkedRole", + "Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity", + "Condition": { + "StringEquals": { + "iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com" + } + } + } + +These permissions are already included in the AWS managed policy [BedrockAgentCoreFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html). @@ -139 +271 @@ This permission is already included in the AWS managed policy [BedrockAgentCoreF -AgentCore does not allow you to edit the `AWSServiceRoleForBedrockAgentCoreNetwork` service-linked role. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see [Editing a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role). +AgentCore does not allow you to edit the `AWSServiceRoleForBedrockAgentCoreNetwork` or `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity` service-linked roles. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see [Editing a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role). @@ -143 +275,8 @@ AgentCore does not allow you to edit the `AWSServiceRoleForBedrockAgentCoreNetwo -If you no longer need to use a feature or service that requires a service-linked role, we recommend that you delete that role. That way you don't have an unused entity that is not actively monitored or maintained. However, you must delete all your AgentCore Runtime, Code Interpreter, and Browser resources with VPC configuration before you can delete the service-linked role. +If you no longer need to use a feature or service that requires a service-linked role, we recommend that you delete that role. That way you don't have an unused entity that is not actively monitored or maintained. However, you must delete all your AgentCore resources that use the service-linked role before you can delete the role: + + * **Network service-linked role** : Delete all AgentCore Runtime, Code Interpreter, and Browser resources with VPC configuration + + * **Identity service-linked role** : Delete all AgentCore Runtime resources + + + @@ -164 +303,9 @@ Before you can use IAM to delete a service-linked role, you must first confirm t -If you are unsure whether AgentCore is using the `AWSServiceRoleForBedrockAgentCoreNetwork` role, you can try to delete the role. If the service is using the role, then the deletion fails and you can view the Regions where the role is being used. If the role is being used, then you must wait for the session to end before you can delete the role. You cannot revoke the session for a service-linked role. +If you are unsure whether AgentCore is using a service-linked role, you can try to delete the role. If the service is using the role, then the deletion fails and you can view the Regions where the role is being used. If the role is being used, then you must wait for the session to end before you can delete the role. You cannot revoke the session for a service-linked role. + +If you want to remove a service-linked role, you must first delete the appropriate AgentCore resources: + + * `AWSServiceRoleForBedrockAgentCoreNetwork`: Delete all AgentCore Runtime, Code Interpreter, and Browser resources with VPC configuration + + * `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity`: Delete all AgentCore Runtime resources + + @@ -166 +312,0 @@ If you are unsure whether AgentCore is using the `AWSServiceRoleForBedrockAgentC -If you want to remove the `AWSServiceRoleForBedrockAgentCoreNetwork` role, you must first delete all your AgentCore Runtime, Code Interpreter, and Browser resources with VPC configuration. @@ -170 +316 @@ If you want to remove the `AWSServiceRoleForBedrockAgentCoreNetwork` role, you m -Use the IAM console, the AWS CLI, or the IAM API to delete the `AWSServiceRoleForBedrockAgentCoreNetwork` service-linked role. For more information, see [Deleting a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role). +Use the IAM console, the AWS CLI, or the IAM API to delete service-linked roles. For more information, see [Deleting a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role).