Amazon JSON policy elements: NotPrincipal
Use the NotPrincipal
element to specify the IAM user, federated user, IAM
role, Amazon Web Services account, Amazon service, or other principal that is not allowed or denied access to a resource. The
NotPrincipal
element enables you to specify an exception to a list of principals.
Use this element to deny access to all principals except the one named in
the NotPrincipal
element. The syntax for specifying NotPrincipal
is
the same as for specifying Amazon JSON policy elements:
Principal.
You cannot use the NotPrincipal
element in an IAM identity-based policy or in
an IAM role trust policy. You can use it in resource-based policies for some Amazon services.
Resource-based policies are policies that you embed directly in a resource.
Important
Very few scenarios require the use of NotPrincipal
, and we recommend that you
explore other authorization options before you decide to use NotPrincipal
.
NotPrincipal
With
Allow
We strongly recommend that you do not use NotPrincipal
in the same policy
statement as "Effect": "Allow"
. Doing so allows all principals
except the one named in the NotPrincipal
element. We do
not recommend this because the permissions specified in the policy statement will be granted
to all principals except for the ones specified. By doing this, you might
grant access to anonymous (unauthenticated) users.
You cannot use the NotPrincipal
element in an IAM identity-based policy or
in an IAM role trust policy. Most resource-based policy types do not allow the use of
NotPrincipal
with "Effect": "Allow"
. Over time, Amazon will
restrict the use of these policy statements across all permissions policies.
NotPrincipal
With
Deny
Note
When you use NotPrincipal
in the same policy statement as "Effect":
"Deny"
, it can be difficult to troubleshoot the effects of multiple policy types.
We recommend using the aws:PrincipalArn
condition key instead. For more
information, see All principals.
When you use NotPrincipal
in the same policy statement as "Effect":
"Deny"
, the actions specified in the policy statement are explicitly denied to all
principals except for the ones specified. 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.
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.