> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Set Up Unified AWS Access **Note:** The MongoDB Atlas Shared Responsibility Model defines the complementary duties of MongoDB and its customers in maintaining a secure and resilient data environment. Under this framework, MongoDB manages the security and operational integrity of the underlying platform, while customers are responsible for the configuration, management, and data policies of their specific deployments. For a detailed breakdown of ownership across security and operational excellence, see [Shared Responsibility Model.](https://www.mongodb.com/resources/products/fundamentals/shared-responsibility) ## Overview Some Atlas features, including [Data Federation](https://www.mongodb.com/docs/atlas/data-federation.md#std-label-atlas-data-federation) and [Encryption at Rest](https://www.mongodb.com/docs/atlas/security-aws-kms.md#std-label-security-aws-kms), authenticate with AWS (Amazon Web Services) [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). When Atlas accesses AWS (Amazon Web Services) services, [assumes an IAM role.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) You can set up an assumed IAM role for your Atlas account to use with the Atlas Administration API or Atlas UI if you have the [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) role. Atlas supports unified access only for AWS (Amazon Web Services). ## Required Access To set up unified AWS (Amazon Web Services) access, you must have [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) or [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project. ## Prerequisites - An Atlas [account.](https://www.mongodb.com/docs/atlas/index.md#std-label-atlas-index) - The [AWS Command Line Interface (CLI).](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install/) ## Procedure 1. Create a new AWS (Amazon Web Services) IAM (Identity and Access Management) role in Atlas. To create an AWS IAM role using the Atlas CLI, run the following command: ```sh atlas cloudProviders accessRoles aws create [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas cloudProviders accessRoles aws create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-cloudProviders-accessRoles-aws-create/) Save the `AtlasAWSAccountArn` and `AtlasAssumedRoleExternalId` field values returned by the command for use in the next step. 2. Modify your AWS IAM role trust policy. 1. Log in to your AWS (Amazon Web Services) Management Console. 2. Navigate to the Identity and Access Management (IAM) service. 3. Select Roles from the left-side navigation. 4. Click on the existing IAM role you wish to use for Atlas access from the list of roles. 5. Select the Trust Relationships tab. 6. Click the Edit trust relationship button. 7. Edit the Policy Document. Add a new `Statement` object with the following content. **Note:** Replace the highlighted lines with values returned in the previous step. ```json { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "AWS":"" }, "Action":"sts:AssumeRole", "Condition":{ "StringEquals":{ "sts:ExternalId":"" } } } ] } ``` 8. Click the Update Trust Policy button. 3. Authorize the new IAM (Identity and Access Management) role. To authorize an AWS IAM role using the Atlas CLI, run the following command: ```sh atlas cloudProviders accessRoles aws authorize [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas cloudProviders accessRoles aws authorize.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-cloudProviders-accessRoles-aws-authorize/) If the command succeeds, you can use the `RoleID` value when configuring Atlas services that use AWS (Amazon Web Services). ## Manage AWS IAM Roles To authorize an AWS IAM role using the Atlas CLI, run the following command: ```sh atlas cloudProviders accessRoles aws authorize [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas cloudProviders accessRoles aws authorize.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-cloudProviders-accessRoles-aws-authorize/) ## Deauthorize an Assumed IAM Role **Note:** Be sure to remove any associated Atlas services from the IAM role before you deauthorize it. To deauthorize an AWS IAM role using the Atlas CLI, run the following command: ```sh atlas cloudProviders accessRoles aws deauthorize [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas cloudProviders accessRoles aws deauthorize.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-cloudProviders-accessRoles-aws-deauthorize/) ## Overview Some Atlas features, including [Data Federation](https://www.mongodb.com/docs/atlas/data-federation.md#std-label-atlas-data-federation) and [Encryption at Rest](https://www.mongodb.com/docs/atlas/security-aws-kms.md#std-label-security-aws-kms), authenticate with AWS (Amazon Web Services) [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). When Atlas accesses AWS (Amazon Web Services) services, [assumes an IAM role.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) You can set up an assumed IAM role for your Atlas account to use with the Atlas Administration API or Atlas UI if you have the [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) role. Atlas supports unified access only for AWS (Amazon Web Services). ## Required Access To set up unified AWS (Amazon Web Services) access, you must have [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) or [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project. ## Prerequisites - An Atlas [account.](https://www.mongodb.com/docs/atlas/index.md#std-label-atlas-index) - The [AWS Command Line Interface (CLI).](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install/) ## Procedure 1. Send a POST request to the `cloudProviderAccess` endpoint. Use the [API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#operation/createCloudProviderAccessRole) endpoint to create a new AWS (Amazon Web Services) IAM role. Atlas will use this role for authentication with your AWS (Amazon Web Services) account. Keep the returned field values `atlasAWSAccountArn` and `atlasAssumedRoleExternalId` handy for use in the next step. 2. Modify your AWS IAM role trust policy. 1. Log in to your AWS (Amazon Web Services) Management Console. 2. Navigate to the Identity and Access Management (IAM) service. 3. Select Roles from the left-side navigation. 4. Click on the existing IAM role you wish to use for Atlas access from the list of roles. 5. Select the Trust Relationships tab. 6. Click the Edit trust relationship button. 7. Edit the Policy Document. Add a new `Statement` object with the following content. **Note:** Replace the highlighted lines with values returned in the previous step. ```json { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "AWS":"" }, "Action":"sts:AssumeRole", "Condition":{ "StringEquals":{ "sts:ExternalId":"" } } } ] } ``` 8. Click the Update Trust Policy button. 3. Authorize the newly created IAM role. Use the [API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#operation/authorizeCloudProviderAccessRole) endpoint to authorize and configure the new IAM Assumed Role ARN (Amazon Resource Name). If the API call is successful, you can use the `roleId` value when configuring Atlas services that use AWS (Amazon Web Services). ## Manage AWS IAM Roles You can manage AWS (Amazon Web Services) IAM roles using the [API.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-cloud-provider-access) ## Deauthorize an Assumed IAM Role Use the `DELETE` API endpoint described in the [API documentation.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-deauthorizecloudprovideraccessrole) ## Overview Some Atlas features, including [Data Federation](https://www.mongodb.com/docs/atlas/data-federation.md#std-label-atlas-data-federation) and [Encryption at Rest](https://www.mongodb.com/docs/atlas/security-aws-kms.md#std-label-security-aws-kms), authenticate with AWS (Amazon Web Services) [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). When Atlas accesses AWS (Amazon Web Services) services, [assumes an IAM role.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) You can set up an assumed IAM role for your Atlas account to use with the Atlas Administration API or Atlas UI if you have the [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) role. Atlas supports unified access only for AWS (Amazon Web Services). ## Required Access To set up unified AWS (Amazon Web Services) access, you must have [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) or [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project. ## Prerequisites - An Atlas [account.](https://www.mongodb.com/docs/atlas/index.md#std-label-atlas-index) - The [AWS Command Line Interface (CLI).](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) ## Procedure ### Begin the Setup Procedure for AWS IAM Access 1. In Atlas, go to the Project Settings page. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar. If it's not already displayed, select your desired project from the Projects menu in the navigation bar. In the sidebar, click the icon next to Project Overview. The [Project Settings](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsettings%2FgroupSettings) page displays. 2. In Atlas, go to the Project Integrations page. Click the Integrations tab. The [Project Integrations](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fintegrations) page displays. 3. Set up AWS IAM Access. Click the Configure button in the AWS IAM Role Access panel. **Note:** If you already have one or more roles configured, the button reads Edit. Click the Authorize an AWS IAM Role button. Read through the Overview instructions, then click Next. If you'd like to create a new AWS IAM role for use with Atlas, use the [Create New Role with the AWS CLI](https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access.md#std-label-create-new-role-aws-cli) procedure. If you have an existing AWS IAM role you want to authorize for Atlas, use the [Add Trust Relationships to an Existing Role](https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access.md#std-label-authorize-existing-aws-role) procedure. ### Create New Role with the AWS CLI 1. Click Create New Role with the AWS CLI to expand the next section. 2. Copy the JSON text and save it to a file named `role-trust-policy.json`. 3. Enter a name for your new AWS IAM role in the text box. 4. If you don't already have the AWS Command Line Interface (CLI) installed, see the [documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html). If you do have the AWS CLI installed, proceed to the next step. 5. Copy the CLI command and enter it at the command prompt. 6. If successful, the CLI command returns a JSON document with information about the newly created AWS IAM role. Locate the field named Arn and copy it into the text box labelled Enter the Role ARN in the Atlas modal window. 7. Click Validate and Finish. ### Add Trust Relationships to an Existing Role 1. Click Add Trust Relationships to an Existing Role to expand the next section. 2. Copy the JSON trust relationship text. 3. In your AWS web console, navigate to the Roles section of the IAM dashboard. 4. Click on the role you want to authorize. 5. Select the Trust relationships tab. 6. Click the Edit trust relationship button. 7. Replace the existing text with the JSON text you copied in step 2. 8. Click Update Trust Policy. 9. Copy the Role ARN and paste it in the Atlas modal window, in the text box labelled Enter the Role ARN. 10. Click Validate and Finish. ## Manage AWS IAM Roles To navigate to the Atlas AWS IAM Role Access screen: 1. In Atlas, go to the Project Settings page. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar. If it's not already displayed, select your desired project from the Projects menu in the navigation bar. In the sidebar, click the icon next to Project Overview. The [Project Settings](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsettings%2FgroupSettings) page displays. 2. In Atlas, go to the Project Integrations page. Click the Integrations tab. The [Project Integrations](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fintegrations) page displays. 3. Configure the Atlas AWS IAM Role Access. Click the Configure button in the AWS IAM Role Access panel. **Note:** If you already have one or more roles configured, the button reads Edit. You can perform the following actions from the Atlas AWS IAM Role Access screen: - **View the list of authorized AWS IAM roles.** The list of roles displays the role's ARN (Amazon Resource Name), its time of creation, and any Atlas services configured to use the role. - **Authorize an AWS IAM role.** Click the Authorize an AWS IAM Role button. **Note:** If you have an authorization in progress, the associated role has a Resume button next to it. For detailed instructions, see [Set Up Unified AWS Access.](https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access.md#std-label-set-up-unified-aws-access) - **Deauthorize an AWS IAM role.** Click the Delete button next to the role. **Note:** Be sure to remove any associated Atlas services from the IAM role before you deauthorize it. - **View the details of an AWS IAM role.** Click the ellipsis (...) icon next to the role and select View Role Details. ## Deauthorize an Assumed IAM Role 1. In Atlas, go to the Project Settings page. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar. If it's not already displayed, select your desired project from the Projects menu in the navigation bar. In the sidebar, click the icon next to Project Overview. The [Project Settings](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsettings%2FgroupSettings) page displays. 2. In Atlas, go to the Project Integrations page. Click the Integrations tab. The [Project Integrations](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fintegrations) page displays. 3. Deauthorize the assumed IAM Role. Click the Edit button in the AWS IAM Role Access panel. Click the Delete button next to the IAM role you want to deauthorize. ## Resume an Authorization Procedure If you cancel a procedure to authorize an AWS IAM role for use with Atlas, you can resume it where you left off. 1. In Atlas, go to the Project Settings page. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar. If it's not already displayed, select your desired project from the Projects menu in the navigation bar. In the sidebar, click the icon next to Project Overview. The [Project Settings](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsettings%2FgroupSettings) page displays. 2. In Atlas, go to the Project Integrations page. Click the Integrations tab. The [Project Integrations](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fintegrations) page displays. 3. Resume authorization. Click the Configure button in the AWS IAM Role Access panel. **Note:** If you already have one or more roles configured, the button reads Edit. Any roles with an ongoing authorization procedure are listed with an `in progress` status. Click the Resume button to resume the authorization process. To cancel an in-progress role authorization completely, click the Delete icon next to the in-progress role.