AWS IAM medium security documentation change
Summary
Added link to article about handling deleted IAM roles in policies, clarified federated principal types (OIDC/SAML), and added S3 bucket policy implementation note
Security assessment
The added link explains security implications of role deletion/recreation and principal ID transformations that prevent privilege escalation. This directly documents a security control mechanism.
Diff
diff --git a/IAM/latest/UserGuide/reference_policies_elements_principal.md b/IAM/latest/UserGuide/reference_policies_elements_principal.md index 6c8746db5..1ef88af2b 100644 --- a/IAM/latest/UserGuide/reference_policies_elements_principal.md +++ b/IAM/latest/UserGuide/reference_policies_elements_principal.md @@ -136 +136 @@ To specify the role ARN in the `Principal` element, use the following format: -If your `Principal` element in a role trust policy contains an ARN that points to a specific IAM role, then that ARN transforms to the role unique principal ID when you save the policy. 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 IAM uses a reverse transformation back to the role ARN when the trust policy is displayed. However, if you delete the role, then you break the relationship. 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 appears in resource-based policies because AWS 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 in the policy to replace the principal ID with the correct ARN. The ARN once again transforms into the role's new principal ID when you save the policy. +If your `Principal` element in a role trust policy contains an ARN that points to a specific IAM role, then that ARN transforms to the role unique principal ID when you save the policy. 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 IAM uses a reverse transformation back to the role ARN when the trust policy is displayed. However, if you delete the role, then you break the relationship. 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 appears in resource-based policies because AWS 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 in the policy to replace the principal ID with the correct ARN. The ARN once again transforms into the role's new principal ID when you save the policy. For more information, see [Understanding AWS's Handling of Deleted IAM roles in Policies](https://repost.aws/articles/ARSqFcxvd7R9u-gcFD9nmA5g/understanding-aws-s-handling-of-deleted-iam-roles-in-policies). @@ -159 +159 @@ When you specify an assumed-role session in a `Principal` element, you cannot us -### Federated principals +### OIDC federated principals @@ -161 +161 @@ When you specify an assumed-role session in a `Principal` element, you cannot us -A _federated principal_ is a session principal that results from using the AWS STS `AssumeRoleWithWebIdentity` operation. You can use an external OIDC or SAML providers (IdP) to sign in, and then assume an IAM role using this operation. This leverages identity federation and issues a role session. For more information about which principals can assume a role using this operation, see [Compare AWS STS credentials](./id_credentials_sts-comparison.html). +A _federated principal_ is a session principal that results from using the AWS STS `AssumeRoleWithWebIdentity` operation. You can use an external OIDC provider (IdP) to sign in, and then assume an IAM role using this operation. This leverages identity federation and issues a role session. For more information about which principals can assume a role using this operation, see [Compare AWS STS credentials](./id_credentials_sts-comparison.html). @@ -184 +184 @@ Use this principal type in your policy to allow or deny access based on custom t -### SAML session principals +### SAML federated principals @@ -186 +186 @@ Use this principal type in your policy to allow or deny access based on custom t -A _SAML session principal_ is a session principal that results from using the AWS STS `AssumeRoleWithSAML` operation. You can use an external SAML identity provider (IdP) to sign in, and then assume an IAM role using this operation. This leverages identity federation and issues a role session. For more information about which principals can assume a role using this operation, see [Compare AWS STS credentials](./id_credentials_sts-comparison.html). +A _SAML federated principal_ is a session principal that results from using the AWS STS `AssumeRoleWithSAML` operation. You can use an external SAML identity provider (IdP) to sign in, and then assume an IAM role using this operation. This leverages identity federation and issues a role session. For more information about which principals can assume a role using this operation, see [Compare AWS STS credentials](./id_credentials_sts-comparison.html). @@ -324 +324 @@ 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 [AWS JSON policy elements: NotPrincipal](./reference_policies_elements_notprincipal.html) to explicitly deny all principals _except_ for the ones specified in the `Condition` element. +The following example shows a resource-based policy that can be used instead of [AWS JSON policy elements: NotPrincipal](./reference_policies_elements_notprincipal.html) to explicitly deny all principals _except_ for the ones specified in the `Condition` element. This policy should be [added to an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-bucket-policy.html).