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).

Amazon JSON policy elements: Principal

Use the Principal element in a resource-based JSON policy to specify the principal that is allowed or denied access to a resource.

You must use the Principal element in resource-based policies. Several services support resource-based policies, including IAM. The IAM resource-based policy type is a role trust policy. In IAM roles, use the Principal element in the role 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?.

Other examples of resources that support resource-based policies include an Amazon S3 bucket or an Amazon KMS key.

You cannot use the Principal element in an identity-based policy. Identity-based policies are permissions policies that you attach to IAM identities (users, groups, or roles). In those cases, the principal is implicitly the identity where the policy is attached.

How to specify a principal

You specify a principal in the Principal element of a resource-based policy or in condition keys that support principals.

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

You cannot identify a user group as a principal in a policy (such as a resource-based policy) because groups relate to permissions, not authentication, and principals are authenticated IAM entities.

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. When you specify more than one principal in an element, you grant permissions to each principal. This is a logical OR and not a logical AND, because you authenticate as one principal at a time. If you include more than one value, use square brackets ([ and ]) and comma-delimit each entry for the array. The following example policy defines permissions for the 123456789012 account or the 555555555555 account.

"Principal" : { 
"AWS": [ 
  "123456789012",
  "555555555555" 
  ]
}

Amazon Web Services account principals

You can specify Amazon Web Services account identifiers in the Principal element of a resource-based policy or in condition keys that support principals. This delegates authority to the account. When you allow access to a different account, an administrator in that account must then grant access to an identity (IAM user or role) in that account. When you specify an Amazon Web Services account, you can use the account ARN (arn:aws-cn:iam::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" }

The account ARN and the shortened account ID behave the same way. Both delegate permissions to the account. Using the account ARN in the Principal element does not limit permissions to only the root user of the account.

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" }

You can also specify more than one Amazon Web Services account, (or canonical user ID) as a principal using an array. For example, you can specify a principal in a bucket policy using all three methods.

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

IAM role principals

You can specify IAM role principal ARNs in the Principal element of a resource-based policy or in condition keys that support principals. IAM roles are identities. In IAM, identities are resources to which you can assign permissions. Roles trust another authenticated identity to assume that role. This includes a principal in Amazon or a user from an external identity provider (IdP). When a principal or identity assumes a role, they receive temporary security credentials with the assumed role’s permissions. When they use those session credentials to perform operations in Amazon, they become a role session principal.

IAM roles are identities that exist in IAM. Roles trust another authenticated identity, such as a principal in Amazon or a user from an external identity provider. When a principal or identity assumes a role, they receive temporary security credentials. They can then use those credentials as a role session principal to perform operations in Amazon.

When you specify a role principal in a resource-based policy, the effective permissions for the principal are limited by any policy types that limit permissions for the role. This includes session policies and permissions boundaries. For more information about how the effective permissions for a role session are evaluated, see Policy evaluation logic.

To specify the role ARN in the Principal element, use the following format:

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

Alternatively, you can specify the role principal as the principal in a resource-based policy or create a broad-permission policy that uses the aws:PrincipalArn condition key. When you use this key, the role session principal is granted the permissions based on the ARN of role that was assumed, and not the ARN of the resulting session. Because Amazon does not convert condition key ARNs to IDs, permissions granted to the role ARN persist if you delete the role and then create a new role with the same name. Identity-based policy types, such as permissions boundaries or session policies, do not limit permissions granted using the aws:PrincipalArn condition key with a wildcard(*) in the Principal element, unless the identity-based policies contain an explicit deny.

Role session principals

You can specify role sessions in the Principal element of a resource-based policy or in condition keys that support principals. When a principal or identity assumes a role, they receive temporary security credentials with the assumed role’s permissions. When they use those session credentials to perform operations in Amazon, they become a role session principal.

The format that you use for a role session principal depends on the Amazon STS operation that was used to assume the role.

Additionally, administrators can design a process to control how role sessions are issued. For example, they can provide a one-click solution for their users that creates a predictable session name. If your administrator does this, you can use role session principals in your policies or condition keys. Otherwise, you can specify the role ARN as a principal in the aws:PrincipalArn condition key. How you specify the role as a principal can change the effective permissions for the resulting session. For more information, see IAM role principals.

Assumed-role session principals

An assumed-role session principal is a session principal that results from using the Amazon STS AssumeRole operation. For more information about which principals can assume a role using this operation, see Compare Amazon STS credentials.

To specify the assumed-role session ARN in the Principal element, use the following format:

"Principal": { "AWS": "arn:aws-cn:sts::AWS-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.

OIDC federated principals

An OIDC federated principal is one type of principal created when authenticating through Amazon STS AssumeRoleWithWebIdentity. This principal supports various identity providers including OpenID Connect, OAuth 2.0 providers like Login with Amazon, Facebook, Google, and Amazon Cognito federated identities.

Identities who've authenticated with a web identity provider, include a JSON web token (JWT) from an OIDC provider in the API call. This token both verifies their identity and returns temporary Amazon security credentials. However, two prerequisites must be met. First, you must obtain a JWT from a supported identity provider. Second, you must add the identity provider to your Amazon Web Services account and configure it. You assign an IAM role to your identity provider to give your external user identities managed by your identity provider permissions to access Amazon resources in your account. AssumeRoleWithWebIdentity doesn't require Amazon credentials for authentication. See OIDC federation for mobile apps and Requesting credentials through an OIDC provider for more information.

Use this principal type in your policy to allow or deny access based on the built-in trusted web identity provider. Amazon natively supports Amazon, Facebook, Google, and Amazon Cognito as identity providers, so you don't need additional configuration. To specify the OIDC federated principal ARN in the Principal element of a role trust policy, use the following format:

"Principal": { "Federated": "cognito-identity.amazonaws.com" }

"Principal": { "Federated": "www.amazon.com" }

"Principal": { "Federated": "graph.facebook.com" }

"Principal": { "Federated": "accounts.google.com" }

When using a custom OIDC provider (i.e. it is created and managed in IAM) rather than Amazon-supported providers, specify the provider's ARN in your role's trust policy. This configuration allows you to write IAM policies that control access specifically for users authenticated through your custom identity provider.

"Principal": { "Federated": "arn:aws:iam::AWS-account-ID:oidc-provider/full-OIDC-identity-provider-URL" }

Use this principal type in your policy to allow or deny access based on custom trusted web identity provider. For example, if GitHub was the trusted web identity provider, the OIDC role session ARN in the Principal element of a role trust policy, uses the following format:

"Principal": { "Federated": "arn:aws:iam::AWS-account-ID:oidc-provider/tokens.actions.githubusercontent.com" }

See Configuring OpenID Connect in Amazon Web Services for more information.

SAML federated principals

A SAML federated principal is a session principal that results from using the Amazon STS AssumeRoleWithSAML operation. Similar to AssumeRoleWithWebIdentity, AssumeRoleWithSAML doesn't require Amazon credentials for authentication. Instead, users first authenticate with their SAML identity provider, then make the AssumeRoleWithSAML API call with three required parameters. These parameters are: the SAML assertion (received from their identity provider), the RoleArn (the role they wish to assume), and the PrincipalArn (the ARN of the SAML provider configured in IAM). This call returns temporary Amazon security credentials for accessing Amazon resources. For more information about which principals can assume a role using this operation, see Compare Amazon STS credentials.

When you issue a role from a SAML identity provider, you get this special type of session principal that includes information about the SAML identity provider.

Use this principal type in your policy to allow or deny access based on the trusted SAML identity provider. To specify the SAML identity role session ARN in the Principal element of a role trust policy, use the following format:

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

IAM user principals

You can specify IAM users in the Principal element of a resource-based policy or in condition keys that support principals.

"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/user-name-2"
  ]
}

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

IAM Identity Center principals

In IAM Identity Center, the principal in a resource-based policy must be defined as the Amazon Web Services account principal. To specify access, reference the role ARN of the permission set in the condition block. For details, see Referencing permission sets in resource policies, Amazon EKS, and Amazon KMS in the IAM Identity Center User Guide.

Amazon STS federated user principals

You can specify federated user sessions in the Principal element of a resource-based policy or in condition keys that support principals.

An Amazon STS federated user principal is created through the GetFederationToken operation, but it differs fundamentally from federated role session principals (created via AssumeRoleWithSAML or AssumeRoleWithWebIdentity). In this case, Amazon STS uses identity federation as the method to obtain temporary access tokens instead of using IAM roles. Unlike role-based federation methods, GetFederationToken requires authentication using user’s Amazon long-term credentials before obtaining temporary security credentials. While the operation can be called using either IAM user credentials or Amazon Web Services account root user credentials, the latter is strongly discouraged for security reasons. For more information, see Follow best practices to protect your root user credentials in the IAM User Guide.

GetFederationToken requires managing and securing long-term Amazon credentials. Alternative federation methods such as IAM roles anywhere, SAML federation, OIDC and OAuth2 federation eliminate the need for long-term credential and are recommended as alternatives to using GetFederationToken API call.

In Amazon, IAM users or an Amazon Web Services account root user can authenticate using long-term access keys. For more information about which principals can federate using this operation, see Compare Amazon STS credentials.

When an IAM user or root user requests temporary credentials from Amazon STS using this operation, they begin a temporary federated user session. This session’s ARN is based on the original identity that was federated.

To specify the federated user session ARN in the Principal element, use the following format:

"Principal": { "AWS": "arn:aws-cn:sts::AWS-account-ID:federated-user/user-name" }

Amazon service principals

You can specify Amazon services in the Principal element of a resource-based policy or in condition keys that support principals. A service principal is an identifier for a service.

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 attached to a role that defines 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. The service principal in an IAM policy can't be "Service": "*".

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.

"Principal": {
    "Service": [
        "ecs.amazonaws.com",
        "elasticloadbalancing.amazonaws.com"
   ]
}

Amazon service principals in opt-in Regions

You can launch resources in several Amazon Regions and some of those Regions you must opt in to. For a complete list of Regions you must opt in to, see Managing Amazon Regions in the Amazon Web Services General Reference guide.

When an Amazon service in an opt-in Region makes a request within the same Region, the service principal name format is identified as the non-regionalized version of their service principal name:

service-name.amazonaws.com

When an Amazon service in an opt-in Region makes a cross-region request to another Region, the service principal name format is identified as the regionalized version of their service principal name:

service-name.{region}.amazonaws.com

For example, you have an Amazon SNS topic located in Region ap-southeast-1 and an Amazon S3 bucket located in opt-in Region ap-east-1. You want to configure S3 bucket notifications to publish messages to the SNS topic. To allow the S3 service to post messages to the SNS topic you must grant the S3 service principal sns:Publish permission via the resource-based access policy of the topic.

If you specify the non-regionalized version of the S3 service principal, s3.amazonaws.com, in the topic access policy, the sns:Publish request from the bucket to the topic will fail. The following example specifies the non-regionalized S3 service principal in the Principal policy element of the SNS topic access policy.

"Principal": { "Service": "s3.amazonaws.com" }

Since the bucket is located in an opt-in Region and the request is made outside of that same Region, the S3 service principal appears as the regionalized service principal name, s3.ap-east-1.amazonaws.com. You must use the regionalized service principal name when an Amazon service in an opt-in Region makes a request to another Region. After you specify the regionalized service principal name, if the bucket makes an sns:Publish request to the SNS topic located in another Region, the request will be successful. The following example specifies the regionalized S3 service principal in the Principal policy element of the SNS topic access policy.

"Principal": { "Service": "s3.ap-east-1.amazonaws.com" }

Resource policies or service principal-based allow-lists for cross-Region requests from an opt-in Region to another Region will only be successful if you specify the regionalized service principal name.

All principals

You can use a wildcard (*) to specify all principals in the Principal element of a resource-based policy or in condition keys that support principals. Resource-based policies grant permissions and condition keys are used to limit the conditions of a policy statement.

For resource-based policies, using a wildcard (*) with an Allow effect grants access to all users, including anonymous users (public access). For IAM users and role principals within your account, no other permissions are required. For principals in other accounts, they must also have identity-based permissions in their account that allow them to access your resource. This is called cross-account access.

For anonymous users, the following elements are equivalent:

"Principal": "*"

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

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

The following example shows a resource-based policy that can be used instead of Amazon JSON policy elements: NotPrincipal to explicitly deny all principals except for the ones specified in the Condition element. This policy should be added to an Amazon S3 bucket.

JSON

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "UsePrincipalArnInsteadOfNotPrincipalWithDeny",
      "Effect": "Deny",
      "Action": "s3:*",
      "Principal": "*",
      "Resource": [
        "arn:aws-cn:s3:::amzn-s3-demo-bucket/*",
        "arn:aws-cn:s3:::amzn-s3-demo-bucket"
      ],
      "Condition": {
        "ArnNotEquals": {
          "aws:PrincipalArn": "arn:aws-cn:iam::444455556666:user/user-name"
        }
      }
    }
  ]
}

More information

For more information, see the following: