Configure additional AWS accounts to manage in Opal

📘
If you haven't configured your AWS management account in Opal, get started with our AWS integration guide before configuring additional accounts.

For each additional AWS account—IAM role, RDS database, etc.—that you want Opal to manage, you must add an Identity Provider and 2 IAM Roles with different permission scopes. Use this guide to configure each additional AWS account to manage in Opal, then see steps 4-6 in our AWS app integration guide to complete your AWS app integration.

Perform steps 1-3 for each account you want Opal to manage.

1. Create Ingester Role

Note: This step can be skipped for your management account, as you configured its ingester role in the previous step.

The ingester role allows Opal to read your configuration and populate it within Opal. Create a role called OpalIngester, with the same trust policy as above:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"AWS": "arn:aws:iam::602387580983:user/OpalIngester"
			},
			"Action": [
				"sts:AssumeRole"
			],
			"Condition": {
				"StringEquals": {
					"sts:ExternalId": "${EXTERNAL_ID}"
				}
			}
		},
		{
			"Effect": "Allow",
			"Principal": {
				"AWS": "arn:aws:iam::602387580983:user/OpalIngester"
			},
			"Action": [
				"sts:TagSession"
			]
		}
	]
}

Then, attach the following permissions policy to it. Use the Explanation tab to view which permissions you can customize and the Policy tabs for a version you can copy and paste.

// IMPORTANT: This snippet is meant for documenting why Opal requires each of
// these permissions, allowing you to customize based on your needs. For a valid
// pasteable policy document, open the "Policy" tab above.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      // Required to import IAM Roles, EC2 instances, EKS clusters and RDS databases into Opal.
      "Sid": "OpalRequiredToManageAccount",
      "Effect": "Allow",
      "Action": [
        "iam:ListRoleTags",
        "iam:ListRoles",
        "iam:GetRolePolicy",
        "iam:GetPolicy",
        "iam:GetRole",
        "rds:DescribeDBInstances",
        "rds:DescribeDBClusters",
        "ec2:DescribeInstances",
        "eks:DescribeCluster",
        "eks:ListClusters",
        // Required to filter out disabled regions when importing resources.
				"account:ListRegions"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OpalRequiredToManageAccount",
      "Effect": "Allow",
      "Action": [
        "iam:ListRoleTags",
        "iam:ListRoles",
        "iam:GetRolePolicy",
        "iam:GetPolicy",
        "iam:GetRole",
        "rds:DescribeDBInstances",
        "rds:DescribeDBClusters",
        "ec2:DescribeInstances",
        "eks:DescribeCluster",
        "eks:ListClusters",
        "account:ListRegions"
      ],
      "Resource": "*"
    }
  ]
}

2. Register Identity Provider

Add your OIDC identity provider to your AWS account—you can search for Identity provider in the AWS IAM console, then select Add provider. See the AWS documentation for more detail or alternative methods.

Set the following fields in AWS.

Field	Value
Provider type	OpenID Connect
Provider URL	The issuer URL from your OIDC provider. This should be the same value as the Issuer URL in AWS Settings > OIDC Provider Settings in Opal. For example, `https://companyname.oktapreview.com`.
Audience	The Client ID from your OIDC provider. This should be the same value as the Client ID in AWS Settings > OIDC Provider Settings in Opal.

3. Create User Role

The User role is used to grant your authenticated users access to the resources that have been allocated to them.

Create a role called OpalUser with the following trust policy, substituting in your management account ID, OIDC issuer URL, and the Client ID used for your OIDC configuration:

${ACCOUNT_ID}: The account ID of the account being configured
${IDP_ISSUER_URL}: The OIDC issuer URL
${OPAL_CLIENT_ID}: The Client ID you used in Step 3b

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::${ACCOUNT_ID}:oidc-provider/${IDP_ISSUER_URL}"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "${IDP_ISSUER_URL}:aud": "${OPAL_CLIENT_ID}"
        }
      }
    }
  ]
}

This trust policy ensures that only users authenticated with your identity provider can be granted access to the role.

Next, add the following permissions policy to the role. Use the Explanation tab to view which permissions you can customize and the Policy tabs for a version you can copy and paste.

// IMPORTANT: This snippet is meant for documenting why Opal requires each of
// these permissions, allowing you to customize based on your needs. For a valid
// pasteable policy document, open the "Policy" tab above.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      // Required to:
      // * Revoke sessions in this account
      // * Grant users session-based access to:
      //   * EC2 instances
      //   * RDS databases/clusters
      "Sid": "OpalRequiredToManageUserSessions",
      "Effect": "Allow",
      "Action": [
        // Required to read/validate AWS configuration
        "access-analyzer:ValidatePolicy",
        "ec2:DescribeInstances",
        "eks:DescribeCluster",
        "eks:ListClusters",
        "iam:GetRole",
        "iam:ListRoles",
        "iam:ListRoleTags",
        "iam:GetRolePolicy",
        "rds:DescribeDBClusters",
        "rds:DescribeDBInstances",
        "ssm:DescribeInstanceProperties",
        "ssm:DescribeSessions",
        "ssm:GetConnectionStatus",
        // Required to tag roles and sessions
        "sts:TagSession",
        "iam:TagRole",
        // Required to revoke sessions before expiration, e.g. if a user's access
        // is removed by admin in Opal.
        "iam:DeleteRolePolicy",
        "iam:PutRolePolicy",
        // Required to grant end-users session credentials.
        "rds-db:connect",
        "ssm:SendCommand",
        "ssm:TerminateSession",
        "ssm:StartSession"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OpalRequiredToManageUserSessions",
      "Effect": "Allow",
      "Action": [
        "access-analyzer:ValidatePolicy",
        "ec2:DescribeInstances",
        "eks:DescribeCluster",
        "eks:ListClusters",
        "iam:GetRole",
        "iam:ListRoleTags",
        "iam:GetRolePolicy",
        "iam:DeleteRolePolicy",
        "iam:PutRolePolicy",
        "iam:ListRoles",
        "iam:TagRole",
        "rds-db:connect",
        "rds:DescribeDBClusters",
        "rds:DescribeDBInstances",
        "sts:TagSession",
        "ssm:DescribeInstanceProperties",
        "ssm:SendCommand",
        "ssm:GetConnectionStatus",
        "ssm:TerminateSession",
        "ssm:StartSession"
      ],
      "Resource": "*"
    }
  ]
}

What's Next

After configuring your additional accounts, see the AWS app configuration guide to complete your integration.