Introduction

AWS does not support renaming an existing customer managed IAM policy in place. In practice, "renaming" a policy means creating a new policy with the same document under the new name, attaching it wherever the old one was used, and then deleting the old policy when it is no longer attached.

Why There Is No Rename Operation

An IAM policy is identified by its ARN, and the policy name is part of that identity. AWS lets you edit the policy document by creating new versions, but that changes permissions, not the policy's name or ARN.

That distinction matters operationally:

• changing a policy version keeps the same policy identity
• changing the name requires a new policy resource
• anything referring to the old policy ARN must be updated

So the safe mental model is that a rename is really a controlled replacement.

Step 1: Export the Existing Policy Document

First, identify the current default version of the policy and fetch its JSON document.

aws iam get-policy \
  --policy-arn arn:aws:iam::111122223333:policy/OldPolicyName

Then fetch the default version itself.

aws iam get-policy-version \
  --policy-arn arn:aws:iam::111122223333:policy/OldPolicyName \
  --version-id v1

In a real account, replace v1 with the DefaultVersionId returned by get-policy.

If the policy uses tags or a useful description, capture those too so the replacement is complete rather than just permission-equivalent.

Step 2: Create the New Policy

Once you have the JSON document, create a new customer managed policy with the desired name.

1aws iam create-policy \
2  --policy-name NewPolicyName \
3  --policy-document file://policy.json \
4  --description "Replacement for OldPolicyName"

This creates a new ARN. From this point on, you have two separate policies in your account even if their JSON is identical.

Step 3: Find Every Attachment of the Old Policy

Before detaching anything, discover where the old policy is currently attached.

aws iam list-entities-for-policy \
  --policy-arn arn:aws:iam::111122223333:policy/OldPolicyName

That output tells you which users, groups, and roles currently depend on the old policy. This step is critical, because forgetting one attachment is the easiest way to cause an unexpected authorization failure after cleanup.

Step 4: Attach the New Policy Everywhere

Now attach the new policy to the same principals.

1aws iam attach-role-policy \
2  --role-name AppServerRole \
3  --policy-arn arn:aws:iam::111122223333:policy/NewPolicyName
4
5aws iam attach-user-policy \
6  --user-name deploy-bot \
7  --policy-arn arn:aws:iam::111122223333:policy/NewPolicyName

If the old policy was attached to groups, use attach-group-policy as well.

A careful migration sequence is:

• attach the new policy first
• verify access still works
• only then detach the old policy

That prevents accidental permission gaps.

Step 5: Detach and Delete the Old Policy

After you confirm the replacement is attached everywhere, remove the old one.

aws iam detach-role-policy \
  --role-name AppServerRole \
  --policy-arn arn:aws:iam::111122223333:policy/OldPolicyName

Once the old policy has no more attachments and no dependent policy versions to worry about, delete it.

aws iam delete-policy \
  --policy-arn arn:aws:iam::111122223333:policy/OldPolicyName

AWS will reject the delete if the policy is still attached.

Policy Versions Are Not Renames

A common misunderstanding is thinking you can solve this by creating a new policy version and setting it as default. That is useful when permissions need to change, but it does not rename the policy.

The policy ARN, policy name, and every reference to that identity remain exactly the same.

So if your goal is cleaner naming, environment standardization, or migration to a new naming convention, you need a new policy resource.

Common Pitfalls

The biggest mistake is deleting the old policy before confirming every user, group, and role has the new one attached.

Another mistake is preserving only the JSON document but forgetting metadata such as tags, descriptions, or documentation references tied to the old policy.

A third issue is overlooking code and infrastructure that refer to the old policy ARN explicitly. CloudFormation templates, Terraform variables, and internal deployment scripts may need updates even after the IAM attachments are fixed.

Finally, do not confuse customer managed policies with inline policies. Inline policies do not have the same rename workflow because they are embedded directly in a principal.

Summary

• AWS does not support renaming a customer managed IAM policy in place.
• A rename is implemented as create new, attach new, detach old, delete old.
• Export the current default policy version before changing anything.
• Use list-entities-for-policy to find every attachment of the old policy.
• Attach the new policy before detaching the old one to avoid outages.
• Update any hard-coded references to the old policy ARN as part of the migration.