Manage an AWS account external ID

Note

The AWS account external ID is only used when adding an AWS account using a cross-account role.

Topics:

What is the external ID?
Configure the external ID
Update the external ID
Retrieve the external ID
Disable retrieval of the external ID

What is the external ID?

Along with the cross-account role ARN, the external ID is used to grant access from one AWS role to another. The external ID is provided by a third-party service that wants to assume the role of your account. If you trust that service to act on your behalf, you add that external ID to your cross-account role. In this case, Deep Security is the third-party service that is providing an external ID to you, in order to act on behalf of your AWS account. Deep Security uses this access to synchronize information from your AWS account and maintain an up-to-date record of your resources. For details, see this AWS document: How to Use External ID When Granting Access to Your AWS Resources.

Notes:

The external ID is only used when adding an AWS account using a cross-account role.
The same external ID is used for all AWS accounts added using cross-account roles. There is one ID per tenant.

Configure the external ID

Configuring the external ID is one step in a larger process of adding a cross-account role. See Add an AWS account using a cross-account role for details.

Update the external ID

If you previously added an AWS account using cross-account role, you might have specified a user-defined external ID. To better align with AWS best-practices, Trend Micro recommends switching to the manager-defined external ID.

Note

AWS accounts that were previously added with a user-defined external ID will continue to function as normal.

Determine whether you're using a user- or manager-defined external ID

If you're not sure whether you're currently using a user- or manager-defined external ID, follow the procedure below to find out.

Log in to Deep Security Manager.
Click Computers.
Right-click the AWS account that was added using a cross-account role and select Properties.
If an Update link appears next to the external ID, it means that a user-defined external ID is currently in use and should be updated. If an Update link does not appear, it's because the manager-defined external ID is currently in use, and no action is necessary.
Repeat this procedure for each account that has been added to the manager using a cross-account role.

Update the external ID through the manager

If you have not already done so, log in to Deep Security Manager, right-click the AWS account you want to update, and select Properties.
Click the Update link that appears next to the external ID. The Update link disappears.
Note the external ID. You'll need it in the next step to configure the cross-account role.
Log in to the AWS account whose external ID you just updated. Update the cross-account role's IAM policy by replacing the old external ID with the new one.
Back on the properties window, click Apply to apply changes.

Your account's user-defined external ID has now been updated to the manager-defined one.
Repeat this procedure for each account that has been added to the manager using a cross-account role.

Update the external ID through the Deep Security API

If you don't already have the new manager-defined external ID, call the /api/awsconnectorsettings endpoint to retrieve it (the ExternalId parameter).
Log in to the AWS account where the cross-account role was configured. Update the cross-account role's IAM policy by replacing the old external ID with the new one. Repeat this step for each account that has been added to the manager using a cross-account role.
Using the /api/awsconnectors endpoint, perform an Update action on the account you are updating, with its CrossAccountRoleARN parameter set to the same role ARN as it is currently. Do not provide an external ID in the request object.

Your account's user-defined external ID has now been updated to the manager-defined one.

Retrieve the external ID

There are a few ways to retrieve the external ID for use with cross-accounts.

Through the 'add account' wizard

See Add an AWS account using a cross-account role which includes a sub-section on how to retrieve the external ID through the wizard.

Through the Deep Security API

Call the /api/awsconnectorsettings endpoint to retrieve it (the ExternalId parameter).

Disable retrieval of the external ID

You might want to disable the ability to view and retrieve the external ID in the manager to prevent unauthorized access to it. You can retrieve the ID once, store it in a safe place like your secrets manager, and then disable the retrieval for everyone else.

Note

Retrieval can be enabled again at any time.

To disable retrieval:

Log in to Deep Security Manager.
Click Administration at the top.
In the main pane, click the Security tab.
Deselect Enable retrieval and viewing of AWS external ID.
Click Save.

Tip

You can also use roles to prevent access to the external ID. For details, see Define roles for users.