SG-AWS Identity and Access Management: Setup, guidelines, and troubleshootingReleaseService Graph Connector for AWS v2.0 and aboveInstructionsThis document's purpose is to cover what the IAM setup for ServiceGraph Connector for AWS looks like. Variations on the setup are possible as well. Another purpose of this document is to provide guidelines for troubleshooting, by comparing your IAM setup with the one described here. Tips are often highlighted in red. IAM Identity It represents a human or a program that is authenticated and then authorized to perform actions. Example: user, user-group, role.User represents an entity which interacts and performs actions on AWS. Generally has fixed credentials. Group set of users.Role similar to user, but more ephemeral. Can not be “owned” by a single entity. Provides creds for a single session.Policies are specific permissions on what actions can an entity perform. 1. AWS IAM Users An IAM User in AWS represents a ServiceNow Instance User (hereafter referred as snow.user) There should be a valid user ('principal') in the AWS IAM console. This user has a unique access key/secret key which are to be entered into our ServiceNow Instance. Important note: this user is created in either the management account or a "designated account." IAM users can be associated with policies (i.e. permissions that specify what actions are allowed). But instead of attaching permissions to a single user, we attach permissions to user-groups, and we make the users a part of the group. 2. Groups and Policies The user from the previous step should belong to a group similar to this one below. The group in turn is associated with two policies. 1. SnowMemberAccountAccessPolicy A member of this group can call the API sts:AssumeRole (to obtain the SnowOrganizationAccountAccessRole) in any account in this org. If this policy is absent the snow.user will be unable to call any AWS API. This API is extremely critical. Debugging note: if you call the STS Assume Role API and get errors saying HTTP 40x AssumeRole call has failed, please check if this policy is attached to the user-group. Verify if the user belongs to the correct group. Verify if the credentials being used for the servicenow user (snow.user) are correct. 2. SnowAccountAccessPolicy This policy is required so that the snow.user can call these basic APIs listed in the policy below. The ones starting with organizations:* are the most critical. There is no substitute to these, we use it to get CI info for our most fundamental datasources. Not attaching this policy will cause the connector to not get any CIs at all. Please note again: the setup shown above (the snow.user, and the groups and their policies) should be done in the management or designated admin aws account. Debugging note: If you are able to call STS AssumeRole API, but the ListAccounts API call is failing in the diagnostic tool, and you're hardly getting any CIs, please check if this policy "SnowAccountAccessPolicy" is present in the management account (or the designated account). This policy should be there in the account where you have created the servicenow user (snow.user). Also, as mentioned before this policy should attached to the correct group, and the group should have the snow.user. 3. Roles: SnowOrganizationAccountAccessRole We know it's not the best idea to attach policies to a user directly. Sure, we saw above that we attach policies to a user-group, and then all the users of that group get access to the resources (specified in the policy) as long as they are a part of the group. But what if we want to give a user temporary permissions, what do we do? How do we give them temporary access in AWS? We uses roles. Important: this role should be in all AWS accounts from which we want CI information from. It is critical to setup this role correctly and it should also have the associated policy (discussed below) and a valid trust relationship. The associated policy - SnowOrganizationAccountAccesPolicy (critical) This policy is the critical policy which lists out all the APIs that snow.user (i.e our servicenow instance) will be able to call. Here is what the policy should look like: { "Version": "2012-10-17", "Statement": [ { "Action": [ "organizations:DescribeOrganization", "organizations:ListAccounts", "config:DescribeConfigurationAggregators", "config:ListDiscoveredResources", "config:SelectAggregateResourceConfig", "config:BatchGetAggregateResourceConfig", "config:SelectResourceConfig", "config:BatchGetResourceConfig", "ec2:DescribeRegions", "ec2:DescribeImages", "ec2:DescribeInstances", "ec2:DescribeInstanceTypes", "ssm:DescribeInstanceInformation", "ssm:ListInventoryEntries", "ssm:GetInventory", "ssm:SendCommand", "s3:GetObject", "s3:DeleteObject", "tag:GetResources", "iam:CreateAccessKey", "iam:DeleteAccessKey" ], "Resource": "*", "Effect": "Allow", "Sid": "ServiceNowUserReadOnlyAccess" }, { "Action": [ "ssm:SendCommand" ], "Resource": [ "arn:aws:ec2:*:*:instance/*", "arn:aws:ssm:*:*:document/SG-AWS-RunShellScript", "arn:aws:ssm:*:*:document/SG-AWS-RunPowerShellScript" ], "Effect": "Allow", "Sid": "SendCommandAccess" }, { "Action": [ "s3:GetObject", "s3:GetBucketLocation", "s3:ListBucket", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::servicenow-INSERT_YOUR_S3_BUCKET_NAME-us-east-2/*" ], "Effect": "Allow", "Sid": "S3BucketAccess" } ]} The Trust Relationship The trust relationships specify who can call this particular role. And in our case it is scoped to any principal in the management account: { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::900******122:root" }, "Action": "sts:AssumeRole" } ]} Debugging note: if there are particular accounts from which you are not getting the CI information from, please check if you have the Role (SnowOrganizationAccountAccessRole) and Policy (SnowOrganizationAccountAccesPolicy) in that particular account. Note on designated vs management account: the setup above has assumed that we are setting up the snow user in management account. If you're setting it up in a designated member account it is slightly different. In that case: create the snow user in the member account. Setup the IAM Role (SnowOrganizationAccountAccessRole) and policy (SnowOrganizationAccountAccesPolicy) in management account. After that create a trust relationship making sure that the snow.user created in designated account can call assume the iam role in the management account. 4. S3 buckets: Instance Profiles and Bucket Policy Our SSM-SendCommand and EKS-Full data sources leverage S3 buckets to store and retrieve data. We want to limit access to this bucket as well. There are EC2 machines from which we are gathering this deep discovery data, and we want only these particular machines to be writing (or performing other operations on our bucket). So a role (instance-profile) is attached to the EC2 machines. As you can see, like any other role, it also has policies and trust relationships. The policy (shown below) allows the principal to perform PutObject, GetObject, and PutObjectAcl on the S3 bucket specified in the policy. The trust relationship which specifies which entity can assume the role is attached below. It implies that only EC2 machines are the trusted entities who can assume this role. Bucket Policies The S3 buckets too are secured. We specify in the bucket that which instance-profile can perform any action on them. A sample has been attached below, Related articles: ServiceNow 1. Service Graph Connector for AWS - Introduction 2. Service Graph Connector for AWS - Diagnostic Tool & Troubleshooting Issues 3. Service Graph Connector for AWS - FAQ AWS 1. AWS IAM Identities https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html 2. AWS STS AssumeRole https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html Related LinksThis is not an exhaustive list, it describes the minimum setup required for the connector to work. More documentation and guides to follow. Please reach out to me if you have any questions, or doubts, or for any corrections or addendums to this document.