Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

The confused deputy problem

The confused deputy problem is a security issue where an entity that doesn't have permission to perform an action can coerce a more-privileged entity to perform the action. To prevent this, Amazon provides tools that help you protect your account if you provide third parties (known as cross-account) or other Amazon services (known as cross-service) access to resources in your account.

At times, you might need to give a third party access to your Amazon resources (delegate access). For example, let's say that you decide to hire a third-party company called Example Corp to monitor your Amazon Web Services account and help optimize costs. In order to track your daily spending, Example Corp needs to access your Amazon resources. Example Corp also monitors many other Amazon Web Services accounts for other customers. You can use an IAM role to establish a trusted relationship between your Amazon Web Services account and the Example Corp account. One important aspect of this scenario is the external ID, optional information that you can use in an IAM role trust policy to designate who can assume the role. The primary function of the external ID is to address and prevent the confused deputy problem.

In Amazon, cross-service impersonation can result in the confused deputy problem. Cross-service impersonation can occur when one service (the calling service) calls another service (the called service). The calling service can be manipulated to use its permissions to act on another customer's resources in a way it should not otherwise have permission to access.

Cross-account confused deputy prevention

The following diagram illustrates the cross-account confused deputy problem.

This scenario assumes the following:

Here's what happens:

This is how the other customer could gain unauthorized access to your resources. Because this other customer was able to trick Example Corp into unwittingly acting on your resources, Example Corp is now a "confused deputy."

Example Corp can address the confused deputy problem by requiring that you include the ExternalId condition check in the role's trust policy. Example Corp generates a unique ExternalId value for each customer and uses that value in its request to assume the role. The ExternalId value must be unique among Example Corp's customers and controlled by Example Corp, not its customers. This is why you get it from Example Corp and you don't come up with it on your own. This prevents Example Corp from being a confused deputy and granting access to another account's Amazon resources.

In our scenario, imagine Example Corp's unique identifier for you is 12345, and its identifier for the other customer is 67890. These identifiers are simplified for this scenario. Generally, these identifiers are GUIDs. Assuming that these identifiers are unique among Example Corp's customers, they are sensible values to use for the external ID.

Example Corp gives the external ID value of 12345 to you. You must then add a Condition element to the role's trust policy that requires the sts:ExternalId value to be 12345, like this:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Principal": {
      "AWS": "Example Corp's Amazon Account ID"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
        "sts:ExternalId": "12345"
      }
    }
  }
}

The Condition element in this policy allows Example Corp to assume the role only when the AssumeRole API call includes the external ID value of 12345. Example Corp makes sure that whenever it assumes a role on behalf of a customer, it always includes that customer's external ID value in the AssumeRole call. Even if another customer supplies Example Corp with your ARN, it cannot control the external ID that Example Corp includes in its request to Amazon. This helps prevent an unauthorized customer from gaining access to your resources.

The following diagram illustrates this.

The external ID helps prevent any other customer from tricking Example Corp into unwittingly accessing your resources.

Cross-service confused deputy prevention

We recommend using the aws:SourceArn and aws:SourceAccount global condition context keys in resource-based policies to limit the permissions that a service has to a specific resource. Use aws:SourceArn if you want only one resource to be associated with the cross-service access. Use aws:SourceAccount if you want to allow any resource in that account to be associated with the cross-service use.

The most effective way to protect against the confused deputy problem is to use the aws:SourceArn global condition context key with the full ARN of the resource in your resource-based policies. If you don't know the full ARN of the resource or if you are specifying multiple resources, use the aws:SourceArn global condition context key with wildcards (*) for the unknown portions of the ARN. For example, arn:aws-cn:servicename:*:123456789012:*.

If the aws:SourceArn value does not contain the account ID, such as an Amazon S3 bucket ARN, you must use both global condition context keys to limit permissions.

For non-service-linked role trust policies, every service in the trust policy has performed the iam:PassRole action to verify that the role is in the same account as the calling service. As a result, using aws:SourceAccount with those trust policies is not necessary. Using aws:SourceArn in a trust policy allows you to specify resources a role can be assumed on behalf of, such as a Lambda function ARN. Some Amazon services use aws:SourceAccount and aws:SourceArn in trust policies for newly created roles, but using the keys isn't required for existing roles in your account.

Cross-service confused deputy prevention for Amazon Security Token Service

Many Amazon services require that you use roles to allow the service to access another service's resources on your behalf. A role that a service assumes to perform actions on your behalf is called a service role. A role requires two policies: a role trust policy that specifies the principal that is allowed to assume the role and a permissions policy that specifies what can be done with the role. A role trust policy is the only type of resource-based policy in IAM. Other Amazon services have resource-based policies, such as an Amazon S3 bucket policy.

When a service assumes a role on your behalf, the service principal must be allowed to perform the sts:AssumeRole action in the role trust policy. When a service calls sts:AssumeRole, Amazon STS returns a set of temporary security credentials that the service principal uses to access the resources that are permitted by the role’s permissions policy. When a service assumes a role in your account, you can include the aws:SourceAccount and aws:SourceArn global condition context keys in your role trust policy to limit access to the role to only requests that are generated by expected resources.

For example, in Amazon Systems Manager Incident Manager, you must choose a role to allow Incident Manager to run a Systems Manager automation document on your behalf. The automation document can include automated response plans for incidents that are initiated by CloudWatch alarms or EventBridge events. In the following role trust policy example, you can use the aws:SourceArn condition key to restrict access to the service role based on the incident record's ARN. Only incident records that are created from the response plan resource myresponseplan are able to use this role.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Principal": {
      "Service": "ssm-incidents.amazonaws.com"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "ArnLike": {
        "aws:SourceArn": "arn:aws-cn:ssm-incidents:*:111122223333:incident-record/myresponseplan/*"
      }
    }
  }
}