# Migrating access control for AWS Billing
<a name="migrate-granularaccess-whatis"></a>

**Note**  
The following AWS Identity and Access Management (IAM) actions have reached the end of standard support on July 2023:  
`aws-portal` namespace
`purchase-orders:ViewPurchaseOrders`
`purchase-orders:ModifyPurchaseOrders`
If you're using AWS Organizations, you can use the [bulk policy migrator scripts](migrate-iam-permissions.md) or bulk policy migrator to update polices from your payer account. You can also use the [old to granular action mapping reference](migrate-granularaccess-iam-mapping-reference.md) to verify the IAM actions that need to be added.  
If you have an AWS account, or are a part of an AWS Organizations created on or after March 6, 2023, 11:00 AM (PDT), the fine-grained actions are already in effect in your organization.

You can use fine-grained access controls to provide individuals in your organization access to AWS Billing and Cost Management services. For example, you can provide access to Cost Explorer without providing access to the Billing and Cost Management console.

To use the fine-grained access controls, you'll need to migrate your policies from under `aws-portal` to the new IAM actions.

The following IAM actions in your permission policies or service control policies (SCP) require updating with this migration:
+ `aws-portal:ViewAccount`
+ `aws-portal:ViewBilling`
+ `aws-portal:ViewPaymentMethods`
+ `aws-portal:ViewUsage`
+ `aws-portal:ModifyAccount`
+ `aws-portal:ModifyBilling`
+ `aws-portal:ModifyPaymentMethods`
+ `purchase-orders:ViewPurchaseOrders`
+ `purchase-orders:ModifyPurchaseOrders`

To learn how to use the **Affected policies** tool to identify your impacted IAM policies, see [How to use the affected policies tool](migrate-security-iam-tool.md).

**Note**  
API access to AWS Cost Explorer, AWS Cost and Usage Reports, and AWS Budgets remains unaffected.  
[Activating access to the Billing and Cost Management console](control-access-billing.md#ControllingAccessWebsite-Activate) remain unchanged.

**Topics**
+ [Managing access permissions](#migrate-control-access-billing)
+ [Using the console to bulk migrate your policies](migrate-granularaccess-console.md)
+ [How to use the affected policies tool](migrate-security-iam-tool.md)
+ [Use scripts to bulk migrate your policies to use fine-grained IAM actions](migrate-iam-permissions.md)
+ [Mapping fine-grained IAM actions reference](migrate-granularaccess-iam-mapping-reference.md)

## Managing access permissions
<a name="migrate-control-access-billing"></a>

AWS Billing integrates with the AWS Identity and Access Management (IAM) service so that you can control who in your organization can access specific pages on the [Billing and Cost Management console](https://console.aws.amazon.com/billing/). This includes features like Payments, Billing, Credits, Free Tier, Payment preferences, Consolidated billing, Tax settings, and Account pages.

Use the following IAM permissions for granular control for the Billing and Cost Management console.

To provide fine-grained access, replace the `aws-portal` policy with `account`, `billing`, `payments`, `freetier`, `invoicing`, `tax`, and `consolidatedbilling`.

Additionally, replace `purchase-orders:ViewPurchaseOrders` and `purchase-orders:ModifyPurchaseOrders` with the fine-grained actions under `purchase-orders`, `account`, and `payments`.

### Using fine-grained AWS Billing actions
<a name="migrate-user-permissions"></a>

This table summarizes the permissions that allow or deny IAM users and roles access to your billing information. For examples of policies that use these permissions, see [AWS Billing policy examples](billing-example-policies.md). 

For a list of actions for the AWS Cost Management console, see [AWS Cost Management actions policies](https://docs.aws.amazon.com/cost-management/latest/userguide/billing-permissions-ref.html#user-permissions) in the *AWS Cost Management User Guide*.

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/migrate-granularaccess-whatis.html)

# Using the console to bulk migrate your policies
<a name="migrate-granularaccess-console"></a>

**Note**  
The following AWS Identity and Access Management (IAM) actions have reached the end of standard support on July 2023:  
`aws-portal` namespace
`purchase-orders:ViewPurchaseOrders`
`purchase-orders:ModifyPurchaseOrders`
If you're using AWS Organizations, you can use the [bulk policy migrator scripts](migrate-iam-permissions.md) or bulk policy migrator to update polices from your payer account. You can also use the [old to granular action mapping reference](migrate-granularaccess-iam-mapping-reference.md) to verify the IAM actions that need to be added.  
If you have an AWS account, or are a part of an AWS Organizations created on or after March 6, 2023, 11:00 AM (PDT), the fine-grained actions are already in effect in your organization.

This section covers how you can use the [AWS Billing and Cost Management console](https://console.aws.amazon.com/billing/) to migrate your legacy policies from your Organizations accounts or standard accounts to the fine-grained actions in bulk. You can complete migrating your legacy policies using the console in two ways:

**Using the AWS recommended migration process**  
This is a streamlined, single-action process where you migrates legacy actions to the fine-grained actions as mapped by AWS. For more information, see [Using recommended actions to bulk migrate legacy policies](migrate-console-streamlined.md).

**Using the customized migration process**  
This process allows you to review and change the actions recommended by AWS prior to the bulk migration, as well as customize which accounts in your organization are migrated. For more information, see [Customizing actions to bulk migrate legacy policies](migrate-console-customized.md).

## Prerequisites for bulk migrating using the console
<a name="migrate-granularaccess-console-prereq"></a>

Both migration options require you to consent in the console so that AWS can recommend fine-grained actions to the legacy IAM actions you have assigned. To do this, you will need to login to your AWS account as an [IAM principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) with the following IAM actions to continue with the policy updates.

------
#### [ Management account ]

```
// Required to view page
"ce:GetConsoleActionSetEnforced",
"aws-portal:GetConsoleActionSetEnforced",
"purchase-orders:GetConsoleActionSetEnforced",
"ce:UpdateConsoleActionSetEnforced",
"aws-portal:UpdateConsoleActionSetEnforced",
"purchase-orders:UpdateConsoleActionSetEnforced",
"iam:GetAccountAuthorizationDetails",
"s3:CreateBucket",
"s3:DeleteObject",
"s3:ListAllMyBuckets",
"s3:GetObject",
"s3:PutObject",
"s3:ListBucket",
"s3:PutBucketAcl",
"s3:PutEncryptionConfiguration",
"s3:PutBucketVersioning",
"s3:PutBucketPublicAccessBlock",
"lambda:GetFunction",
"lambda:DeleteFunction",
"lambda:CreateFunction",
"lambda:InvokeFunction",
"lambda:RemovePermission",
"scheduler:GetSchedule", 
"scheduler:DeleteSchedule",
"scheduler:CreateSchedule",
"cloudformation:ActivateOrganizationsAccess",
"cloudformation:CreateStackSet",
"cloudformation:CreateStackInstances",
"cloudformation:DescribeStackSet",
"cloudformation:DescribeStackSetOperation",
"cloudformation:ListStackSets",
"cloudformation:DeleteStackSet",
"cloudformation:DeleteStackInstances",
"cloudformation:ListStacks",
"cloudformation:ListStackInstances",
"cloudformation:ListStackSetOperations",
"cloudformation:CreateStack",
"cloudformation:UpdateStackInstances",
"cloudformation:UpdateStackSet",
"cloudformation:DescribeStacks",
"ec2:DescribeRegions",
"iam:GetPolicy",
"iam:GetPolicyVersion",
"iam:GetUserPolicy",
"iam:GetGroupPolicy",
"iam:GetRole",
"iam:GetRolePolicy",
"iam:CreatePolicyVersion",
"iam:DeletePolicyVersion",
"iam:ListAttachedRolePolicies",
"iam:ListPolicyVersions",
"iam:PutUserPolicy",
"iam:PutGroupPolicy",
"iam:PutRolePolicy",
"iam:SetDefaultPolicyVersion",
"iam:GenerateServiceLastAccessedDetails",
"iam:GetServiceLastAccessedDetails",
"iam:GenerateOrganizationsAccessReport",
"iam:GetOrganizationsAccessReport",
"organizations:ListAccounts",
"organizations:ListPolicies",
"organizations:DescribePolicy",
"organizations:UpdatePolicy",
"organizations:DescribeOrganization",
"organizations:ListAccountsForParent",
"organizations:ListRoots",
"sts:AssumeRole",
"sso:ListInstances",
"sso:ListPermissionSets",
"sso:GetInlinePolicyForPermissionSet",
"sso:DescribePermissionSet",
"sso:PutInlinePolicyToPermissionSet",
"sso:ProvisionPermissionSet",
"sso:DescribePermissionSetProvisioningStatus",
"notifications:ListNotificationHubs" // Added to ensure Notifications API does not return 403
```

------
#### [ Member account or standard account ]

```
// Required to view page
"ce:GetConsoleActionSetEnforced",
"aws-portal:GetConsoleActionSetEnforced",
"purchase-orders:GetConsoleActionSetEnforced",
"ce:UpdateConsoleActionSetEnforced", // Not needed for member account
"aws-portal:UpdateConsoleActionSetEnforced", // Not needed for member account
"purchase-orders:UpdateConsoleActionSetEnforced", // Not needed for member account
"iam:GetAccountAuthorizationDetails",
"ec2:DescribeRegions",
"s3:CreateBucket",
"s3:DeleteObject",
"s3:ListAllMyBuckets",
"s3:GetObject",
"s3:PutObject",
"s3:ListBucket",
"s3:PutBucketAcl", 
"s3:PutEncryptionConfiguration",
"s3:PutBucketVersioning",
"s3:PutBucketPublicAccessBlock",
"iam:GetPolicy",
"iam:GetPolicyVersion",
"iam:GetUserPolicy",
"iam:GetGroupPolicy",
"iam:GetRolePolicy",
"iam:GetRole",
"iam:CreatePolicyVersion",
"iam:DeletePolicyVersion",
"iam:ListAttachedRolePolicies",
"iam:ListPolicyVersions",
"iam:PutUserPolicy",
"iam:PutGroupPolicy",
"iam:PutRolePolicy",
"iam:SetDefaultPolicyVersion",
"iam:GenerateServiceLastAccessedDetails",
"iam:GetServiceLastAccessedDetails",
"notifications:ListNotificationHubs" // Added to ensure Notifications API does not return 403
```

------

**Topics**
+ [Prerequisites for bulk migrating using the console](#migrate-granularaccess-console-prereq)
+ [Using recommended actions to bulk migrate legacy policies](migrate-console-streamlined.md)
+ [Customizing actions to bulk migrate legacy policies](migrate-console-customized.md)
+ [Rollingback your bulk migration policy changes](migrate-console-rollback.md)
+ [Confirming your migration](#migrate-console-complete)

# Using recommended actions to bulk migrate legacy policies
<a name="migrate-console-streamlined"></a>

You can migrate all of your legacy policies by using the fine-grained actions mapped by AWS. For AWS Organizations, this applies to all legacy policies across all accounts. Once you complete your migration process, the fine-grained actions are effective. You have the option to test the bulk migration process using test accounts before committing your entire organization. For more information, see the following section.

**To migrate all of your policies using fine-grained actions mapped by AWS**

1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/).

1. In the search bar at the top of the page, enter **Bulk Policy Migrator**.

1. On the **Manage new IAM actions** page, choose **Confirm and migrate**.

1. Remain on the **Migration in progress** page until the migration is complete. See the status bar for progress.

1. Once the **Migration in progress** section updates to **Migration successful**, you are redirected to the **Manage new IAM actions** page.

## Testing your bulk migration
<a name="migrate-console-streamlined-test"></a>

You can test the bulk migration from legacy policies to AWS recommended fine-grained actions using test accounts before committing to migrating your entire organization. Once you complete your migration process on your test accounts, the fine-grained actions are applied to your test accounts.

**To use your test accounts for bulk migration**

1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/).

1. In the search bar at the top of the page, enter **Bulk Policy Migrator**.

1. On the **Manage new IAM actions** page, choose **Customize**.

1. Once the accounts and policies load in the **Migrate accounts** table, select one or more test accounts from the list of AWS accounts.

1. (Optional) To change the mapping between your legacy policy and AWS recommended fine-grained actions, choose **View default mapping**. Change the mapping, and choose **Save**.

1. Choose **Confirm and migrate**.

1. Remain on the console page until migration is complete.

# Customizing actions to bulk migrate legacy policies
<a name="migrate-console-customized"></a>

You can customize your bulk migration in various ways, instead of using the AWS recommended action for all of your accounts. You have the option to review any changes needed to your legacy policies before migrating, choose specific accounts in your Organizations to migrate at a time, and change the access range by updating the mapped fine-grained actions.

**To review your affected policies before bulk migrating**

1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/).

1. In the search bar at the top of the page, enter **Bulk Policy Migrator**.

1. On the **Manage new IAM actions** page, choose **Customize**.

1. Once the accounts and policies load in the **Migrate accounts** table, choose the number in the **Number of affected IAM policies** column to see the affected policies. You will also see when that policy was used last to access the Billing and Cost Management consoles.

1. Choose a policy name to open it in the IAM console to view definitions and manually update the policy.
**Notes**  
Doing this might log you out of your current account if the policy is from another member account.
You won't be redirected to the corresponding IAM page if your current account has a bulk migration in progress.

1. (Optional) Choose **View default mapping** to see the legacy policies to understand the fine-grained policy mapped by AWS.

**To migrate a select group of accounts to migrate from your organization**

1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/).

1. In the search bar at the top of the page, enter **Bulk Policy Migrator**.

1. On the **Manage new IAM actions** page, choose **Customize**.

1. Once the accounts and policies load in the **Migrate accounts** table, select one or more accounts to migrate.

1. Choose **Confirm and migrate**.

1. Remain on the console page until migration is complete.

**To change the access range by updating the mapped fine-grained actions**

1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/).

1. In the search bar at the top of the page, enter **Bulk Policy Migrator**.

1. On the **Manage new IAM actions** page, choose **Customize**.

1. Choose **View default mapping**.

1. Choose **Edit**.

1. Add or remove IAM actions for the Billing and Cost Management services you want to control access to. For more information about fine-grained actions and the access it controls, see [Mapping fine-grained IAM actions reference](migrate-granularaccess-iam-mapping-reference.md).

1. Choose **Save changes**.

The updated mapping is used for all future migrations from the account you're logged into. This can be changed at any time.

# Rollingback your bulk migration policy changes
<a name="migrate-console-rollback"></a>

You can rollback all policy changes you make during the bulk migration process safely, using the steps provided in the bulk migration tool. The rollback feature works at an account-level. You can rollback policy updates for all accounts, or specific groups of migrated accounts. However, you can't rollback changes for specific policies in an account.

**To rollback bulk migration changes**

1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/).

1. In the search bar at the top of the page, enter **Bulk Policy Migrator**.

1. On the **Manage new IAM actions** page, choose the **Rollback changes** tab.

1. Select any accounts to rollback. The accounts must have `Migrated` showing in the **Rollback status** column.

1. Choose **Rollback changes** button.

1. Remain on the console page until rollback is complete.

## Confirming your migration
<a name="migrate-console-complete"></a>

You can see if there are any AWS Organizations accounts that still need to migrate by using the migration tool.

**To confirm if all accounts migrated**

1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/).

1. In the search bar at the top of the page, enter **Bulk Policy Migrator**.

1. On the **Manage new IAM actions** page, choose the **Migrate accounts** tab.

All accounts have migrated successfully if the table doesn't show any remaining accounts.

# How to use the affected policies tool
<a name="migrate-security-iam-tool"></a>

**Note**  
The following AWS Identity and Access Management (IAM) actions have reached the end of standard support on July 2023:  
`aws-portal` namespace
`purchase-orders:ViewPurchaseOrders`
`purchase-orders:ModifyPurchaseOrders`
If you're using AWS Organizations, you can use the [bulk policy migrator scripts](migrate-iam-permissions.md) or bulk policy migrator to update polices from your payer account. You can also use the [old to granular action mapping reference](migrate-granularaccess-iam-mapping-reference.md) to verify the IAM actions that need to be added.  
If you have an AWS account, or are a part of an AWS Organizations created on or after March 6, 2023, 11:00 AM (PDT), the fine-grained actions are already in effect in your organization.

You can use the **Affected policies** tool in the Billing console to identify IAM policies (excluding SCPs), and reference the IAM actions affected by this migration. Use the **Affected policies** tool to do the following tasks: 
+ Identify IAM policies and reference the IAM actions affected by this migration
+ Copy the updated policy to your clipboard
+ Open the affected policy in IAM policy editor
+ Save the updated policy for your account
+ Turn on the fine-grained permissions and disable the old actions

This tool operates within the boundaries of the AWS account you're signed into, and information regarding other AWS Organizations accounts are not disclosed.

**To use the Affected policies tool**

1. Sign in to the AWS Management Console and open the AWS Billing and Cost Management console at [https://console.aws.amazon.com/costmanagement/](https://console.aws.amazon.com/costmanagement/).

1. Paste the following URL into your browser to access the **Affected policies** tool: [https://console.aws.amazon.com/poliden/home?region=us-east-1#/](https://console.aws.amazon.com/poliden/home?region=us-east-1#/).
**Note**  
You must have the `iam:GetAccountAuthorizationDetails` permission to view this page.

1. Review the table that lists the affected IAM policies. Use the **Deprecated IAM actions** column to review specific IAM actions referenced in a policy.

1. Under the **Copy updated policy** column, choose **Copy** to copy the updated policy to your clipboard. The updated policy contains the existing policy and the suggested fine-grained actions appended to it as a separate `Sid` block. This block has the prefix `AffectedPoliciesMigrator` at the end of the policy.

1. Under the **Edit Policy in IAM Console** column, choose **Edit** to go to IAM policy editor. You will see the JSON of your existing policy.

1. Replace the entire existing policy with the updated policy that you copied in step 4. You can make any other changes as needed.

1. Choose **Next** and then choose **Save changes**.

1. Repeat steps 3 to 7 for all affected policies.

1. After you update your policies, refresh the **Affected policies** tool to confirm there are no affected policies listed. The **New IAM Actions Found** column should have **Yes** for all policies and the **Copy** and **Edit** buttons will be disabled. Your affected policies are updated.

**To enable fine-grained actions for your account**

After you update your policies, follow this procedure to enable the fine-grained actions for your account.

Only the management account (payer) of an organization or individual accounts can use the **Manage New IAM Actions** section. An individual account can enable the new actions for itself. A management account can enable new actions for the entire organization or a subset of member accounts. If you're a management account, update the affected policies for all member accounts and enable the new actions for your organization. For more information, see the [How to toggle accounts between new fine-grained actions or existing IAM actions?](https://aws.amazon.com/blogs/aws-cloud-financial-management/changes-to-aws-billing-cost-management-and-account-consoles-permissions/#How-to-toggle-accounts-between-new-fine-grained-actions-or-existing-IAM-Actions) section in the AWS blog post. 
**Note**  
To do this, you must have the following permissions:  
`aws-portal:GetConsoleActionSetEnforced`
`aws-portal:UpdateConsoleActionSetEnforced`
`ce:GetConsoleActionSetEnforced`
`ce:UpdateConsoleActionSetEnforced`
`purchase-orders:GetConsoleActionSetEnforced`
`purchase-orders:UpdateConsoleActionSetEnforced`

If you don't see the **Manage New IAM Actions** section, this means your account has already enabled the fine-grained IAM actions.

1. Under **Manage New IAM Actions**, the **Current Action Set Enforced** setting will have the **Existing** status.

   Choose **Enable New actions (Fine Grained)** and then choose **Apply changes**.

1. In the dialog box, choose **Yes**. The **Current Action Set Enforced** status will change to **Fine Grained**. This means the new actions are enforced for your AWS account or for your organization.

1. (Optional) You can then update your existing policies to remove any of the old actions.

**Example: Before and after IAM policy**  
The following IAM policy has the old `aws-portal:ViewPaymentMethods` action.  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "aws-portal:ViewPaymentMethods"
            ],
            "Resource": "*"
        }
    ]
}
```
After you copy the updated policy, the following example has the new `Sid` block with the fine-grained actions.  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "aws-portal:ViewPaymentMethods"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AffectedPoliciesMigrator0",
            "Effect": "Allow",
            "Action": [
                "account:GetAccountInformation",
                "invoicing:GetInvoicePDF",
                "payments:GetPaymentInstrument",
                "payments:GetPaymentStatus",
                "payments:ListPaymentPreferences"
            ],
            "Resource": "*"
        }
    ]
}
```

## Related resources
<a name="related-resources-affected-policies"></a>

For more information, see [Sid](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_sid.html) in the *IAM User Guide*.

For more information about the new fine-grained actions, see the [Mapping fine-grained IAM actions reference](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/migrate-granularaccess-iam-mapping-reference.html) and [Using fine-grained Billing actions](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/migrate-granularaccess-whatis.html#migrate-user-permissions).

# Use scripts to bulk migrate your policies to use fine-grained IAM actions
<a name="migrate-iam-permissions"></a>

**Note**  
The following AWS Identity and Access Management (IAM) actions have reached the end of standard support on July 2023:  
`aws-portal` namespace
`purchase-orders:ViewPurchaseOrders`
`purchase-orders:ModifyPurchaseOrders`
If you're using AWS Organizations, you can use the [bulk policy migrator scripts](#migrate-iam-permissions) or bulk policy migrator to update polices from your payer account. You can also use the [old to granular action mapping reference](migrate-granularaccess-iam-mapping-reference.md) to verify the IAM actions that need to be added.  
If you have an AWS account, or are a part of an AWS Organizations created on or after March 6, 2023, 11:00 AM (PDT), the fine-grained actions are already in effect in your organization.

To help migrate your IAM policies to use new actions, known as fine-grained actions, you can use scripts from the [AWS Samples](https://github.com/aws-samples/bulk-policy-migrator-scripts-for-account-cost-billing-consoles) website. 

You run these scripts from the payer account of your organization to identify the following affected policies in your organization that use the old IAM actions:
+ Customer managed IAM policies
+ Role, group, and user IAM inline policies
+ Service control policies (SCPs) (applies to the payer account only)
+ Permission sets

The scripts generate suggestions for new actions that correspond to existing actions that are used in the policy. You then review the suggestions and use the scripts to add the new actions across all affected policies in your organization. You don't need to update AWS managed policies or AWS managed SCPs (for example, AWS Control Tower and AWS Organizations SCPs).

You use these scripts to: 
+ Streamline the policy updates to help you manage the affected policies from the payer account.
+ Reduce the amount of time that you need to update the policies. You don't need to sign into each member account and manually update the policies.
+ Group identical policies from different member accounts together. You can then review and apply the same updates across all identical policies, instead of reviewing them one by one.
+ Ensure that user access remains unaffected after AWS retires the old IAM actions on July 6, 2023.

For more information about policies and service control policies (SCPs), see the following topics: 
+ [Managing IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html) in the *IAM User Guide*
+ [Service control policies (SCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*
+ [Custom permissions](https://docs.aws.amazon.com/singlesignon/latest/userguide/permissionsetcustom.html) in the *IAM Identity Center User Guide*

## Overview
<a name="overview-bulk-migrate-policies"></a>

Follow this topic to complete the following steps:

**Topics**
+ [Overview](#overview-bulk-migrate-policies)
+ [Prerequisites](#prerequisites-running-the-scripts)
+ [Step 1: Set up your environment](#set-up-your-environment-and-download-the-scripts)
+ [Step 2: Create the CloudFormation StackSet](#create-the-cloudformation-stack)
+ [Step 3: Identify the affected policies](#identify-the-affected-policies)
+ [Step 4: Review the suggested changes](#review-the-affected-policies)
+ [Step 5: Update the affected policies](#update-the-affected-policies)
+ [Step 6: Revert your changes (Optional)](#revert-changes)
+ [IAM policy examples](#examples-of-similar-policies)

## Prerequisites
<a name="prerequisites-running-the-scripts"></a>

To get started, you must do the following:
+ Download and install [Python 3](https://www.python.org/downloads/)
+ Sign in to your payer account and verify that you have an IAM principal that has the following IAM permissions:

  ```
  "iam:GetAccountAuthorizationDetails",
  "iam:GetPolicy",
  "iam:GetPolicyVersion",
  "iam:GetUserPolicy",
  "iam:GetGroupPolicy",
  "iam:GetRole",
  "iam:GetRolePolicy",
  "iam:CreatePolicyVersion",
  "iam:DeletePolicyVersion",
  "iam:ListAttachedRolePolicies",
  "iam:ListPolicyVersions",
  "iam:PutUserPolicy",
  "iam:PutGroupPolicy",
  "iam:PutRolePolicy",
  "iam:SetDefaultPolicyVersion",
  "organizations:ListAccounts",
  "organizations:ListPolicies",
  "organizations:DescribePolicy",
  "organizations:UpdatePolicy",
  "organizations:DescribeOrganization",
  "sso:DescribePermissionSet",
  "sso:DescribePermissionSetProvisioningStatus",
  "sso:GetInlinePolicyForPermissionSet",
  "sso:ListInstances",
  "sso:ListPermissionSets",
  "sso:ProvisionPermissionSet",
  "sso:PutInlinePolicyToPermissionSet",
  "sts:AssumeRole"
  ```

**Tip**  
To get started, we recommend that you use a subset of an account, such as a test account, to verify that the suggested changes are expected.  
You can then run the scripts again for remaining accounts in your organization.

## Step 1: Set up your environment
<a name="set-up-your-environment-and-download-the-scripts"></a>

To get started, download the required files from the [AWS Samples](https://github.com/aws-samples/bulk-policy-migrator-scripts-for-account-cost-billing-consoles) website. You then run commands to set up your environment.

**To set up your environment**

1. Clone the repository from the [AWS Samples](https://github.com/aws-samples/bulk-policy-migrator-scripts-for-account-cost-billing-consoles) website. In a command line window, you can use the following command:

   ```
   git clone https://github.com/aws-samples/bulk-policy-migrator-scripts-for-account-cost-billing-consoles.git
   ```

1. Navigate to the directory where you downloaded the files. You can use the following command:

   ```
   cd bulk-policy-migrator-scripts-for-account-cost-billing-consoles
   ```

   In the repository, you can find the following scripts and resources:
   + `billing_console_policy_migrator_role.json` – The CloudFormation template that creates the `BillingConsolePolicyMigratorRole` IAM role in member accounts of your organization. This role allows the scripts to assume the role, and then read and update the affected policies.
   + `action_mapping_config.json`– Contains the one-to-many mapping of the old actions to the new actions. The scripts use this file to suggest the new actions for each affected policy that contains the old actions. 

     Each old action corresponds to multiple fine-grained actions. The new actions suggested in the file provide users access to the same AWS services before the migration. 
   + `identify_affected_policies.py` – Scans and identifies affected policies in your organization. This script generates a `affected_policies_and_suggestions.json` file that lists the affected policies along with the suggested new actions. 

     Affected policies that use the same set of old actions are grouped together in the JSON file, so that you can review or update the suggested new actions.
   + `update_affected_policies.py` – Updates the affected policies in your organization. The script inputs the`affected_policies_and_suggestions.json` file, and then adds the suggested new actions to the policies.
   + `rollback_affected_policies.py` – (Optional) Reverts changes made to the affected policies. This script removes the new fine-grained actions from the affected policies.

1. Run the following commands to set up and activate the virtual environment.

   ```
   python3 -m venv venv
   ```

   ```
   source venv/bin/activate
   ```

1. Run the following command to install the AWS SDK for Python (Boto3) dependency.

   ```
   pip install -r requirements.txt
   ```
**Note**  
You must configure your AWS credentials to use the AWS Command Line Interface (AWS CLI). For more information, see [AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html).

For more information, see the [README.md](https://github.com/aws-samples/bulk-policy-migrator-scripts-for-account-cost-billing-consoles#readme) file.

## Step 2: Create the CloudFormation StackSet
<a name="create-the-cloudformation-stack"></a>

Follow this procedure to create a CloudFormation *stack set*. This stack set then creates the `BillingConsolePolicyMigratorRole` IAM role for all member accounts in your organization.

**Note**  
You only need to complete this step once from the management account (payer account).

**To create the CloudFormation StackSet**

1. In a text editor, open the `billing_console_policy_migrator_role.json` file, and replace each instance of *`<management_account>`* with the account ID of the payer account (for example, *123456789012*).

1. Save the file.

1. Sign in to the AWS Management Console as the payer account.

1. In the CloudFormation console, create a stack set with the `billing_console_policy_migrator_role.json` file that you updated. 

   For more information, see [ Creating a stack set on the AWS CloudFormation console](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-getting-started-create.html) in the *AWS CloudFormation User Guide*.

After CloudFormation creates the stack set, each member account in your organization has an `BillingConsolePolicyMigratorRole` IAM role. 

The IAM role contains the following permissions:

```
"iam:GetAccountAuthorizationDetails",
"iam:GetPolicy",
"iam:GetPolicyVersion",
"iam:GetUserPolicy",
"iam:GetGroupPolicy",
"iam:GetRolePolicy",
"iam:CreatePolicyVersion",
"iam:DeletePolicyVersion",
"iam:ListPolicyVersions",
"iam:PutUserPolicy",
"iam:PutGroupPolicy",
"iam:PutRolePolicy",
"iam:SetDefaultPolicyVersion"
```

**Notes**  
For each member account, the scripts call the [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API operation to get temporary credentials to assume the `BillingConsolePolicyMigratorRole` IAM role. 
The scripts call the [ListAccounts](https://docs.aws.amazon.com/organizations/latest/APIReference/API_ListAccounts.html) API operation to get all member accounts. 
The scripts also call IAM API operations to perform the read and write permissions to the policies.

## Step 3: Identify the affected policies
<a name="identify-the-affected-policies"></a>

After you create the stack set and downloaded the files, run the `identify_affected_policies.py` script. This script assumes the `BillingConsolePolicyMigratorRole` IAM role for each member account, and then identifies the affected policies.

**To identify the affected policies**

1. Navigate to the directory where you downloaded the scripts.

   ```
   cd policy_migration_scripts/scripts
   ```

1. Run the `identify_affected_policies.py` script. 

You can use the following input parameters: 
+ AWS accounts that you want the script to scan. To specify accounts, use the following input parameters:
  +  `--all` – Scans all member accounts in your organization. 

    ```
    python3 identify_affected_policies.py --all
    ```
  +  `--accounts` – Scans a subset of member accounts in your organization. 

    ```
    python3 identify_affected_policies.py --accounts 111122223333, 444455556666, 777788889999
    ```
  + `--exclude-accounts`– Excludes specific member accounts in your organization. 

    ```
    python3 identify_affected_policies.py --all --exclude-accounts 111111111111, 222222222222, 333333333333
    ```
+ ` –-action-mapping-config-file`– (Optional) Specify the path to the `action_mapping_config.json` file. The script uses this file to generate suggested updates for affected policies. If you don't specify the path, the script uses the `action_mapping_config.json` file in the folder. 

  ```
  python3 identify_affected_policies.py –-action-mapping-config-file c:\Users\username\Desktop\Scripts\action_mapping_config.json –-all
  ```

**Note**  
You can't specify organizational units (OUs) with this script.

After you run the script, it creates two JSON files in a `Affected_Policies_<Timestamp>` folder:
+ `affected_policies_and_suggestions.json`
+ `detailed_affected_policies.json`

**`affected_policies_and_suggestions.json`**  
 Lists the affected policies with the suggested new actions. Affected policies that use the same set of old actions are grouped together in the file.  
This file contains the following sections:  
+ Metadata that provides an overview of the accounts that you specified in the script, including:
  + Accounts scanned and the input parameter used for the `identify_affected_policies.py` script
  + Number of affected accounts
  + Number of affected policies
  + Number of similar policy groups
+ Similar policy groups – Includes the list of accounts and policy details, including the following sections:
  + `ImpactedPolicies` – Specifies which policies are affected and included in the group

     
  + `ImpactedPolicyStatements` – Provides information about the `Sid` blocks that currently use the old actions in the affected policy. This section includes the old actions and IAM elements, such as `Effect`, `Principal`, `NotPrincipal`, `NotAction`, and `Condition`.
+ `SuggestedPolicyStatementsToAppend` – Provides the suggested new actions that are added as new `SID` block. 

  When you update the policies, this block is appended at the end of the policies.

**Example `affected_policies_and_suggestions.json` file**  
This file groups together policies that are similar based on the following criteria:  
+ Same old actions used – Policies that have the same old actions across all `SID` blocks.
+ Matching details – In addition to affected actions, the policies have identical IAM elements,such as:
  + `Effect` (`Allow`/`Deny`)
  + `Principal` (who is allowed or denied access)
  + `NotAction` (what actions are not allowed)
  + `NotPrincipal` (who is explicitly denied access)
  + `Resource` (which AWS resources the policy applies to)
  + `Condition` (any specific conditions under which the policy applies) 
For more information, see [IAM policy examples](#examples-of-similar-policies).

**Example `affected_policies_and_suggestions.json`**  

```
[{
        "AccountsScanned": [
            "111111111111",
            "222222222222"
        ],
        "TotalAffectedAccounts": 2,
        "TotalAffectedPolicies": 2,
        "TotalSimilarPolicyGroups": 2
    },
    {
        "GroupName": "Group1",
        "ImpactedPolicies": [{
                "Account": "111111111111",
                "PolicyType": "UserInlinePolicy",
                "PolicyName": "Inline-Test-Policy-Allow",
                "PolicyIdentifier": "1111111_1-user:Inline-Test-Policy-Allow"
            },
            {
                "Account": "222222222222",
                "PolicyType": "UserInlinePolicy",
                "PolicyName": "Inline-Test-Policy-Allow",
                "PolicyIdentifier": "222222_1-group:Inline-Test-Policy-Allow"
            }
        ],
        "ImpactedPolicyStatements": [
            [{
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "aws-portal:ViewAccounts"
                ],
                "Resource": "*"
            }]
        ],
        "SuggestedPolicyStatementsToAppend": [{
            "Sid": "BillingConsolePolicyMigrator0",
            "Effect": "Allow",
            "Action": [
                "account:GetAccountInformation",
                "account:GetAlternateContact",
                "account:GetChallengeQuestions",
                "account:GetContactInformation",
                "billing:GetContractInformation",
                "billing:GetIAMAccessPreference",
                "billing:GetSellerOfRecord",
                "payments:ListPaymentPreferences"
            ],
            "Resource": "*"
        }]
    },
    {
        "GroupName": "Group2",
        "ImpactedPolicies": [{
                "Account": "111111111111",
                "PolicyType": "UserInlinePolicy",
                "PolicyName": "Inline-Test-Policy-deny",
                "PolicyIdentifier": "1111111_2-user:Inline-Test-Policy-deny"
            },
            {
                "Account": "222222222222",
                "PolicyType": "UserInlinePolicy",
                "PolicyName": "Inline-Test-Policy-deny",
                "PolicyIdentifier": "222222_2-group:Inline-Test-Policy-deny"
            }
        ],
        "ImpactedPolicyStatements": [
            [{
                "Sid": "VisualEditor0",
                "Effect": "deny",
                "Action": [
                    "aws-portal:ModifyAccount"
                ],
                "Resource": "*"
            }]
        ],
        "SuggestedPolicyStatementsToAppend": [{
            "Sid": "BillingConsolePolicyMigrator1",
            "Effect": "Deny",
            "Action": [
                "account:CloseAccount",
                "account:DeleteAlternateContact",
                "account:PutAlternateContact",
                "account:PutChallengeQuestions",
                "account:PutContactInformation",
                "billing:PutContractInformation",
                "billing:UpdateIAMAccessPreference",
                "payments:UpdatePaymentPreferences"
            ],
            "Resource": "*"
        }]
    }
]
```

**`detailed_affected_policies.json`**  
Contains the definition of all affected policies that the `identify_affected_policies.py` script identified for member accounts.  
The file groups similar policies together. You can use this file as reference, so that you can review and manage policy changes without needing to sign in to each member account to review the updates for each policy and account individually.  
You can search the file for the policy name (for example, `YourCustomerManagedReadOnlyAccessBillingUser`) and then review the affected policy definitions.   

**Example: `detailed_affected_policies.json`**  

## Step 4: Review the suggested changes
<a name="review-the-affected-policies"></a>

After the script creates the `affected_policies_and_suggestions.json` file, review it and make any changes.

**To review the affected policies**

1. In a text editor, open the `affected_policies_and_suggestions.json` file.

1. In the `AccountsScanned` section, verify that the number of similar groups identified across the scanned accounts is expected.

1. Review the suggested fine-grained actions that will be added to the affected policies.

1. Update your file as needed and then save it.

### Example 1: Update the `action_mapping_config.json` file
<a name="example-1-update-action-mapping-config-file"></a>

You can update the suggested mappings in the `action_mapping_config.json`. After you update the file, you can rerun the `identify_affected_policies.py` script. This script generates updated suggestions for the affected policies.

You can make multiple versions of the `action_mapping_config.json` file to change the policies for different accounts with different permissions. For example, you might create one file named `action_mapping_config_testing.json` to migrate permissions for your test accounts and `action_mapping_config_production.json` for your production accounts.

### Example 2: Update the `affected_policies_and_suggestions.json` file
<a name="example-2-make-changes-to-affected-policy-groups"></a>

To make changes to the suggested replacements for a specific affected policy group, you can directly edit the suggested replacements section within the `affected_policies_and_suggestions.json` file. 

Any changes that you make in this section are applied to all policies within that specific affected policy group.

### Example 3: Customize a specific policy
<a name="example-3-customize-a-specific-policy"></a>

If you find that a policy within an affected policy group that needs different changes than the suggested updates, you can do the following:
+ Exclude specific accounts from the `identify_affected_policies.py` script. You can then review those excluded accounts separately.
+ Update the affected `Sid` blocks by removing the affected policies and accounts that need different permissions. Create a JSON block that includes only the specific accounts or excludes them from the current update affected policy run. 

  When you rerun the `identify_affected_policies.py` script, only the relevant accounts appear in the updated block. You can then refine the suggested replacements for that specific `Sid` block.

## Step 5: Update the affected policies
<a name="update-the-affected-policies"></a>

After you review and refine the suggested replacements, run the `update_affected_policies.py` script. The script takes the `affected_policies_and_suggestions.json` file as input. This script assumes the `BillingConsolePolicyMigratorRole` IAM role to update the affected policies listed in the `affected_policies_and_suggestions.json` file. 

**To update the affected policies**

1. If you haven't already, open a command line window for the AWS CLI.

1. Enter the following command to run the `update_affected_policies.py` script. You can enter the following input parameter:
+ The directory path of the `affected_policies_and_suggestions.json` file that contains a list of the affected policies to be updated. This file is an output of the previous step.

```
python3 update_affected_policies.py --affected-policies-directory Affected_Policies_<Timestamp>
```

The `update_affected_policies.py` script updates the affected policies within the `affected_policies_and_suggestions.json` file with the suggested new actions. The script adds a `Sid` block to the policies, identified as `BillingConsolePolicyMigrator#`, where *\$1* corresponds to an incremental counter (for example, 1, 2, 3). 

For example, if there are multiple `Sid` blocks in the affected policy that use old actions, the script adds multiple `Sid` blocks that appear as `BillingConsolePolicyMigrator#` to correspond to each `Sid` block.

**Important**  
The script doesn't remove old IAM actions from the policies, and or change existing `Sid` blocks in the policies. Instead, it creates `Sid` blocks and appends them to the end of the policy. These new `Sid` blocks have the suggested new actions from the JSON file. This ensures that the permissions of the original policies aren't changed.
We recommend that you do not change the name of the `BillingConsolePolicyMigrator#` `Sid` blocks in case you need to revert your changes.

**Example: Policy with appended `Sid` blocks**  
See the appended `Sid` blocks in the `BillingConsolePolicyMigrator1` and `BillingConsolePolicyMigrator2` blocks.

The script generates a status report that contains unsuccessful operations and outputs the JSON file locally.

**Example: Status report**  

```
[{
    "Account": "111111111111",
    "PolicyType": "Customer Managed Policy"
    "PolicyName": "AwsPortalViewPaymentMethods",
    "PolicyIdentifier": "identifier",
    "Status": "FAILURE", // FAILURE or SKIPPED	
    "ErrorMessage": "Error message details"
}]
```

**Important**  
If you re-run the `identify_affected_policies.py` and `update_affected_policies.py` scripts , they skip all policies that contain the `BillingConsolePolicyMigratorRole#``Sid` block. The scripts assume that those policies were previously scanned and updated, and that they don't require additional updates. This prevents the script from duplicating the same actions in the policy.
After you update the affected policies, you can use the new IAM by using the affected policies tool. If you identify any issues, you can use the tool to switch back to the previous actions. You can also use a script to revert your policy updates.  
For more information, see [How to use the affected policies tool](migrate-security-iam-tool.md) and the [Changes to AWS Billing, Cost Management, and Account Consoles Permissions](https://aws.amazon.com/blogs/aws-cloud-financial-management/changes-to-aws-billing-cost-management-and-account-consoles-permissions/) blog post.
To manage your updates, you can:  
Run the scripts for each account individually.
Run the script in batches for similar accounts, such as testing, QA, and production accounts.
Run the script for all accounts.
Choose a mix between updating some accounts in batches, and then updating others individually.

## Step 6: Revert your changes (Optional)
<a name="revert-changes"></a>

The `rollback_affected_policies.py` script reverts the changes applied to each affected policy for the specified accounts. The script removes all `Sid` blocks that the `update_affected_policies.py` script appended. These `Sid` blocks have the `BillingConsolePolicyMigratorRole#` format.

**To revert your changes**

1. If you haven't already, open a command line window for the AWS CLI.

1. Enter the following command to run the `rollback_affected_policies.py` script. You can enter the following input parameters:
+ `--accounts` 
  + Specifies a comma-separated list of the AWS account IDs that you want to include in the rollback. 
  + The following example scans the policies in the specified AWS accounts, and removes any statements with the `BillingConsolePolicyMigrator#` `Sid` block. 

    ```
    python3 rollback_affected_policies.py –-accounts 111122223333, 555555555555, 666666666666
    ```
+ `--all`
  + Includes all AWS account IDs in your organization. 
  + The following example scans all policies in your organization, and removes any statements with the `BillingConsolePolicyMigratorRole#` `Sid` block.

  ```
  python3 rollback_affected_policies.py –-all
  ```
+ `--exclude-accounts`
  + Specifies a comma-separated list of the AWS account IDs that you want to exclude from the rollback. 

    You can use this parameter only when you also specify the `--all` parameter. 
  + The following example scans the policies for all AWS accounts in your organization, except for the specified accounts.

    ```
    python3 rollback_affected_policies.py --all --exclude-accounts 777777777777, 888888888888, 999999999999
    ```

## IAM policy examples
<a name="examples-of-similar-policies"></a>

Policies are considered similar if they have identical: 
+  Affected actions across all `Sid` blocks. 
+  Details in the following IAM elements:
  + `Effect` (`Allow`/`Deny`)
  + `Principal` (who is allowed or denied access)
  + `NotAction` (what actions are not allowed)
  + `NotPrincipal` (who is explicitly denied access)
  + `Resource` (which AWS resources the policy applies to)
  + `Condition` (any specific conditions under which the policy applies)

The following examples show policies which IAM might or might not consider similar based on the differences between them. 

**Example 1: Policies are considered similar**  
Each policy type is different, but both policies contain one `Sid` block with the same affected `Action`.     
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "aws-portal:ViewAccount",
            "aws-portal:*Billing"
        ],
        "Resource": "*"
    }]
}
```  
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "aws-portal:ViewAccount",
            "aws-portal:*Billing"
        ],
        "Resource": "*"
    }]
}
```

**Example 2: Policies are considered similar**  
Both policies contain one `Sid` block with the same affected `Action`. Policy 2 contains additional actions, but these actions aren't affected.    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "aws-portal:ViewAccount",
            "aws-portal:*Billing"
        ],
        "Resource": "*"
    }]
}
```  
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "aws-portal:ViewAccount",
            "aws-portal:*Billing",
            "athena:*"
        ],
        "Resource": "*"
    }]
}
```

**Example 3: Policies aren't considered similar**  
Both policies contain one `Sid` block with the same affected `Action`. However, policy 2 contains a `Condition` element that isn't present in policy 1.    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "aws-portal:ViewAccount",
            "aws-portal:*Billing"
        ],
        "Resource": "*"
    }]
}
```  
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "aws-portal:ViewAccount",
            "aws-portal:*Billing",
            "athena:*"
        ],
        "Resource": "*",
        "Condition": {
            "BoolIfExists": {
                "aws:MultiFactorAuthPresent": "true"
            }
        }
    }]
}
```

**Example 4: Policies are considered similar**  
Policy 1 has a single `Sid` block with an affected `Action`. Policy 2 has multiple `Sid` blocks, but the affected `Action` appears in only one block.    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "aws-portal:View*"
        ],
        "Resource": "*"
    }]
}
```  
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "aws-portal:View*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "cloudtrail:Get*"
            ],
            "Resource": "*"
        }
    ]
}
```

**Example 5: Policies aren't considered similar**  
Policy 1 has a single `Sid` block with an affected `Action`. Policy 2 has multiple `Sid` blocks, and the affected `Action` appears in multiple blocks.    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "aws-portal:View*"
        ],
        "Resource": "*"
    }]
}
```  
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "aws-portal:View*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Deny",
            "Action": [
                "aws-portal:Modify*"
            ],
            "Resource": "*"
        }
    ]
}
```

**Example 6: Policies are considered similar**  
Both policies have multiple `Sid` blocks, with the same affected `Action` in each `Sid` block.    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "aws-portal:*Account",
                "iam:Get*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Deny",
            "Action": [
                "aws-portal:Modify*",
                "iam:Update*"
            ],
            "Resource": "*"
        }
    ]
}
```  
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "aws-portal:*Account",
                "athena:Get*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Deny",
            "Action": [
                "aws-portal:Modify*",
                "athena:Update*"
            ],
            "Resource": "*"
        }
    ]
}
```

**Example 7**  
The following two policies aren't considered similar.  
Policy 1 has a single `Sid` block with an affected `Action`. Policy 2 has a `Sid` block with the same affected `Action`. However, policy 2 also contains another `Sid` block with different actions.     
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "aws-portal:*Account",
                "iam:Get*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Deny",
            "Action": [
                "aws-portal:Modify*",
                "iam:Update*"
            ],
            "Resource": "*"
        }
    ]
}
```  
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [{
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "aws-portal:*Account",
                "athena:Get*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Deny",
            "Action": [
                "aws-portal:*Billing",
                "athena:Update*"
            ],
            "Resource": "*"
        }
    ]
}
```

# Mapping fine-grained IAM actions reference
<a name="migrate-granularaccess-iam-mapping-reference"></a>

**Note**  
The following AWS Identity and Access Management (IAM) actions have reached the end of standard support on July 2023:  
`aws-portal` namespace
`purchase-orders:ViewPurchaseOrders`
`purchase-orders:ModifyPurchaseOrders`
If you're using AWS Organizations, you can use the [bulk policy migrator scripts](migrate-iam-permissions.md) or bulk policy migrator to update polices from your payer account. You can also use the [old to granular action mapping reference](#migrate-granularaccess-iam-mapping-reference) to verify the IAM actions that need to be added.  
If you have an AWS account, or are a part of an AWS Organizations created on or after March 6, 2023, 11:00 AM (PDT), the fine-grained actions are already in effect in your organization.

You will need to migrate the following IAM actions in your permission policies or service control policies (SCP):
+ `aws-portal:ViewAccount`
+  `aws-portal:ViewBilling`
+ `aws-portal:ViewPaymentMethods`
+  `aws-portal:ViewUsage` 
+  `aws-portal:ModifyAccount`
+  `aws-portal:ModifyBilling`
+  `aws-portal:ModifyPaymentMethods` 
+ `purchase-orders:ViewPurchaseOrders` 
+ `purchase-orders:ModifyPurchaseOrders` 

You can use this topic to view the mapping of the old to new fine-grained actions for each IAM action that we're retiring.

**Overview**

1. Review your affected IAM policies in your AWS account. To do so, follow the steps in the **Affected policies** tool to identify your affected IAM policies. See [How to use the affected policies tool](migrate-security-iam-tool.md).

1. Use the IAM console to add the new granular permissions to your policy. For example, if your policy allows the `purchase-orders:ModifyPurchaseOrders` permission, you will need to add each action in the [Mapping for purchase-orders:ModifyPurchaseOrders](#mapping-for-purchase-ordersmodifypurchaseorders) table. 

   **Old policy**

   The following policy allows a user to add, delete, or modify any purchase order in the account.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": "purchase-orders:ModifyPurchaseOrders",
               "Resource": "arn:aws:purchase-orders::123456789012:purchase-order/*"
           }
       ]
   }
   ```

------

   **New policy**

   The following policy also allows a user to add, delete, or modify any purchase order in the account. Note that each granular permission appears after the old `purchase-orders:ModifyPurchaseOrders` permission. These permissions give you more control over what actions you want to allow or deny.
**Tip**  
We recommend that you keep the old permissions to ensure that you don't lose permissions until this migration is complete.

------
#### [ JSON ]

****  

   ```
   {
   	"Version":"2012-10-17",		 	 	 
   	"Statement": [
   		{
   			"Sid": "VisualEditor0",
   			"Effect": "Allow",
   			"Action": [
   				"purchase-orders:ModifyPurchaseOrders",
   				"purchase-orders:AddPurchaseOrder",
   				"purchase-orders:DeletePurchaseOrder",
   				"purchase-orders:UpdatePurchaseOrder",
   				"purchase-orders:UpdatePurchaseOrderStatus"
   			],
   			"Resource": "arn:aws:purchase-orders::123456789012:purchase-order/*"
   		}
   	]
   }
   ```

------

1. Save your changes.

**Notes**  
To edit policies manually in the IAM console, see [Editing customer managed policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-edit.html#edit-inline-policy-console) in the *IAM User Guide*.
To bulk migrate your IAM policies to use fine-grained actions (new actions), see [Use scripts to bulk migrate your policies to use fine-grained IAM actions](migrate-iam-permissions.md).

**Contents**
+ [Mapping for aws-portal:ViewAccount](#mapping-for-aws-portalviewaccount)
+ [Mapping for aws-portal:ViewBilling](#mapping-for-aws-portalviewbilling)
+ [Mapping for aws-portal:ViewPaymentMethods](#mapping-for-aws-portalviewpaymentmethods)
+ [Mapping for aws-portal:ViewUsage](#mapping-for-aws-portalviewusage)
+ [Mapping for aws-portal:ModifyAccount](#mapping-for-aws-portalmodifyaccount)
+ [Mapping for aws-portal:ModifyBilling](#mapping-for-aws-portalmodifybilling)
+ [Mapping for aws-portal:ModifyPaymentMethods](#mapping-for-aws-portalmodifypaymentmethods)
+ [Mapping for purchase-orders:ViewPurchaseOrders](#mapping-for-purchase-ordersviewpurchaseorders)
+ [Mapping for purchase-orders:ModifyPurchaseOrders](#mapping-for-purchase-ordersmodifypurchaseorders)

## Mapping for aws-portal:ViewAccount
<a name="mapping-for-aws-portalviewaccount"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  account:GetAccountInformation |  Grants permission to retrieve the account information for an account  |  Read  | 
|  account:GetAlternateContact  |  Grants permission to retrieve the alternate contacts for an account  |  Read  | 
|  account:GetContactInformation  |  Grants permission to retrieve the primary contact information for an account  |  Read  | 
|  billing:GetContractInformation  |  Grants permission to view the account's contract information including the contract number, end-user organization names, purchase order numbers, and if the account is used to service public-sector customers |  Read  | 
|  billing:GetIAMAccessPreference  |  Grants permission to retrieve the state of the Allow IAM Access billing preference |  Read  | 
|  billing:GetSellerOfRecord  |  Grants permission to retrieve the account's default seller of record |  Read  | 
|  payments:ListPaymentPreferences  |  Grants permission to get payment preferences (for example, preferred payment currency, preferred payment method)  |  Read  | 

## Mapping for aws-portal:ViewBilling
<a name="mapping-for-aws-portalviewbilling"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  account:GetAccountInformation  |  Grants permission to retrieve the account information for an account  |  Read  | 
|  billing:GetBillingData |  Grants permission to perform queries on billing information  |  Read  | 
|  billing:GetBillingDetails |  Grants permission to view detailed line item billing information  |  Read  | 
|  billing:GetBillingNotifications  |  Grants permission to view notifications sent by AWS related to your accounts billing information  |  Read  | 
|  billing:GetBillingPreferences |  Grants permission to view billing preferences such as Reserved Instances, Savings Plans, and credits sharing  |  Read  | 
|  billing:GetContractInformation |  Grants permission to view the account's contract information including the contract number, end-user organization names, purchase order numbers, and if the account is used to service public-sector customers  |  Read  | 
|  billing:GetCredits  |  Grants permission to view credits that have been redeemed  |  Read  | 
|  billing:GetIAMAccessPreference |  Grants permission to retrieve the state of the Allow IAM Access billing preference |  Read  | 
|  billing:GetSellerOfRecord |  Grants permission to retrieve the account's default seller of record  |  Read  | 
|  billing:ListBillingViews |  Grants permission to get billing information for your proforma billing groups |  List  | 
|  ce:DescribeNotificationSubscription |  Grants permission to view reservation expiration alerts  |  Read  | 
|  ce:DescribeReport  |  Grants permission to view Cost Explorer reports page  |  Read  | 
|  ce:GetAnomalies |  Grants permission to retrieve anomalies  |  Read  | 
|  ce:GetAnomalyMonitors  |  Grants permission to query anomaly monitors  |  Read  | 
|  ce:GetAnomalySubscriptions |  Grants permission to query anomaly subscriptions  |  Read  | 
|  ce:GetCostAndUsage  |  Grants permission to retrieve the cost and usage metrics for your account  |  Read  | 
|  ce:GetCostAndUsageWithResources  |  Grants permission to retrieve the cost and usage metrics with resources for your account  |  Read  | 
|  ce:GetCostCategories  |  Grants permission to query cost category names and values for a specified time period  |  Read  | 
|  ce:GetCostForecast |  Grants permission to retrieve a cost forecast for a forecast time period  |  Read  | 
|  ce:GetDimensionValues  |  Grants permission to retrieve all available filter values for a filter for a period of time  |  Read  | 
|  ce:GetPreferences |  Grants permission to view the Cost Explorer preferences page  |  Read  | 
|  ce:GetReservationCoverage  |  Grants permission to retrieve the reservation coverage for your account  |  Read  | 
|  ce:GetReservationPurchaseRecommendation |  Grants permission to retrieve the reservation recommendations for your account  |  Read  | 
|  ce:GetReservationUtilization  |  Grants permission to retrieve the reservation utilization for your account  |  Read  | 
|  ce:GetRightsizingRecommendation  |  Grants permission to retrieve the rightsizing recommendations for your account  |  Read  | 
|  ce:GetSavingsPlansCoverage  |  Grants permission to retrieve the Savings Plans coverage for your account  |  Read  | 
| ce:GetSavingsPlansPurchaseRecommendation  |  Grants permission to retrieve the Savings Plans recommendations for your account  |  Read  | 
|  ce:GetSavingsPlansUtilization  |  Grants permission to retrieve the Savings Plans utilization for your account  |  Read  | 
|  ce:GetSavingsPlansUtilizationDetails  |  Grants permission to retrieve the Savings Plans utilization details for your account  |  Read  | 
|  ce:GetTags  |  Grants permission to query tags for a specified time period  |  Read  | 
|  ce:GetUsageForecast  |  Grants permission to retrieve a usage forecast for a forecast time period  |  Read  | 
|  ce:ListCostAllocationTags  |  Grants permission to list cost allocation tags  |  List  | 
|  ce:ListSavingsPlansPurchaseRecommendationGeneration  |  Grants permission to retrieve a list of your historical recommendation generations  |  Read  | 
|  consolidatedbilling:GetAccountBillingRole  |  Grants permission to get account role (payer, linked, regular)  |  Read  | 
|  consolidatedbilling:ListLinkedAccounts  |  Grants permission to get list of member and linked accounts  |  List  | 
|  cur:GetClassicReport  |  Grants permission to get the CSV report for your bill |  Read  | 
|  cur:GetClassicReportPreferences  |  Grants permission to get the classic report enablement status for usage reports |  Read  | 
|  cur:ValidateReportDestination  |  Grants permission to validates if the Amazon S3 bucket exists with appropriate permissions for AWS CUR delivery  |  Read  | 
|  freetier:GetFreeTierAlertPreference  |  Grants permission to get AWS Free Tier alert preference (by email address)  |  Read  | 
|  freetier:GetFreeTierUsage  | Grants permission to get AWS Free Tier usage limits and month-to-date (MTD) usage status  |  Read  | 
|  invoicing:GetInvoiceEmailDeliveryPreferences  |  Grants permission to get invoice email delivery preferences  |  Read  | 
|  invoicing:GetInvoicePDF  |  Grants permission to get the invoice PDF  |  Read  | 
|  invoicing:ListInvoiceSummaries  |  Grants permission to get invoice summary information for your account or linked account  |  List  | 
|  payments:GetPaymentInstrument  |  Grants permission to get information about a payment instrument  |  Read  | 
|  payments:GetPaymentStatus  |  Grants permission to get payment status of invoices  |  Read  | 
|  payments:ListPaymentPreferences  |  Grants permission to get payment preferences (for example, preferred payment currency, preferred payment method)  |  Read  | 
|  tax:GetTaxInheritance  |  Grants permission to view tax inheritance status  |  Read  | 
|  tax:GetTaxRegistrationDocument  |  Grants permission to download tax registration documents  |  Read  | 
|  tax:ListTaxRegistrations  |  Grants permission to view tax registration  |  Read  | 

## Mapping for aws-portal:ViewPaymentMethods
<a name="mapping-for-aws-portalviewpaymentmethods"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  account:GetAccountInformation  |  Grants permission to retrieve the account information for an account  |  Read  | 
|  invoicing:GetInvoicePDF  |  Grants permission to get the invoice PDF  |  Read  | 
|  payments:GetPaymentInstrument  |  Grants permission to get information about a payment instrument  |  Read  | 
|  payments:GetPaymentStatus  |  Grants permission to get payment status of invoices  |  Read  | 
|  payments:ListPaymentPreferences  |  Grants permission to get payment preferences (for example, preferred payment currency, preferred payment method)  |  List  | 

## Mapping for aws-portal:ViewUsage
<a name="mapping-for-aws-portalviewusage"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  cur:GetUsageReport  | Grants permission to get a list of AWS services, the usage type and operation for the usage report workflow, and to download usage reports  |  Read  | 

## Mapping for aws-portal:ModifyAccount
<a name="mapping-for-aws-portalmodifyaccount"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  account:CloseAccount  |  Grants permission to close an account  |  Write  | 
|  account:DeleteAlternateContact  |  Grants permission to delete the alternate contacts for an account  |  Write  | 
|  account:PutAlternateContact  |  Grants permission to modify the alternate contacts for an account  |  Write  | 
|  account:PutChallengeQuestions  |  Grants permission to modify the challenge questions for an account  |  Write  | 
|  account:PutContactInformation  | Grants permission to update the primary contact information for an account  |  Write  | 
|  billing:PutContractInformation  |  Grants permission to set the account's contract information end-user organization names and if the account is used to service public-sector customers  |  Write  | 
|  billing:UpdateIAMAccessPreference  |  Grants permission to update the Allow IAM Access billing preference |  Write  | 
|  payments:UpdatePaymentPreferences  |  Grants permission to update payment preferences (for example, preferred payment currency, preferred payment method)  |  Write  | 

## Mapping for aws-portal:ModifyBilling
<a name="mapping-for-aws-portalmodifybilling"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  billing:PutContractInformation  |  Grants permission to set the account's contract information end-user organization names and if the account is used to service public-sector customers  |  Write  | 
|  billing:RedeemCredits  |  Grants permission to redeem an AWS credit  |  Write  | 
|  billing:UpdateBillingPreferences  |  Grants permission to update billing preferences such as Reserved Instances, Savings Plans, and credits sharing  |  Write  | 
|  ce:CreateAnomalyMonitor  |  Grants permission to create a new anomaly monitor  |  Write  | 
|  ce:CreateAnomalySubscription  |  Grants permission to create a new anomaly subscription  |  Write  | 
|  ce:CreateNotificationSubscription  |  Grants permission to create reservation expiration alerts  |  Write  | 
|  ce:CreateReport  |  Grants permission to create Cost Explorer reports  |  Write  | 
|  ce:DeleteAnomalyMonitor  |  Grants permission to delete an anomaly monitor  |  Write  | 
|  ce:DeleteAnomalySubscription  |  Grants permission to delete an anomaly subscription  |  Write  | 
|  ce:DeleteNotificationSubscription  |  Grants permission to delete reservation expiration alerts  |  Write  | 
|  ce:DeleteReport  |  Grants permission to delete Cost Explorer reports  |  Write  | 
|  ce:ProvideAnomalyFeedback  |  Grants permission to provide feedback on detected anomalies  |  Write  | 
|  ce:StartSavingsPlansPurchaseRecommendationGeneration  |  Grants permission to request a Savings Plans recommendation generation  |  Write  | 
|  ce:UpdateAnomalyMonitor  |  Grants permission to update an existing anomaly monitor  |  Write  | 
|  ce:UpdateAnomalySubscription  |  Grants permission to update an existing anomaly subscription  |  Write  | 
|  ce:UpdateCostAllocationTagsStatus  |  Grants permission to update existing cost allocation tags status  |  Write  | 
|  ce:UpdateNotificationSubscription  |  Grants permission to update reservation expiration alerts  |  Write  | 
|  ce:UpdatePreferences  |  Grants permission to edit the Cost Explorer preferences page  |  Write  | 
|  cur:PutClassicReportPreferences  |  Grants permission to enable classic reports  |  Write  | 
|  freetier:PutFreeTierAlertPreference  | Grants permission to set AWS Free Tier alert preference (by email address)  |  Write  | 
|  invoicing:PutInvoiceEmailDeliveryPreferences  |  Grants permission to update invoice email delivery preferences  |  Write  | 
|  payments:CreatePaymentInstrument  |  Grants permission to create a payment instrument  |  Write  | 
|  payments:DeletePaymentInstrument  |  Grants permission to delete a payment instrument  |  Write  | 
|  payments:MakePayment  |  Grants permission to make a payment, authenticate a payment, verify a payment method, and generate a funding request document for Advance Pay  |  Write  | 
|  payments:UpdatePaymentPreferences  |  Grants permission to update payment preferences (for example, preferred payment currency, preferred payment method) |  Write  | 
|  tax:BatchPutTaxRegistration  |  Grants permission to batch update tax registrations  |  Write  | 
|  tax:DeleteTaxRegistration  |  Grants permission to delete tax registration data  |  Write  | 
|  tax:PutTaxInheritance  |  Grants permission to set tax inheritance  |  Write  | 

## Mapping for aws-portal:ModifyPaymentMethods
<a name="mapping-for-aws-portalmodifypaymentmethods"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  account:GetAccountInformation  |  Grants permission to retrieve the account information for an account  |  Read  | 
|  payments:DeletePaymentInstrument  |  Grants permission to delete a payment instrument  |  Write  | 
|  payments:CreatePaymentInstrument  |  Grants permission to create a payment instrument  |  Write  | 
|  payments:MakePayment  |  Grants permission to make a payment, authenticate a payment, verify a payment method, and generate a funding request document for Advance Pay  |  Write  | 
|  payments:UpdatePaymentPreferences  |  Grants permission to update payment preferences (for example, preferred payment currency, preferred payment method)  |  Write  | 

## Mapping for purchase-orders:ViewPurchaseOrders
<a name="mapping-for-purchase-ordersviewpurchaseorders"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  invoicing:GetInvoicePDF  |  Grants permission to get invoice PDF  |  Get  | 
|  payments:ListPaymentPreferences  |  Grants permission to get payment preferences (for example, preferred payment currency, preferred payment method)  |  List  | 
|  purchase-orders:GetPurchaseOrder  | Grants permission to get a purchase order  |  Read  | 
|  purchase-orders:ListPurchaseOrderInvoices | Grants permission to view purchase orders and details  |  List  | 
|  purchase-orders:ListPurchaseOrders  |  Grants permission to get all available purchase orders  |  List  | 

## Mapping for purchase-orders:ModifyPurchaseOrders
<a name="mapping-for-purchase-ordersmodifypurchaseorders"></a>


|  New action  |  Description  |  Access level  | 
| --- | --- | --- | 
|  purchase-orders:AddPurchaseOrder |  Grants permission to add a purchase order  |  Write  | 
| purchase-orders:DeletePurchaseOrder  |  Grants permission to delete a purchase order.  |  Write  | 
| purchase-orders:UpdatePurchaseOrder  |  Grants permission to update an existing purchase order  |  Write  | 
| purchase-orders:UpdatePurchaseOrderStatus  | Grants permission to set purchase order status  |  Write  |