Amazon JSON policy elements: Principal - Amazon Identity and Access Management
Specifying a principalAmazon account principalsIndividual IAM user principalsFederated web identity user principalsFederated SAML user principalsIAM role principalsSpecific assumed-role session principalsAmazon service principalsAnonymous user principals (public access)More information
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.

Amazon JSON policy elements: Principal

Use the Principal element in a policy to specify the principal that is allowed or denied access to a resource. You cannot use the Principal element in an IAM identity-based policy. You can use it in the trust policies for IAM roles and in resource-based policies. Resource-based policies are policies that you embed directly in a resource. For example, you can embed policies in an Amazon S3 bucket or a Amazon KMS key.

You can specify any of the following principals in a policy:

  • Amazon account and root user

  • IAM users

  • Federated users (using web identity or SAML federation)

  • IAM roles

  • Assumed-role sessions

  • Amazon services

  • Anonymous users (not recommended)

Use the Principal element in these ways:

  • In IAM roles, use the Principal element in the role's trust policy to specify who can assume the role. For cross-account access, you must specify the 12-digit identifier of the trusted account. To learn whether principals in accounts outside of your zone of trust (trusted organization or account) have access to assume your roles, see What is IAM Access Analyzer?.

    Note

    After you create the role, you can change the account to "*" to allow everyone to assume the role. If you do this, we strongly recommend that you limit who can access the role through other means, such as a Condition element that limits access to only certain IP addresses. Do not leave your role accessible to everyone!

  • In resource-based policies, use the Principal element to specify the accounts or users who are allowed to access the resource.

Do not use the Principal element in policies that you attach to IAM users and groups. Similarly, you do not specify a principal in the permission policy for an IAM role. In those cases, the principal is implicitly the user that the policy is attached to (for IAM users) or the user who assumes the role (for role access policies). When the policy is attached to an IAM group, the principal is the IAM user in that group who is making the request.

Specifying a principal

You specify a principal using the Amazon Resource Name (ARN) or other identifier of the principal, as shown in the following sections. You cannot specify IAM groups and instance profiles as principals.

You can specify more than one principal for each of the principal types in following sections using an array. Arrays can take one or more values. If more than one value is included, the array is in square brackets ([ and ]) and comma-delimited, as in the following example: 

"Principal" : { 
"AWS": [ 
  "arn:aws-cn:iam::123456789012:root",
  "arn:aws-cn:iam::555555555555:root" 
  ]
}

Amazon account principals

When you use an Amazon account identifier as the principal in a policy, you delegate authority to the account. An administrator in that account can then grant access to any identity in that account. This includes IAM users and roles in that account. When you specify an Amazon account, you can use the account ARN (arn:aws-cn:iam::Amazon-account-ID:root), or a shortened form that consists of the AWS: prefix followed by the account ID.

For example, given an account ID of 123456789012, you can use either of the following methods to specify that account in the Principal element: 

"Principal": { "AWS": "arn:aws-cn:iam::123456789012:root" }
"Principal": { "AWS": "123456789012" }

You can also specify more than one Amazon account, (or canonical user ID) as a principal using an array, with any combination of the methods that we previously mentioned. 

"Principal": { 
  "AWS": [
    "arn:aws-cn:iam::123456789012:root",
    "999999999999"
  ]
}

Some Amazon services support additional options for specifying an account principal. For example, Amazon S3 lets you specify a canonical user ID using the following format: 

"Principal": { "CanonicalUser": "79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be" }

Individual IAM user principals

You can specify an individual IAM user (or array of users) as the principal, as in the following examples. When you specify more than one principal in the element, you grant permissions to each principal. This is a logical OR and not a logical AND, because you are authenticated as one principal at a time.

Note

In a Principal element, the user name is case sensitive. 

"Principal": { "AWS": "arn:aws-cn:iam::Amazon-account-ID:user/user-name" }
"Principal": {
  "AWS": [
    "arn:aws-cn:iam::Amazon-account-ID:user/user-name-1", 
    "arn:aws-cn:iam::Amazon-account-ID:user/UserName2"
  ]
}

When you specify users in a Principal element, you cannot use a wildcard (*) to mean "all users". Principals must always name a specific user or users.

Important

If your Principal element in a role trust policy contains an ARN that points to a specific IAM user, then that ARN is transformed to the user's unique principal ID when the policy is saved. This helps mitigate the risk of someone escalating their privileges by removing and recreating the user. You don't normally see this ID in the console, because there is also a reverse transformation back to the user's ARN when the trust policy is displayed. However, if you delete the user, then the relationship is broken. The policy no longer applies, even if you recreate the user. That's because the new user has a new principal ID that does not match the ID stored in the trust policy. When this happens, the principal ID shows up in the console because Amazon can no longer map it back to a valid ARN. The result is that if you delete and recreate a user referenced in a trust policy's Principal element, you must edit the role to replace the now incorrect principal ID with the correct ARN. The ARN is once again transformed into the user's new principal ID when you save the policy.

Federated web identity user principals 

"Principal": { "Federated": "cognito-identity.amazonaws.com" }
"Principal": { "Federated": "www.amazon.com" }
"Principal": { "Federated": "graph.facebook.com" }
"Principal": { "Federated": "accounts.google.com" }

Federated SAML user principals

"Principal": { "Federated": "arn:aws-cn:iam::Amazon-account-ID:saml-provider/provider-name" }

IAM role principals

"Principal": { "AWS": "arn:aws-cn:iam::Amazon-account-ID:role/role-name" }
Important

If your Principal element in a role trust policy contains an ARN that points to a specific IAM role, then that ARN is transformed to the role's unique principal ID when the policy is saved. This helps mitigate the risk of someone escalating their privileges by removing and recreating the role. You don't normally see this ID in the console, because there is also a reverse transformation back to the role's ARN when the trust policy is displayed. However, if you delete the role, then the relationship is broken. The policy no longer applies, even if you recreate the role because the new role has a new principal ID that does not match the ID stored in the trust policy. When this happens, the principal ID shows up in the console because Amazon can no longer map it back to a valid ARN. The end result is that if you delete and recreate a role referenced in a trust policy's Principal element, you must edit the role to replace the now incorrect principal ID with the correct ARN. The ARN will once again be transformed into the role's new principal ID when you save the policy.

Specific assumed-role session principals

"Principal": { "AWS": "arn:aws-cn:sts::Amazon-account-ID:assumed-role/role-name/role-session-name" }

When you specify an assumed-role session in a Principal element, you cannot use a wildcard (*) to mean "all sessions". Principals must always name a specific session.

Amazon service principals

IAM roles that can be assumed by an Amazon service are called service roles. Service roles must include a trust policy. Trust policies are resource-based policies that are attached to a role that define which principals can assume the role. Some service roles have predefined trust policies. However, in some cases, you must specify the service principal in the trust policy. A service principal is an identifier that is used to grant permissions to a service.

The identifier for a service principal includes the service name, and is usually in the following format:

service-name.amazonaws.com

However, some services might use the following format instead of or in addition to the usual format:

service-name.amazonaws.com.cn

The service principal is defined by the service. You can find the service principal for some services by opening Amazon services that work with IAM, checking whether the service has Yes in the Service-linked role column, and opening the Yes link to view the service-linked role documentation for that service. Find the Service-Linked Role Permissions section for that service to view the service principal.

The following example shows a policy that can be attached to a service role. The policy enables two services, Amazon ECS and Elastic Load Balancing, to assume the role. The services can then perform any tasks granted by the permissions policy assigned to the role (not shown). To specify multiple service principals, you do not specify two Service elements; you can have only one. Instead, you use an array of multiple service principals as the value of a single Service element. 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "ecs.amazonaws.com",
          "elasticloadbalancing.amazonaws.com"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Anonymous user principals (public access)

For resource-based policies, such as Amazon S3 bucket policies, a wildcard (*) in the principal element specifies all users or public access. The following elements are equivalent: 

"Principal": "*"
"Principal" : { "AWS" : "*" }

You cannot use a wildcard to match part of a name or an ARN.

We strongly recommend that you do not use a wildcard in the Principal element in a role's trust policy unless you otherwise restrict access through a Condition element in the policy. Otherwise, any IAM user in any account in your partition can access the role.

More information

For more information, see the following: