AWS agent-toolkit documentation change
Summary
Complete restructuring of IAM integration documentation. Replaced detailed IAM feature support table with a simplified authorization flow explanation. Added documentation for new MCP condition context keys (aws:ViaAWSMCPService, aws:CalledViaAWSMCP), clarified temporary credential handling, and deprecated MCP-specific IAM actions.
Security assessment
The changes primarily document a new authorization model where MCP Server forwards requests to downstream services with added condition keys. This explains how to use IAM policies with new context keys for access control but contains no evidence of addressing a specific security vulnerability. The deprecation of old IAM actions improves security posture by removing unnecessary permissions.
Diff
diff --git a/agent-toolkit/latest/userguide/security_iam_service-with-iam.md b/agent-toolkit/latest/userguide/security_iam_service-with-iam.md index 0fefa380b..1d1e60d72 100644 --- a//agent-toolkit/latest/userguide/security_iam_service-with-iam.md +++ b//agent-toolkit/latest/userguide/security_iam_service-with-iam.md @@ -7 +7 @@ -Identity-based policiesResource-based policiesPolicy actionsPolicy resourcesPolicy condition keysACLsABACTemporary credentialsPrincipal permissionsService rolesService-linked roles +Authorization flowMCP condition context keysIdentity-based policiesTemporary credentialsDeprecated actions @@ -11 +11 @@ Identity-based policiesResource-based policiesPolicy actionsPolicy resourcesPoli -Before you use IAM to manage access to Agent Toolkit for AWS, learn what IAM features are available to use with Agent Toolkit for AWS. +AWS MCP Server uses a simplified authorization model that works like the AWS Command Line Interface (AWS CLI) and AWS SDKs. The server does not define its own IAM actions, resources, or service-specific condition keys. Instead, it authenticates your request using [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html), adds standardized condition context keys, and forwards the request to the downstream AWS service. The downstream service performs the authorization check using your existing IAM policies. This means your AI agents work with your existing AWS credentials and service-level permissions, and you do not need to configure separate MCP-specific IAM actions. @@ -13,13 +13 @@ Before you use IAM to manage access to Agent Toolkit for AWS, learn what IAM fea -IAM feature | AWS MCP Server support ----|--- -Identity-based policies | Yes -Resource-based policies | No -Policy actions | Yes -Policy resources | Yes -Policy condition keys | Yes -ACLs | No -ABAC (tags in policies) | Partial -Temporary credentials | Yes -Principal permissions | Yes -Service roles | Yes -Service-linked roles | No +## Authorization flow @@ -27 +15 @@ Service-linked roles | No -To get a high-level view of how AWS MCP Server and other AWS services work with most IAM features, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the _IAM User Guide_. +When an AI agent calls the AWS MCP Server, the following authorization flow occurs: @@ -29 +17 @@ To get a high-level view of how AWS MCP Server and other AWS services work with -## Identity-based policies for AWS MCP Server + 1. Your agent's request is authenticated with your AWS credentials using [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). The [MCP Proxy for AWS](https://github.com/aws/mcp-proxy-for-aws) handles this signing automatically between your host application and the server. @@ -31,27 +19 @@ To get a high-level view of how AWS MCP Server and other AWS services work with -**Supports identity-based policies:** Yes - -Identity-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role. These policies control what actions users and roles can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the _IAM User Guide_. - -With IAM identity-based policies, you can specify allowed or denied actions and resources as well as the conditions under which actions are allowed or denied. To learn about all of the elements that you can use in a JSON policy, see [IAM JSON policy elements reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the _IAM User Guide_. - -### Identity-based policy examples for AWS MCP Server - -To view examples of Agent Toolkit for AWS identity-based policies, see [Identity-based policy examples for AWS MCP Server](./security_iam_id-based-policy-examples.html). - -## Resource-based policies within AWS MCP Server - -**Supports resource-based policies:** No - -Resource-based policies are JSON policy documents that you attach to a resource. Examples of resource-based policies are IAM _role trust policies_ and Amazon S3 _bucket policies_. In services that support resource-based policies, service administrators can use them to control access to a specific resource. For the resource where the policy is attached, the policy defines what actions a specified principal can perform on that resource and under what conditions. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource-based policy. Principals can include accounts, users, roles, federated users, or AWS services. - -To enable cross-account access, you can specify an entire account or IAM entities in another account as the principal in a resource-based policy. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the _IAM User Guide_. - -## Policy actions for AWS MCP Server - -**Supports policy actions:** Yes - -Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources** , and under what **conditions**. - -The `Action` element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Include actions in a policy to grant permissions to perform the associated operation. - -To see a list of AWS MCP Server actions, see [Actions Defined by Agent Toolkit for AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_your_service.html#your_service-actions-as-permissions) in the _Service Authorization Reference_. + 2. AWS MCP Server authenticates the request and adds the MCP condition context keys (`aws:ViaAWSMCPService` and `aws:CalledViaAWSMCP`). @@ -59 +21 @@ To see a list of AWS MCP Server actions, see [Actions Defined by Agent Toolkit f -Policy actions in AWS MCP Server use the following prefix before the action: + 3. AWS MCP Server forwards the request to the target AWS service. @@ -60,0 +23 @@ Policy actions in AWS MCP Server use the following prefix before the action: + 4. The target AWS service authorizes the request using your existing IAM policies, which can reference the MCP condition context keys for fine-grained control. @@ -62 +24,0 @@ Policy actions in AWS MCP Server use the following prefix before the action: -To specify multiple actions in a single statement, separate them with commas. @@ -65,4 +26,0 @@ To specify multiple actions in a single statement, separate them with commas. - "Action": [ - ":action1", - ":action2" - ] @@ -70 +28 @@ To specify multiple actions in a single statement, separate them with commas. -To view examples of Agent Toolkit for AWS identity-based policies, see [Identity-based policy examples for AWS MCP Server](./security_iam_id-based-policy-examples.html). +## MCP condition context keys @@ -72 +30 @@ To view examples of Agent Toolkit for AWS identity-based policies, see [Identity -## Policy resources for AWS MCP Server +AWS MCP Server automatically adds the following global condition context keys to all requests it forwards to downstream AWS services. You can use these keys in IAM policies and service control policies (SCPs) to differentiate between requests made through an AWS managed MCP server and direct API calls. @@ -74 +32 @@ To view examples of Agent Toolkit for AWS identity-based policies, see [Identity -**Supports policy resources:** Yes +`aws:ViaAWSMCPService` @@ -76 +33,0 @@ To view examples of Agent Toolkit for AWS identity-based policies, see [Identity -Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources** , and under what **conditions**. @@ -78 +35 @@ Administrators can use AWS JSON policies to specify who has access to what. That -The `Resource` JSON policy element specifies the object or objects to which the action applies. As a best practice, specify a resource using its [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). For actions that don't support resource-level permissions, use a wildcard (*) to indicate that the statement applies to all resources. +A Boolean key set to `true` for any request that passes through an AWS managed MCP server. Use this key to allow or deny all actions initiated through any AWS managed MCP server. @@ -79,0 +37 @@ The `Resource` JSON policy element specifies the object or objects to which the +Type: Boolean @@ -81 +39 @@ The `Resource` JSON policy element specifies the object or objects to which the - "Resource": "*" +`aws:CalledViaAWSMCP` @@ -83 +40,0 @@ The `Resource` JSON policy element specifies the object or objects to which the -To see a list of AWS MCP Server resource types and their ARNs, see [Resources Defined by Agent Toolkit for AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_your_service.html#your_service-resources-for-iam-policies) in the _Service Authorization Reference_. To learn with which actions you can specify the ARN of each resource, see [Actions Defined by Agent Toolkit for AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_your_service.html#your_service-actions-as-permissions). @@ -85 +42 @@ To see a list of AWS MCP Server resource types and their ARNs, see [Resources De -To view examples of Agent Toolkit for AWS identity-based policies, see [Identity-based policy examples for AWS MCP Server](./security_iam_id-based-policy-examples.html). +A single-valued string key containing the service principal of the specific AWS managed MCP server that initiated the request. Use this key to apply controls for a specific MCP server. @@ -87 +44 @@ To view examples of Agent Toolkit for AWS identity-based policies, see [Identity -## Policy condition keys for AWS MCP Server +Type: String @@ -89 +46 @@ To view examples of Agent Toolkit for AWS identity-based policies, see [Identity -**Supports service-specific policy condition keys:** Yes +Example values: @@ -91 +48 @@ To view examples of Agent Toolkit for AWS identity-based policies, see [Identity -Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources** , and under what **conditions**. + * `aws-mcp.amazonaws.com` – AWS MCP Server @@ -93 +50 @@ Administrators can use AWS JSON policies to specify who has access to what. That -The `Condition` element specifies when statements execute based on defined criteria. You can create conditional expressions that use [condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html), such as equals or less than, to match the condition in the policy with values in the request. To see all AWS global condition keys, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the _IAM User Guide_. + * `eks-mcp.amazonaws.com` – Amazon EKS MCP Server @@ -95 +52 @@ The `Condition` element specifies when statements execute based on defined crite -To see a list of AWS MCP Server condition keys, see [Condition Keys for Agent Toolkit for AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_your_service.html#your_service-policy-keys) in the _Service Authorization Reference_. To learn with which actions and resources you can use a condition key, see [Actions Defined by Agent Toolkit for AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_your_service.html#your_service-actions-as-permissions). + * `ecs-mcp.amazonaws.com` – Amazon ECS MCP Server @@ -97 +53,0 @@ To see a list of AWS MCP Server condition keys, see [Condition Keys for Agent To -In addition to service-specific condition keys, the following global condition context keys are automatically added to all requests made through AWS MCP Server: @@ -99 +54,0 @@ In addition to service-specific condition keys, the following global condition c - * `aws:ViaAWSMCPService` – A Boolean key set to `true` for any request that passes through an AWS managed MCP server. Use this key to allow or deny all actions initiated through any AWS managed MCP server. @@ -101 +55,0 @@ In addition to service-specific condition keys, the following global condition c - * `aws:CalledViaAWSMCP` – A string key containing the service principal of the specific AWS managed MCP server that initiated the request (for example, `aws-mcp.amazonaws.com`). Use this key to apply controls for a specific MCP server. @@ -102,0 +57 @@ In addition to service-specific condition keys, the following global condition c +For more information about global condition context keys, see [IAM condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the _IAM User Guide_. @@ -103,0 +59 @@ In addition to service-specific condition keys, the following global condition c +## Identity-based policies @@ -104,0 +61 @@ In addition to service-specific condition keys, the following global condition c +**Supports identity-based policies:** Yes @@ -106,19 +63 @@ In addition to service-specific condition keys, the following global condition c -For more information about these global condition keys, see [IAM condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the _IAM User Guide_. For examples of how to use these keys in IAM policies, see [Step 4: Understand IAM authorization](./getting-started-aws-mcp-server.html#step-4-configure-iam). - -To view examples of Agent Toolkit for AWS identity-based policies, see [Identity-based policy examples for AWS MCP Server](./security_iam_id-based-policy-examples.html). - -## ACLs in AWS MCP Server - -**Supports ACLs:** No - -Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format. - -## ABAC with AWS MCP Server - -**Supports ABAC (tags in policies):** Partial - -Attribute-based access control (ABAC) is an authorization strategy that defines permissions based on attributes called tags. You can attach tags to IAM entities and AWS resources, then design ABAC policies to allow operations when the principal's tag matches the tag on the resource. - -To control access based on tags, you provide tag information in the [condition element](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) of a policy using the `aws:ResourceTag/`key-name``, `aws:RequestTag/`key-name``, or `aws:TagKeys` condition keys. - -If a service supports all three condition keys for every resource type, then the value is **Yes** for the service. If a service supports all three condition keys for only some resource types, then the value is **Partial**. +Because AWS MCP Server forwards requests to downstream AWS services using your credentials, the IAM policies attached to your IAM user or role determine what actions the MCP server can perform on your behalf. No additional IAM configuration is required to use AWS MCP Server beyond the permissions you already grant for direct API access. @@ -126 +65 @@ If a service supports all three condition keys for every resource type, then the -For more information about ABAC, see [Define permissions with ABAC authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html) in the _IAM User Guide_. To view a tutorial with steps for setting up ABAC, see [Use attribute-based access control (ABAC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html) in the _IAM User Guide_. +You can use the MCP condition context keys in your existing policies to apply different permissions when actions are initiated through an MCP server. For examples, see [Identity-based policy examples for AWS MCP Server](./security_iam_id-based-policy-examples.html). @@ -132,7 +71 @@ For more information about ABAC, see [Define permissions with ABAC authorization -Temporary credentials provide short-term access to AWS resources and are automatically created when you use federation or switch roles. AWS recommends that you dynamically generate temporary credentials instead of using long-term access keys. For more information, see [Temporary security credentials in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) and [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the _IAM User Guide_. - -## Cross-service principal permissions for AWS MCP Server - -**Supports forward access sessions (FAS):** Yes - -Forward access sessions (FAS) use the permissions of the principal calling an AWS service, combined with the requesting AWS service to make requests to downstream services. For policy details when making FAS requests, see [Forward access sessions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html). +AWS MCP Server works with temporary credentials obtained through AWS STS. When you authenticate with AWS MCP Server, you can use temporary credentials from IAM roles, federated identities, or assumed roles. The server forwards these credentials to downstream AWS services, which honor the same session policies and permission boundaries as direct API calls. @@ -140 +73 @@ Forward access sessions (FAS) use the permissions of the principal calling an AW -## Service roles for AWS MCP Server +## Deprecated MCP-specific IAM actions @@ -142 +75 @@ Forward access sessions (FAS) use the permissions of the principal calling an AW -**Supports service roles:** Yes +During the preview period, AWS MCP Server required the following service-specific IAM actions: @@ -144 +77 @@ Forward access sessions (FAS) use the permissions of the principal calling an AW -A service role is an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that a service assumes to perform actions on your behalf. An IAM administrator can create, modify, and delete a service role from within IAM. For more information, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the _IAM User Guide_. + * `aws-mcp:InvokeMcp` @@ -146 +79 @@ A service role is an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide -###### Warning + * `aws-mcp:CallReadOnlyTool` @@ -148 +81 @@ A service role is an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide -Changing the permissions for a service role might break AWS MCP Server functionality. Edit service roles only when AWS MCP Server provides guidance to do so. + * `aws-mcp:CallReadWriteTool` @@ -150 +82,0 @@ Changing the permissions for a service role might break AWS MCP Server functiona -## Service-linked roles for AWS MCP Server @@ -152 +83,0 @@ Changing the permissions for a service role might break AWS MCP Server functiona -**Supports service-linked roles:** No @@ -154 +84,0 @@ Changing the permissions for a service role might break AWS MCP Server functiona -A service-linked role is a type of service role that is linked to an AWS service. The service can assume the role to perform an action on your behalf. Service-linked roles appear in your AWS account and are owned by the service. An IAM administrator can view, but not edit the permissions for service-linked roles. @@ -156 +86 @@ A service-linked role is a type of service role that is linked to an AWS service -For details about creating or managing service-linked roles, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html). Find a service in the table that includes a `Yes` in the **Service-linked role** column. Choose the **Yes** link to view the service-linked role documentation for that service. +These actions are no longer required and have no effect. If you previously configured IAM permissions using these actions, we recommend that you remove them from your policies. If you used these actions in Deny statements to block access to AWS MCP Server, you must update your policies to use the `aws:ViaAWSMCPService` or `aws:CalledViaAWSMCP` condition context keys instead.