Cloud Integration: AWS Organization Onboarding

Owned by John Gerlock
Last updated: Jun 27, 2024
17 min read

This feature is in preview and is not yet available in the user interface.

Overview

Onboarding your AWS account grants Data Theorem read-only access to inspect the resources in your account. The access controlled using AWS’s IAM. A new role will be created in your account, and that role will have the required policies attached to it. It will allow a user in Data Theorem’s dedicated AWS account to assume the role in your account. Onboarding the management AWS account for your AWS Organization will allow us to onboard all the AWS accounts in your AWS Organization automatically.

To create the necessary IAM Role and IAM policies in your AWS Organization, Data Theorem provides a Cloud Formation Template.

The AWS CloudFormation template will perform the following actions:

  • Create the “organization role”, that will give Data Theorem the capability to list AWS accounts belonging to the organization for onboarding purpose, and perform discovery.

  • Create a CloudFormation StackSet that will take care of creating the necessary role and policy in each AWS account in you organization.

 

AWSTemplateFormatVersion: "2010-09-09" Description: Setup roles and CloudFormation StackSet to onboard all children accounts within an organization Parameters: OrganizationalUnitIds: Type: CommaDelimitedList Description: Organizational unit IDs OrganizationRoleName: Type: String Description: Role name for allowing DT to auto-onboard organization members account AllowedPattern: '[-_a-zA-Z0-9]+' Default: DataTheorem-OrganizationOnboardingService DiscoveryRoleName: Type: String AllowedPattern: '[-_a-zA-Z0-9]+' Description: Role name for allowing DT to perform discovery Default: DataTheorem-DiscoveryService ExternalID: Type: String Description: External ID provided by support Region: Type: String Description: Region for the CloudFormation deployment (defaults to us-east-1) Default: us-east-1 Resources: OrganizationRole: Type: AWS::IAM::Role Properties: RoleName: Ref: OrganizationRoleName AssumeRolePolicyDocument: Version: "2012-10-17" Statement: - Effect: Allow Principal: AWS: arn:aws:iam::835257243705:root Action: sts:AssumeRole Condition: StringEquals: sts:ExternalId: Ref: ExternalID OrganizationRolePolicies: Type: AWS::IAM::Policy Properties: PolicyName: DataTheorem-OrganizationRole PolicyDocument: Version: "2012-10-17" Statement: - Sid: OrgAccess Effect: Allow Action: - iam:SimulatePrincipalPolicy - organizations:DescribeAccount - organizations:DescribeOrganization - organizations:ListAccountsForParent - organizations:ListOrganizationalUnitsForParent - organizations:ListPolicies - organizations:ListRoots - organizations:ListTagsForResource - organizations:ListTargetsForPolicy Resource: '*' Roles: - Ref: OrganizationRole RootDiscoveryRole: Type: AWS::IAM::Role Properties: RoleName: Ref: DiscoveryRoleName ManagedPolicyArns: - arn:aws:iam::aws:policy/SecurityAudit AssumeRolePolicyDocument: Version: "2012-10-17" Statement: - Effect: Allow Principal: AWS: arn:aws:iam::835257243705:root Action: sts:AssumeRole Condition: StringEquals: sts:ExternalId: Ref: ExternalID RootDiscoveryRolePolicies: Type: AWS::IAM::Policy Properties: PolicyName: DataTheorem-ExtraAccess PolicyDocument: Version: "2012-10-17" Statement: - Sid: InspectApiGateways Effect: Allow Resource: '*' Action: - apigateway:GET - Sid: InspectLambdas Effect: Allow Action: - lambda:Get* Resource: '*' - Sid: InstallDTAPIProtectLayer Effect: Allow Action: - lambda:UpdateFunctionConfiguration Resource: '*' Roles: - Ref: RootDiscoveryRole OrgOnboardingStackSet: Type: AWS::CloudFormation::StackSet DeletionPolicy: Retain Properties: StackSetName: DataTheorem-OrganizationAutoOnboarding43d962 AutoDeployment: Enabled: true RetainStacksOnAccountRemoval: false Capabilities: - CAPABILITY_NAMED_IAM Description: Updatedescription1 PermissionModel: SERVICE_MANAGED ManagedExecution: Active: true Parameters: - ParameterKey: ExternalID ParameterValue: Ref: ExternalID - ParameterKey: DiscoveryRoleName ParameterValue: Ref: DiscoveryRoleName StackInstancesGroup: - DeploymentTargets: OrganizationalUnitIds: Ref: OrganizationalUnitIds Regions: - Ref: Region OperationPreferences: FailureTolerancePercentage: 100 TemplateBody: |- { "AWSTemplateFormatVersion": "2010-09-09", "Parameters": { "DiscoveryRoleName": { "Type": "String", "Description": "Role name for allowing us to auto-onboard organization members account", "AllowedPattern": "[-_a-zA-Z0-9]+" }, "ExternalID": { "Type": "String", "Description": "External ID provided by support" } }, "Resources": { "RootRole": { "Type": "AWS::IAM::Role", "Properties": { "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::835257243705:root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": { "Ref": "ExternalID" } } } } ] }, "RoleName": { "Ref": "DiscoveryRoleName" }, "Path": "/", "ManagedPolicyArns": [ "arn:aws:iam::aws:policy/SecurityAudit" ] } }, "RolePolicies": { "Type": "AWS::IAM::Policy", "Properties": { "PolicyName": "DataTheorem-ExtraAccess", "PolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Sid": "InspectApiGateways", "Effect": "Allow", "Resource": "*", "Action": [ "apigateway:GET" ] }, { "Sid": "InspectLambdas", "Effect": "Allow", "Action": [ "lambda:Get*" ], "Resource": "*" }, { "Sid": "InstallDTAPIProtectLayer", "Effect": "Allow", "Action": [ "lambda:UpdateFunctionConfiguration" ], "Resource": "*" } ] }, "Roles": [ { "Ref": "RootRole" } ] } } } } Outputs: OrganizationRoleARN: Value: Fn::GetAtt: - OrganizationRole - Arn Description: Role ARN to give back to support DiscoveryRoleName: Value: Ref: DiscoveryRoleName Description: Role name to give back to support ExternalID: Value: Ref: ExternalID Description: External ID to give back to support

Prerequisites

  • Administrator access to the management account for the AWS Organization

  • The “Organization Id” of your AWS Organization root

  • The AWS organization must have the following features enabled:

    • Trusted access for AWS Account Management

    • CloudFormation StackSets

  • The AWS Cloud Formation Quick Create link you received from Data Theorem

Enabling trusted access for AWS Account Management and CloudFormation StackSets

Log in to the AWS console with your AWS Organization management account and navigate to the AWS Organizations Services page: https://us-east-1.console.aws.amazon.com/organizations/v2/home/services

  1. Ensure “AWS Account Management” is enabled

  2. Ensure “CloudFormation StackSets“ is enabled

 

image-20230814-190406.png

 

image-20230814-190439.png

 

Collect your AWS Organization ID

  1. Navigate to the AWS Organization Accounts page https://us-east-1.console.aws.amazon.com/organizations/v2/home/accounts and make a note of your organization ID. You will need this value in a later step. In the example below, the Organization ID is r-hd2b.

 

Running the AWS CloudFormation Template

  1. Open the link you received from DT in your browser. This will open the AWS console. Sign in as a user with admin privileges in your AWS Organization root account. The link will open the Data Theorem Cloud Formation Template

  2. Input the r- prefixed Organization ID in the OrganizationalUnitIds field

  3. Click Next twice, and submit the Stack

  4. Wait for stack to complete

  5. Copy the outputs and email them to support@datatheorem.com. In the example below, the necessary values would be: DataTheorem-Service and arn:aws:iam::1111111111:role/DataTheorem-OrganizationOnboarding