export const meta = {
  title: `Override Amplify-generated project-level IAM roles`,
  description: `The "amplify override project" command generates a developer-configurable "overrides" TypeScript file which provides Amplify-generated IAM roles for authenticated and unauthenticated as CDK constructs. For example, developers can run "amplify override project" to change the authenticated and unauthenticated IAM role names to comply with organization-specific naming conventions.`,
};

```bash
amplify override project
```

Run the command above to override Amplify-generated project-level resources, such as IAM roles for authenticated and unauthenticated.

<Callout warning>

**Warning:** Due to the deep dependencies on the authenticated and unauthenticated user roles, it is recommended to ONLY modify these resources at the beginning of your project, when no other resources are added yet.
</Callout>

The command creates a new `overrides.ts` file under `amplify/backend/awscloudformation/` which provides you the Amplify-generated resources as [CDK constructs](https://docs.aws.amazon.com/cdk/latest/guide/home.html).

Apply all the overrides in the `override(...)` function. For example to rename and add a path for authenticated users' IAM role:
```ts
import { AmplifyRootStackTemplate } from '@aws-amplify/cli-extensibility-helper';

export function override(resources: AmplifyRootStackTemplate) {
  resources.authRole.roleName = "myCustomName"
  resources.authRole.path = "/<my-organization>/"
  // Note: CloudFormation limits you from updating the path if you don't recreate the resource.
  // Changing the role name will recreate the resource.
}
```

You can override the following project-level resources that Amplify generates:

|Amplify-generated resource|Description|
|-|-|
|[authRole](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html)|The IAM role for authenticated access to your app backend|
|[unauthRole](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html)|The IAM role for authenticated or guest access to your app backend|


## Example: Modify authRole's IAM policies

For example, use `amplify override project` to further modify the authRole policy for Geo category beyond the default policy statements:

```ts
import { AmplifyRootStackTemplate } from "@aws-amplify/cli-extensibility-helper";

export function override(resources: AmplifyRootStackTemplate) {
  const authRole = resources.authRole;

  const basePolicies = Array.isArray(authRole.policies)
    ? authRole.policies
    : [authRole.policies];

  authRole.policies = [
    ...basePolicies,
    {
      policyName: "amplify-permissions-custom-resources",
      policyDocument: {
        Version: "2012-10-17",
        Statement: [
          //? Route calculator
          {
            Resource: "<ARN of Geo>",
            Action: ["geo:CalculateRoute*"],
            Effect: "Allow",
          },
        ],
      },
    },
  ];
}

```