Set up an Amazon Web Services (AWS) connector

IAM setup: Gather credentials that support syncing child account data

To sync IAM data (like users, roles, and groups) from multiple AWS child accounts, ConductorOne uses a secure, read-only mechanism called cross-account access. This setup works by allowing a central role in your root account to temporarily assume a specific role in each child account. This method ensures that the connector can gather the necessary data without storing credentials or requiring permanent access.

If you’re using this setup, make sure to click Enable support for AWS Organizations when setting up the connector in the ConductorOne web UI, and DO NOT click Enable support for AWS IAM Identity Center or Enable usage of the AWS IAM Identity Center SCIM API.

In order to use the connector to gather IAM AWS data, you’ll need to configure each sub-account to have a role with a trust policy. There are two options here:

• Use OrganizationAccountAccessRole, and add the following to the management role:

  { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::*:role/OrganizationAccountAccessRole" }

• Create a new custom role by following the steps below

Create a custom IAM role

This custom role acts as a bridge, allowing ConductorOne to securely access your child account. The trust policy you’re about to create is the key to this connection.

1. Navigate to the IAM Dashboard and select Roles > Create Role.

2. Select Custom Trust Policy and paste the following into the Trust Policy JSON editor, replacing {ROOT_ID} with the root ID from the main account, ConductorOneService with the role name from the root account, and EXTERNAL_ID_FROM_C1_INTEGRATIONS_PAGE with the External ID from ConductorOne.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Statement1",
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::{ROOT_ID}:role/ConductorOneService"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   } 
   

   Notes on the Trust Policy:

   “Action”: “sts:AssumeRole”: This is the core permission. It’s the only action allowed by this policy, and it specifically allows the ConductorOne role in your root account to temporarily assume this role in the child account. Think of it like a temporary key that only the main account can use.

   “Principal”: “arn:aws:iam::{ROOT_ID}:role/ConductorOneService”: This is the trusted entity. It specifies that only the ConductorOne role in your main root account is allowed to assume this role. This ensures that no other account can use this trust policy.

3. Click Next.

4. Skip Add permissions and click Next.

5. Give the role a name, such as ConductorOneIntegration.

   

6. Add any tags relevant to your organization and click Create Role.

7. Find the newly created role, and click on it to view the role details page.

   

Grant permission for data sync

Next, you will create an inline policy to define the specific data this role can gather from the child account. These are read-only permissions that enable ConductorOne to securely sync your IAM data.

1. Under Permissions Policies, click Add Permissions and select Create Inline Policy.

2. Switch to the JSON Editor tab and paste the following policy into the editor:

   {
     "Action": [
       "iam:ListUsers",
       "iam:ListGroups",
       "iam:ListRoles",
       "iam:GetGroup",
       //The following two permissions are only needed if you want ConductorOne to sync access key secret data
       "iam:ListAccessKeys",
       "iam:GetAccessKeyLastUsed", 
     ],
     "Effect": "Allow",
     "Resource": "*",
     // The minimum permissions required for the connector to sync. This will sync IAM Users, Groups, and Roles
     "Sid": "MinimumRequiredPermissionsSyncIAMUsersGroupsRoles"
   },
   

   Notes about permissions:

   iam:ListUsers: Allows ConductorOne to retrieve a list of all IAM user accounts in this AWS account.

   iam:ListGroups: Allows ConductorOne to retrieve a list of all IAM groups.

   iam:ListRoles: Allows ConductorOne to retrieve a list of all IAM roles.

   iam:GetGroup: Required to see which users belong to which groups. The ListGroups action only provides the group name, while GetGroup provides the group’s members.

   iam:ListAccessKeys and iam:GetAccessKeyLastUsed: These are optional permissions. They allow ConductorOne to gather data on the status of your IAM access keys, such as when they were last used. This is useful for auditing and security purposes (such as identifying unused or old keys). ConductorOne does not store or access the secret access key itself.

3. Click Review Policy.

4. Give the policy a name, such as ConductorOnePermissions and click Create Policy.

   

5. Copy the Role ARN for the Role we created, it should look like: arn:aws:iam::NNNNNNNNNN:role/ConductorOneIntegration.

That’s it! Next, move on to the connector configuration instructions.

SSO setup: Gather credentials

Follow these steps to gather the credentials needed for an AWS IAM Identity Center (SSO) setup of the AWS connector.

Get a ConductorOne-provided External ID

1. In ConductorOne, navigate to Admin > Connectors and click Add connector.

2. Search for AWS v2 and click Add.

3. Choose how to set up the new AWS connector:

   • Add the connector to a currently unmanaged app (select from the list of apps that were discovered in your identity, SSO, or federation provider that aren’t yet managed with ConductorOne)

   • Add the connector to a managed app (select from the list of existing managed apps)

   • Create a new managed app

4. Set the owner for this connector. You can manage the connector yourself, or choose someone else from the list of ConductorOne users. Setting multiple owners is allowed.

   If you choose someone else, ConductorOne will notify the new connector owner by email that their help is needed to complete the setup process.

5. Click Next.

6. Find the Settings area of the page and click Edit.

7. Copy and save the External ID populated in the External ID field.

Create a custom IAM role

This setup allows ConductorOne to integrate with AWS IAM Identity Center (formerly SSO). It requires permissions to both read existing user, group, and permission set data, and optionally, to provision new assignments and manage related resources.

The permissions policy below is broken into several sections to align with these functions. This allows you to grant only the permissions you need for your use case, following the principle of least privilege.

1. In a new browser tab, sign in to your AWS Account using your existing credentials or SSO.

   To support use of AWS Organizations: You must create this IAM Role in the management (formerly called master) account of the AWS Organization.

2. Navigate to the IAM Dashboard and select Roles > Create Role.

3. Select Custom Trust Policy and paste the following into the Trust Policy JSON editor, replacing EXTERNAL_ID_FROM_C1_INTEGRATIONS_PAGE with the External ID from ConductorOne.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::765656841499:role/ConductorOneService"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "EXTERNAL_ID_FROM_C1_INTEGRATIONS_PAGE"
           }
         }
       }
     ]
   }
   

4. Click Next.

5. Skip Add permissions and click Next.

6. Give the role a name, such as ConductorOneIntegration.

   

7. Add any tags relevant to your organization and click Create Role.

8. Find the newly created role, and click on it to view the role details page.

   

9. Under Permissions Policies, click Add Permissions and select Create Inline Policy.

   This policy provides the necessary permissions for ConductorOne to securely integrate with your AWS IAM Identity Center setup. Below is the full policy, followed by a detailed breakdown of each section.

10. Switch to the JSON Editor tab and paste the following policy into the editor:

    {
      "Statement": [
        {
          "Action": [
            "iam:GetGroup",
            "iam:GetAccessKeyLastUsed",  
            "iam:ListAccountAliases",
            "iam:ListGroups",
            "iam:ListRoles",
            "iam:ListUsers",
            "identitystore:GetGroupMembershipId",
            "identitystore:ListGroupMemberships",
            "identitystore:ListGroups",
            "identitystore:ListUsers",
            "organizations:ListAccounts",
            "sso:DescribePermissionSet",
            "sso:ListAccountAssignments",
            "sso:ListInstances",
            "sso:ListPermissionSets",
            "sso:ListPermissionSetsProvisionedToAccount"
          ],
          "Effect": "Allow",
          "Resource": "*",
          "Sid": "ConductorOneReadAccess"
        },
        {
          "Action": [
            "iam:AddUserToGroup",
            "iam:RemoveUserFromGroup",
            "sso:CreateAccountAssignment",
            "sso:DeleteAccountAssignment",
            "identitystore:CreateGroupMembership",
            "identitystore:DeleteGroupMembership",
            "sso:DescribeAccountAssignmentCreationStatus",
            "sso:DescribeAccountAssignmentDeletionStatus"
          ],
          "Effect": "Allow",
          "Resource": "*",
          "Sid": "ConductorOneProvisionAccess"
        },
        {
          "Sid": "AccessToSSOProvisionedRoles",
          "Effect": "Allow",
          "Action": [
            "iam:AttachRolePolicy",
            "iam:CreateRole",
            "iam:DeleteRole",
            "iam:DeleteRolePolicy",
            "iam:DetachRolePolicy",
            "iam:GetRole",
            "iam:ListAttachedRolePolicies",
            "iam:ListRolePolicies",
            "iam:PutRolePolicy",
            "iam:UpdateRole",
            "iam:UpdateRoleDescription"
          ],
          "Resource": "arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*"
        },
        {
          "Sid": "IAMListPermissions",
          "Effect": "Allow",
          "Action": [
            "iam:ListRoles",
            "iam:ListPolicies",
            "iam:ListAccessKeys"
          ],
          "Resource": "*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "iam:GetSAMLProvider"
          ],
          "Resource": "arn:aws:iam::*:saml-provider/AWSSSO_*_DO_NOT_DELETE"
        },
        {
          "Effect": "Allow",
          "Action": [
            "sts:AssumeRole"
          ],
          "Resource": "arn:aws:iam::*:role/OrganizationAccountAccessRole"
        }
      ],
      "Version": "2012-10-17"
    }
    

    Notes about permissions:

    Section 1: Read-Only Access (“ConductorOneReadAccess”)

    This group of permissions is the minimum required for ConductorOne to discover and sync your SSO users, groups, and permission sets. These are strictly read-only permissions.

    • iam:List..., iam:GetGroup: These are standard IAM permissions for listing users, groups, and roles. They are necessary to identify resources within your AWS account. iam:GetGroup provides the members of a group.

    • identitystore:List...: These permissions are specific to AWS IAM Identity Center. They allow ConductorOne to list and read information about your users and groups as they are defined within the Identity Center.

    • organizations:ListAccounts: This permission is required to list all the accounts within your AWS Organization, enabling ConductorOne to understand your account structure.

    • sso:List..., sso:Describe...: These permissions allow ConductorOne to list your permission sets and see how they are assigned to accounts and users.

    Section 2: Provisioning Access (“ConductorOneProvisionAccess”)

    This group of permissions is only required if you want to provision (create or delete) user assignments in AWS. For example, if you plan to use ConductorOne to add a user to a group or assign a permission set to a user, you will need to include these permissions.

    • iam:AddUserToGroup, iam:RemoveUserFromGroup: These permissions are used to manage IAM group memberships directly.

    • sso:CreateAccountAssignment, sso:DeleteAccountAssignment: These are the core permissions for provisioning. They allow ConductorOne to add or remove assignments of permission sets to users within your organization.

    • identitystore:CreateGroupMembership, identitystore:DeleteGroupMembership: These permissions manage group membership for users and groups defined within the Identity Center.

    Section 3: Access to SSO Provisioned Roles (“AccessToSSOProvisionedRoles”)

    This group of permissions allows ConductorOne to inspect and manage the AWS-managed roles created by IAM Identity Center in your accounts. This is crucial for understanding how permission sets are being applied.

    • iam:AttachRolePolicy, iam:DeleteRole, iam:GetRole, etc.: These are permissions to manage IAM roles. The key detail is the Resource constraint: arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*. This ensures that ConductorOne can only interact with roles created and managed by the AWS SSO service itself, preventing it from modifying other roles in your account.

    Section 4: Other Required Permissions

    These are supporting permissions that enable specific features or functionality.

    • IAMListPermissions: This section is needed to support the provisioning functionality. For example, it allows ConductorOne to list access keys for users. ConductorOne does not store or access the secret access keys.

    • sts:AssumeRole: This permission allows ConductorOne to assume the OrganizationAccountAccessRole in your child accounts. This is essential for discovering and syncing resources across your AWS Organization.

    • iam:GetSAMLProvider: This is a necessary permission to read the configuration of the SAML provider that AWS SSO uses for single sign-on.

    • The permissions listed in the "Sid": "IAMListPermissions" and "Sid": "AccessToSSOProvisiondRoles" sections are required only if you want to use ConductorOne to create assignments in the AWS Organization’s management account. In certain cases, you may also need to add iam:UpdateSAMLProvider to these sections.

    • The iam:GetAccessKeyLastUsed permission is only needed if you want ConductorOne to sync access key secret data.

11. Click Review Policy.

12. Give the policy a name, such as ConductorOnePermissions and click Create Policy.

13. Copy the Role ARN for the Role we created, it should look like: arn:aws:iam::NNNNNNNNNN:role/ConductorOneIntegration.

That’s it! Next, move on to the connector configuration instructions.

Follow these instructions to use a built-in, no-code connector hosted by ConductorOne.

1. Return to the AWS v2 connector setup page in ConductorOne.

2. Find the Settings area of the page and click Edit.

3. Paste the AWS Role ARN into the Role ARN field.

4. Optional. Click to Enable support for AWS Organizations.

   If support for AWS Organizations is enabled, the IAM Role (as described in Step 2) must be created in the management (formerly called master) account of the AWS Organization. If the IAM Role is created on a member account and support for AWS Organizations is enabled, the integration will return a 400 error.

5. Optional. Click to Enable support for AWS IAM Identity Center and select the region for AWS IAM Identity Center from the dropdown.

6. Optional. To enable ConductorOne to sync the statuses of SSO accounts, click to Enable usage of the AWS IAM Identity Center SCIM API and enter the SCIM endpoint and access token in the relevant fields.

7. Optional. Enable Sync secrets to display them on the Inventory page.

8. Click Save.

9. The connector’s label changes to Syncing, followed by Connected. You can view the logs to ensure that information is syncing.

That’s it! Your AWS connector is now pulling access data into ConductorOne.

Follow these instructions to use the Amazon Web Services connector, hosted and run in your own environment.

When running in service mode on Kubernetes, a self-hosted connector maintains an ongoing connection with ConductorOne, automatically syncing and uploading data at regular intervals. This data is immediately available in the ConductorOne UI for access reviews and access requests.

Step 1: Set up a new AWS connector

1. In ConductorOne, navigate to Connectors > Add connector.

2. Search for Baton and click Add.

3. Choose how to set up the new AWS connector:

   • Add the connector to a currently unmanaged app (select from the list of apps that were discovered in your identity, SSO, or federation provider that aren’t yet managed with ConductorOne)

   • Add the connector to a managed app (select from the list of existing managed apps)

   • Create a new managed app

4. Set the owner for this connector. You can manage the connector yourself, or choose someone else from the list of ConductorOne users. Setting multiple owners is allowed.

   If you choose someone else, ConductorOne will notify the new connector owner by email that their help is needed to complete the setup process.

5. Click Next.

6. In the Settings area of the page, click Edit.

7. Click Rotate to generate a new Client ID and Secret.

   Carefully copy and save these credentials. We’ll use them in Step 2.

Step 2: Create Kubernetes configuration files

Create two Kubernetes manifest files for your AWS connector deployment:

Secrets configuration

# baton-aws-secrets.yaml
apiVersion: v1
kind: Secret
metadata:
  name: baton-aws-secrets
type: Opaque
stringData:
  # ConductorOne credentials
  BATON_CLIENT_ID: <ConductorOne client ID>
  BATON_CLIENT_SECRET: <ConductorOne client secret>
  
  # AWS credentials
  BATON_EXTERNAL_ID: <External ID for the AWS account, generated by ConductorOne>
  BATON_ROLE_ARN: <AWS Role ARN>

  # Optional: Include if you want ConductorOne to provision access using this connector
  BATON_PROVISIONING: true

  # Optional: Include if you want to enable support for AWS Organizations (see note below)
  BATON_GLOBAL_AWS_ORGS_ENABLED: true

  # Optional: Include if you want to enable support for AWS IAM Identity Center
  BATON_GLOBAL_AWS_SSO_ENABLED: true
  BATON_GLOBAL_AWS_SSO_REGION: <Region for SSO identities (default is "us-east-1")>

  # Optional: Include to enable ConductorOne to sync the statuses of SSO accounts
  BATON_SCIM_ENABLED: true
  BATON_SCIM_ENDPOINT: <SCIM endpoint>
  BATON_SCIM_TOKEN: <SCIM access token>

If support for AWS Organizations is enabled, the IAM Role must be created in the management (formerly called master) account of the AWS Organization. If the IAM Role is created on a member account and support for AWS Organizations is enabled, the integration will return a 400 error.

See the connector’s README or run --help to see all available configuration flags and environment variables.

Deployment configuration

# baton-aws.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: baton-aws
  labels:
    app: baton-aws
spec:
  selector:
    matchLabels:
      app: baton-aws
  template:
    metadata:
      labels:
        app: baton-aws
        baton: true
        baton-app: aws
    spec:
      containers:
      - name: baton-aws
        image: ghcr.io/conductorone/baton-aws:latest
        imagePullPolicy: IfNotPresent
        envFrom:
        - secretRef:
            name: baton-aws-secrets

Step 3: Deploy the connector

1. Create a namespace in which to run ConductorOne connectors (if desired), then apply the secret config and deployment config files.

2. Check that the connector data uploaded correctly. In ConductorOne, click Applications. On the Managed apps tab, locate and click the name of the application you added the AWS connector to. AWS data should be found on the Entitlements and Accounts tabs.

That’s it! Your AWS connector is now pulling access data into ConductorOne.

Configure the AWS connector using Terraform

Use the following Terraform script to integrate your AWS instance with ConductorOne.

Step 1: Get ConductorOne-provided External ID for AWS IAM Role

1. Log into ConductorOne.

2. Click Connectors > AWS Connector.

3. Copy and save the External ID populated in the External ID field. We’ll use this in Step 2.

Step 2: Use a Terraform script to set up the AWS integration

variable "EXTERNAL_ID_FROM_C1_INTEGRATIONS_PAGE" {
  description = "ConductorOne-provided External ID for AWS IAM Role from Step 1"
  type        = string
}

resource "aws_iam_role" "ConductorOneIntegration" {
  name = "ConductorOneIntegration"
  assume_role_policy = jsonencode(
    {
      "Version" : "2012-10-17",
      "Statement" : [
        {
          "Effect" : "Allow",
          "Principal" : {
            "AWS" : "arn:aws:iam::765656841499:role/ConductorOneService"
          },
          "Action" : "sts:AssumeRole",
          "Condition" : {
            "StringEquals" : {
              "sts:ExternalId" : var.EXTERNAL_ID_FROM_C1_INTEGRATIONS_PAGE
            }
          }
        }
      ]
    })

  inline_policy {
    name = "ConductorOnePermissions"
    policy = jsonencode({
      "Statement" : [
        {
          "Action" : [
            "iam:GetGroup",
            "iam:ListAccountAliases",
            "iam:ListGroups",
            "iam:ListRoles",
            "iam:ListUsers",
            "identitystore:ListGroupMemberships",
            "identitystore:GetGroupMembershipId",
            "identitystore:ListGroups",
            "identitystore:ListUsers",
            "organizations:ListAccounts",
            "sso:DescribePermissionSet",
            "sso:ListAccountAssignments",
            "sso:ListInstances",
            "sso:ListPermissionSets",
            "sso:ListPermissionSetsProvisionedToAccount"
          ],
          "Effect" : "Allow",
          "Resource" : "*",
          "Sid" : "ConductorOneReadAccess"
        },
        {
          "Action" : [
            "iam:AddUserToGroup",
            "iam:RemoveUserFromGroup",
            "sso:CreateAccountAssignment",
            "sso:DeleteAccountAssignment",
            "identitystore:CreateGroupMembership",
            "identitystore:DeleteGroupMembership",
            "sso:DescribeAccountAssignmentCreationStatus",
            "sso:DescribeAccountAssignmentDeletionStatus"
          ],
          "Effect" : "Allow",
          "Resource" : "*",
          "Sid" : "ConductorOneProvisionAccess"
        },
        {
          "Sid" : "AccessToSSOProvisionedRoles",
          "Effect" : "Allow",
          "Action" : [
            "iam:AttachRolePolicy",
            "iam:CreateRole",
            "iam:DeleteRole",
            "iam:DeleteRolePolicy",
            "iam:DetachRolePolicy",
            "iam:GetRole",
            "iam:ListAttachedRolePolicies",
            "iam:ListRolePolicies",
            "iam:PutRolePolicy",
            "iam:UpdateRole",
            "iam:UpdateRoleDescription"
          ],
          "Resource" : "arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*"
        },
        {
          "Sid" : "IAMListPermissions",
          "Effect" : "Allow",
          "Action" : [
            "iam:ListRoles",
            "iam:ListPolicies"
          ],
          "Resource" : "*"
        },
        {
          "Effect" : "Allow",
          "Action" : [
            "iam:GetSAMLProvider"
          ],
          "Resource" : "arn:aws:iam::*:saml-provider/AWSSSO_*_DO_NOT_DELETE"
        },
        # OPTIONAL: This statement is only needed if requesting child accounts when Identity Center is not configured
        {
          "Effect": "Allow",
          "Action": [
            "sts:AssumeRole"
          ],
          "Resource": "arn:aws:iam::*:role/OrganizationAccountAccessRole"
        }
      ],
      "Version" : "2012-10-17"
    })
  }
}