Amazon JSON policy elements: NotPrincipal - Amazon Identity and Access Management
Specifying NotPrincipal with Deny
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: NotPrincipal

You can use the NotPrincipal element to deny access to all principals except the IAM user, federated user, IAM role, Amazon Web Services account, Amazon service, or other principal specified in the NotPrincipal element.

You can use it in resource-based policies for some Amazon services, including VPC endpoints. Resource-based policies are policies that you embed directly in a resource. You cannot use the NotPrincipal element in an IAM identity-based policy nor in an IAM role trust policy.

NotPrincipal must be used with "Effect":"Deny". Using it with "Effect":"Allow" is not supported.

Important

Very few scenarios require the use of NotPrincipal. We recommend that you explore other authorization options before you decide to use NotPrincipal. When you use NotPrincipal, troubleshooting the effects of multiple policy types can be difficult. We recommend using the aws:PrincipalArn context key with ARN condition operators instead. For more information, see All principals.

Specifying NotPrincipal with Deny

When you use NotPrincipal with Deny, you must also specify the account ARN of the not-denied principal. Otherwise, the policy might deny access to the entire account containing the principal. Depending on the service that you include in your policy, Amazon might validate the account first and then the user. If an assumed-role user (someone who is using a role) is being evaluated, Amazon might validate the account first, then the role, and then the assumed-role user. The assumed-role user is identified by the role session name that is specified when they assumed the role. Therefore, we strongly recommend that you explicitly include the ARN for a user's account, or include both the ARN for a role and the ARN for the account containing that role.

Important

Don't use resource-based policy statements that include a NotPrincipal policy element with a Deny effect for IAM users or roles that have a permissions boundary policy attached. The NotPrincipal element with a Deny effect will always deny any IAM principal that has a permissions boundary policy attached, regardless of the values specified in the NotPrincipal element. This causes some IAM users or roles that would otherwise have access to the resource to lose access. We recommend changing your resource-based policy statements to use the condition operator ArnNotEquals with the aws:PrincipalArn context key to limit access instead of the NotPrincipal element. For information about permissions boundaries, see Permissions boundaries for IAM entities.

Note

As a best practice, you should include the ARNs for the account in your policy. Some services require the account ARN, although this is not required in all cases. Any existing policies without the required ARN will continue to work, but new policies that include these services must meet this requirement. IAM does not track these services, and therefore recommends that you always include the account ARN.

The following examples show how to use NotPrincipal and "Effect": "Deny" in the same policy statement effectively.

Example IAM user in the same or a different account

In the following example, all principals except the user named Bob in Amazon Web Services account 444455556666 are explicitly denied access to a resource. Note that as a best practice, the NotPrincipal element contains the ARN of both the user Bob and the Amazon Web Services account that Bob belongs to (arn:aws-cn:iam::444455556666:root). If the NotPrincipal element contained only Bob's ARN, the effect of the policy might be to explicitly deny access to the Amazon Web Services account that contains the user Bob. In some cases, a user cannot have more permissions than its parent account, so if Bob's account is explicitly denied access then Bob might be unable to access the resource.

This example works as intended when it is part of a policy statement in a resource-based policy that is attached to a resource in either the same or a different Amazon Web Services account (not 444455556666). This example by itself does not grant access to Bob, it only omits Bob from the list of principals that are explicitly denied. To allow Bob access to the resource, another policy statement must explicitly allow access using "Effect": "Allow".

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Deny",
        "NotPrincipal": {"AWS": [
            "arn:aws-cn:iam::444455556666:user/Bob",
            "arn:aws-cn:iam::444455556666:root"
        ]},
        "Action": "s3:*",
        "Resource": [
            "arn:aws-cn:s3:::BUCKETNAME",
            "arn:aws-cn:s3:::BUCKETNAME/*"
        ]
    }]
}
Example IAM role in the same or different account

In the following example, all principals except the assumed-role user named cross-account-audit-app in Amazon Web Services account 444455556666 are explicitly denied access to a resource. As a best practice, the NotPrincipal element contains the ARN of the assumed-role user (cross-account-audit-app), the role (cross-account-read-only-role), and the Amazon Web Services account that the role belongs to (444455556666). If the NotPrincipal element was missing the ARN of the role, the effect of the policy might be to explicitly deny access to the role. Similarly, if the NotPrincipal element was missing the ARN of the Amazon Web Services account that the role belongs to, the effect of the policy might be to explicitly deny access to the Amazon Web Services account and all entities in that account. In some cases, assumed-role users cannot have more permissions than their parent role, and roles cannot have more permissions than their parent Amazon Web Services account, so when the role or the account is explicitly denied access, the assumed role user might be unable to access the resource.

This example works as intended when it is part of a policy statement in a resource-based policy that is attached to a resource in a different Amazon Web Services account (not 444455556666). This example by itself does not allow access to the assumed-role user cross-account-audit-app, it only omits cross-account-audit-app from the list of principals that are explicitly denied. To give cross-account-audit-app access to the resource, another policy statement must explicitly allow access using "Effect": "Allow".

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Deny",
        "NotPrincipal": {"AWS": [
            "arn:aws-cn:sts::444455556666:assumed-role/cross-account-read-only-role/cross-account-audit-app",
            "arn:aws-cn:iam::444455556666:role/cross-account-read-only-role",
            "arn:aws-cn:iam::444455556666:root"
        ]},
        "Action": "s3:*",
        "Resource": [
            "arn:aws-cn:s3:::Bucket_AccountAudit",
            "arn:aws-cn:s3:::Bucket_AccountAudit/*"
        ]
    }]
}

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