# AWS Resilience Hub access permissions reference You can use AWS Identity and Access Management (IAM) to manage access to the application resources and create IAM policies that apply to users, groups, or roles. Every AWS Resilience Hub application can be configured to use the [Invoker role](security-iam-resilience-hub-invoker-role.md) (an IAM role), or use the current IAM user permissions (along with a set of predefined roles for cross-account and scheduled assessment). In this role, you can attach a policy that defines the permissions required by AWS Resilience Hub to access other AWS resources or application resources. The invoker role must have a trust policy that is added to AWS Resilience Hub Service Principal. To manage permissions for your application, we recommend using [AWS managed policies for AWS Resilience Hub](security-iam-awsmanpol.md). You can use these managed policies without any modifications, or you can use them as a starting point to write your own restrictive policies. Policies can restrict user permissions at the resource level for different actions by using additional optional conditions. If your application resources are in different accounts (secondary/resource accounts), you must setup a new role in each account that contains your application resources. **Note** If you define VPC endpoints for your workload resources, ensure that the VPC endpoint policies provide read-only access to AWS Resilience Hub for accessing the resources. For more information, see [Control access to VPC endpoints using endpoint policies](https://docs.aws.amazon.com//vpc/latest/privatelink/vpc-endpoints-access.html). **Topics** + [Using IAM role](security-iam-resilience-hub-using-iam-role.md) + [Using current IAM user permissions](security-iam-resilience-hub-current-user-permissions.md) # Using IAM role AWS Resilience Hub will use a predefined existing IAM role to access your resources in the primary account or secondary/resources account. This is the recommended permission option to access your resources. **Topics** + [Invoker role](security-iam-resilience-hub-invoker-role.md) + [Roles in different AWS account for cross-account access - optional](security-iam-resilience-cross-account-roles.md) # Invoker role The AWS Resilience Hub invoker role is an AWS Identity and Access Management (IAM) role that AWS Resilience Hub assumes to access AWS services and resources. For example, you might create an invoker role that has permission to access your CFN template and the resource it creates. This page provides information on how to create, view, and manage an application invoker role. When you create an application, you provide an invoker role. AWS Resilience Hub assumes this role to access your resources when you import resources or start an assessment. For AWS Resilience Hub to properly assume your invoker role, the role's trust policy must specify the AWS Resilience Hub service principal (**resiliencehub.amazonaws.com**) as a trusted service. To view the application's invoker role, choose **Applications** from the navigation pane, and then choose **Update permissions** from **Actions** menu in the **Application** page. You can add or remove permissions from an application invoker role at any time, or configure your application to use a different role for accessing application resources. **Topics** + [Creating an invoker role in the IAM console](#security-iam-resilience-hub-create-invoker-role) + [Managing roles with the IAM API](#security-iam-resilience-hub-manage-roles-with-IAM-API) + [Defining trust policy using JSON file](#security-iam-resilience-define-policy) ## Creating an invoker role in the IAM console To enable AWS Resilience Hub to access AWS services and resources, you must create an invoker role in the primary account using the IAM console. For more information about creating roles using IAM console, see [Creating a role for an AWS service (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console). **To create an invoker role in the primary account using IAM console** 1. Open the IAM console at `https://console.aws.amazon.com/iam/`. 1. From the navigation pane, choose **Roles** and then choose **Create role**. 1. Select **Custom Trust Policy**, copy the following policy in the **Custom trust policy** window, and then choose **Next**. **Note** If your resources are in different accounts, you have to create a role in each of those accounts, and use the secondary account trust policy for the other accounts. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "resiliencehub.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 1. In the **Permissions policies** section of **Add permissions** page, enter `AWSResilienceHubAsssessmentExecutionPolicy` in the **Filter policies by property or policy name and press enter** box. 1. Select the policy and choose **Next**. 1. In **Role details** section, enter a unique role name (such as `AWSResilienceHubAssessmentRole`) in the **Role name** box. This field accepts only alphanumeric and '`+=,.@-_/`' characters. 1. (Optional) Enter a description about the role in the **Description** box. 1. Choose **Create Role**. To edit the use cases and permissions, in step 6, choose **Edit** button that is located to the right of **Step 1: Select trusted entities** or **Step 2: Add permissions** sections. After creating the invoker role and the resource role (if applicable), you can configure your application to use these roles. **Note** You must have an `iam:passRole` permission in your current IAM user/role to the invoker role when creating or updating the application. However, you do not need this permission to run an assessment. ## Managing roles with the IAM API A role's trust policy gives the specified principal's permission to assume the role. To create the roles using AWS Command Line Interface (AWS CLI), use the `create-role` command. While using this command, you can specify the trust policy inline. The following example shows how to grant the AWS Resilience Hub service the principal permission to assume your role. **Note** The requirement to escape quotes (`' '`) in the JSON string may vary based on your shell version. **Sample `create-role`** ``` aws iam create-role --role-name AWSResilienceHubAssessmentRole --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": {"Service": "resiliencehub.amazonaws.com"}, "Action": "sts:AssumeRole" } ] }' ``` ## Defining trust policy using JSON file You can define the trust policy for the role using a separate JSON file and then run the `create-role` command. In the following example, **`trust-policy.json`** is a file that contains the trust policy in the current directory. This policy is attached to a role by running **`create-role`** command. The output of the `create-role` command is shown in the **Sample Output**. To add permissions to the role, use the **attach-policy-to-role** command and you can start by adding the `AWSResilienceHubAsssessmentExecutionPolicy` managed policy. For more information about this managed policy, see [AWSResilienceHubAsssessmentExecutionPolicy](security-iam-awsmanpol.md#security_iam_aws-assessment-policy). **Sample `trust-policy.json`** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Service": "resiliencehub.amazonaws.com" }, "Action": "sts:AssumeRole" }] } ``` ------ **Sample `create-role`** `aws iam create-role --role-name AWSResilienceHubAssessmentRole --assume-role-policy-document file://trust-policy.json` **Sample Output** **Sample `attach-policy-to-role`** `aws iam attach-role-policy --role-name AWSResilienceHubAssessmentRole --policy-arn arn:aws:iam::aws:policy/AWSResilienceHubAsssessmentExecutionPolicy` # Roles in different AWS account for cross-account access - optional When your resources are located in secondary/resource accounts, you must create roles in each of these accounts to enable AWS Resilience Hub to successfully assess your application. The role creation procedure is similar to the invoker role creation process, except for the trust policy configuration. **Note** You must create the roles in secondary accounts where the resources are located. **Topics** + [Creating a role in the IAM console for secondary/resource accounts](#security-iam-resilience-cross-create-roles-infra-account) + [Managing roles with the IAM API](#security-iam-resilience-cross-create-roles-infra-account-api) + [Defining trust policy using JSON file](#security-iam-resilience-cross-define-trust-policy-infra-account) ## Creating a role in the IAM console for secondary/resource accounts To enable AWS Resilience Hub to access AWS services and resources in other AWS accounts, you must create roles in each of these accounts. **To create a role in the IAM console for the secondary/resource accounts using IAM console** 1. Open the IAM console at `https://console.aws.amazon.com/iam/`. 1. From the navigation pane, choose **Roles** and then choose **Create role**. 1. Select **Custom Trust Policy**, copy the following policy in the **Custom trust policy** window, and then choose **Next**. **Note** If your resources are in different accounts, you have to create a role in each of those accounts and use the secondary account trust policy for the other accounts. 1. In the **Permissions policies** section of **Add permissions** page, enter `AWSResilienceHubAsssessmentExecutionPolicy` in the **Filter policies by property or policy name and press enter** box. 1. Select the policy and choose **Next**. 1. In **Role details** section, enter a unique role name (such as `AWSResilienceHubAssessmentRole`) in the **Role name** box. 1. (Optional) Enter a description about the role in the **Description** box. 1. Choose **Create Role**. To edit the use cases and permissions, in step 6, choose **Edit** button that is located to the right of **Step 1: Select trusted entities ** or **Step 2: Add permissions** sections. In addition, you also need to add the `sts:assumeRole` permission to the invoker role to enable it to assume the roles in your secondary accounts. Add the following policy to your invoker role for each of the secondary roles you created: ``` { "Effect": "Allow", "Resource": [ "arn:aws:iam::secondary_account_id_1:role/RoleInSecondaryAccount_1", "arn:aws:iam::secondary_account_id_2:role/RoleInSecondaryAccount_2", ... ], "Action": [ "sts:AssumeRole" ] } ``` ### Managing roles with the IAM API A role's trust policy gives the specified principal's permission to assume the role. To create the roles using AWS Command Line Interface (AWS CLI), use the `create-role` command. When using this command, you can specify the trust policy inline. The following example shows how to grant the AWS Resilience Hub service principal permission to assume your role. **Note** The requirement to escape quotes (`' '`) in the JSON string may vary based on your shell version. **Sample `create-role`** ``` aws iam create-role --role-name AWSResilienceHubAssessmentRole --assume-role-policy-document '{"Version": "2012-10-17", "Statement": [{"Effect": "Allow","Principal": {"AWS": ["arn:aws:iam::primary_account_id:role/InvokerRoleName"]},"Action": "sts:AssumeRole"}]}' ``` You can also define the trust policy for the role using a separate JSON file. In the following example, `trust-policy.json` is a file in the current directory. ### Defining trust policy using JSON file You can define the trust policy for the role using a separate JSON file and then run the `create-role` command. In the following example, **`trust-policy.json`** is a file that contains the trust policy in the current directory. This policy is attached to a role by running **`create-role`** command. The output of the `create-role` command is shown in the **Sample Output**. To add permissions to a role, use the **attach-policy-to-role** command and you can start by adding the `AWSResilienceHubAsssessmentExecutionPolicy` managed policy. For more information about this managed policy, see [AWSResilienceHubAsssessmentExecutionPolicy](security-iam-awsmanpol.md#security_iam_aws-assessment-policy). **Sample `trust-policy.json`** **Sample `create-role`** ``` aws iam create-role --role-name AWSResilienceHubAssessmentRole --assume-role-policy-document file://trust-policy.json ``` **Sample Output** **Sample `attach-policy-to-role`** `aws iam attach-role-policy --role-name AWSResilienceHubAssessmentRole --policy-arn arn:aws:iam::aws:policy/AWSResilienceHubAsssessmentExecutionPolicy`. # Using current IAM user permissions Use this method if you want to use your current IAM user permissions to create and run an assessment. You can attach the `AWSResilienceHubAsssessmentExecutionPolicy` managed policy to your IAM user or a Role associated with your user. ## Single account setup Using the managed policy mentioned above is enough to run an assessment on an application which is managed in the same account as the IAM user. ## Scheduled assessment setup You must create a new role `AwsResilienceHubPeriodicAssessmentRole` to enable AWS Resilience Hub to perform scheduled assessment related tasks. **Note** While using the role-based access (with the invoker role mentioned above) this step is not required. The role name must be `AwsResilienceHubPeriodicAssessmentRole`. **To enable AWS Resilience Hub to perform scheduled assessment related tasks** 1. Attach the `AWSResilienceHubAsssessmentExecutionPolicy` managed policy to the role. 1. Add the following policy, where `primary_account_id` is the AWS account where the application is defined and will run the assessment. In addition, you must add the associated trust policy for the scheduled assessment's role, (`AwsResilienceHubPeriodicAssessmentRole`), which gives permissions for the AWS Resilience Hub service to assume the scheduled assessment's role. **Trust policy for the scheduled assessment's role (`AwsResilienceHubPeriodicAssessmentRole`)** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "resiliencehub.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ ## Cross-account setup The following IAM permissions policies are required if you're using AWS Resilience Hub with multiple accounts. Each AWS account might need different permissions depending on your use case. While setting up AWS Resilience Hub for cross-account access, the following accounts and roles are considered: + **Primary account** – AWS account in which you want to create the application and run assessments. + **Secondary/Resource account(s)** – AWS account(s) where the resources are located. **Note** While using the role-based access (with the invoker role mentioned above) this step is not required. For more information about configuring permissions to access Amazon Elastic Kubernetes Service, see [Enabling AWS Resilience Hub access to your Amazon Elastic Kubernetes Service cluster](enabling-eks-in-arh.md). ### Primary account setup You must create a new role `AwsResilienceHubAdminAccountRole` in the primary account and enable AWS Resilience Hub access to assume it. This role will be used to access another role in your AWS account that contains your resources. It should not have permissions to read resources. **Note** The role name must be `AwsResilienceHubAdminAccountRole`. It must be created in the primary account. Your current IAM user/role must have the `iam:assumeRole` permission to assume this role. Replace `secondary_account_id_1/2/...` with the relevant secondary account identifiers. The following policy provides executor permissions to your role for accessing resources in another role in your AWS account: The trust policy for the admin role (`AwsResilienceHubAdminAccountRole`) is as follows: ### Secondary/Resource account(s) setup In each of your secondary accounts, you must create a new `AwsResilienceHubExecutorAccountRole` and enable the admin role created above to assume this role. Since this role will be used by AWS Resilience Hub to scan and assess your application resources, it will also require the appropriate permissions. However, you must attach the `AWSResilienceHubAsssessmentExecutionPolicy` managed policy to the role and attach the executor role policy. The executor role trust policy is as follows: