To set up an integration:
1. Navigate to the Integrations page.
2. Click the AWS logo.
3. Click the Create account button..
4. Provide the name for the integration you are creating by filling in the Account name field at the top of the page.
5. Choose how you want Ardoq to authenticate with your AWS account. We current support these types of authentication:
authenticate with an AWS account
authenticate with AWS Assume Role service
5.1. To authenticate with an AWS account you will need to share your AWS account's credentials with Ardoq by selecting the Username/secret radio button and filling in the Username and Secret text fields. We recommend that you setup a separate AWS account from your main AWS account. That will allow you to provide a tailored set of policies and to comfortably share the "secret" with Ardoq.
We recommend a restricted set of policies for the AWS account you are planning to use for the integration. Here's a JSON example of such policies:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"ec2:DescribeRegions",
"ec2:DescribeVpcs",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeSecurityGroups",
"ec2:DescribeInstances"
],
"Resource": "*",
"Condition": {
"StringLike": {
"aws:RequestedRegion": "eu-central-1"
}
}
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": "elasticloadbalancing:Describe*",
"Resource": "*",
"Condition": {
"StringLike": {
"aws:RequestedRegion": "eu-central-1"
}
}
}
]
}Amazon provides detailed documentation on how to create a policy.
After providing the credentials you will get access to a field called Applicable regions. This is a select box that you will use in the next step.
5.2. The AWS Assume Role service is based on AWS roles and do not require sharing your AWS credentials with Ardoq. Thus it's considered to be a safer approach with more control over the access to your AWS data. In brief, this authentication method allows a specific Ardoq's AWS Role to make AWS API calls on behalf of your AWS role.
To setup the role-based authentication you will need to select the Role based radio button and fill in the Role ID text field. The Role ID is your AWS role that you have setup for integration with Ardoq. Amazon has detailed documentation describing the process of creating a role.
Please note the additional read-only fields below the Role ID text field. These fields contain the information that will help you to configure your AWS setup:
External ID
This is an additional security measure that we use in order to address the so-called "Confused Deputy Problem". It's an Amazon recommended way of making sure that our users cannot request data that does not belong to them. We generate this External ID for you but you will need it when you're setting up a trust policy for the AWS role you are planning to use for the integration with Ardoq.
Ardoq Role ARN
This is the role that Ardoq will use in order to assume your role. You need this information when you create and attach a trust policy for your role.
Trust Relationship Config Example
This is a JSON example of a trust policy that you will need to setup in your AWS cloud. It is already pre-populated with the correct External ID and Ardoq Role ARN, so you can simply copy it to your clipboard by using the Copy example button. This configuration example is designed to be the minimum viable trust policy configuration needed for the integration to work. Of course, you don't have to use the exact same configuration, so feel free to extend it however you need or create your own from scratch.
Policy Config Example
This is a JSON example of a AWS policy. We have designed this example so that it only contains the actions that we currently need in order for the full AWS integration to work with Ardoq. This policy uses specific actions and only allows the read access. You can use the Copy example button to copy the whole example into your clipboard and use it to quickly setup the correct policy. Please note the Condition sections of the configuration. It limits Ardoq's access only to the specific AWS regions. We recommend using the similar condition to list only the regions you want the integration to work with. Of course, you don't have to use the exact same configuration, so feel free to extend it however you need or create your own from scratch.
The example policy has pros and cons that you should be aware of.
Pros:
it is very specific about what Ardoq's role is allowed to do on behalf of your AWS role
it is restricted to read-only calls
it is restricted to only specific AWS regions
Cons:
due to the specificity of the configuration when Ardoq adds more AWS resources and actions to the integration service you will need to update the related policy config in order to get access to the new features. (However it will not break your existing AWS integration with Ardoq even if you decide not to update the policy).
The alternative configuration example might describe the Action sections like this:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"ec2:Describe*"
],
"Resource": "*",
"Condition": {
"StringLike": {
"aws:RequestedRegion": "eu-central-1"
}
}
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": "elasticloadbalancing:Describe*",
"Resource": "*",
"Condition": {
"StringLike": {
"aws:RequestedRegion": "eu-central-1"
}
}
}
]
}
This example is less restrictive and doesn't require the policy to be updated when we add new EC2 actions to our AWS integration service (you would still need to login into Ardoq and update the integration there anyway). This policy is also less secure and might cause Ardoq to access your data that you did not intend to be accessed, so please take care when you are setting up the policy.
After setting up the role-based authentication you will get the full access to a field called Applicable regions. This is a select box that you will use in the next step.
6. Select Applicable regions.
This field allows you to select the AWS regions you want Ardoq to integrate with. Please makes sure that the AWS account or the AWS role that you've used during the previous steps has access to the regions you would like to select.
Important: If there was an error in the previous steps your Applicable regions select box might look like this:
If that happens please go through the previous steps one more time or reach out to our support team for help.
7. Select Applicable VPCs.
After selecting the AWS regions you get access to the Applicable VPCs select box. The box will only have the VPCs from the selected regions.
8. Save the account by clicking the Save account button.
After everything is correctly setup the Save account button will become active. This lets you know that your integration with AWS is ready and can be saved in Ardoq.
After clicking the Save account button you will be automatically redirected to the Select source data page, where you can specify the Resources you want Ardoq to pull in from your AWS cloud. When you finish selecting the Resources the Fetch data button will become active
9. Fetch data.
Clicking the Fetch data button will bring you to our mapping screen. This is where you tell Ardoq more details about your data in order for Ardoq to automatically create the needed components, fields and references and populate them with the data from your AWS cloud.
10. Follow the same steps as in the Excel- and ServiceNow-importer to map columns to Ardoq-elements. Follow the steps from nr. 7 in https://help.ardoq.com/en/articles/3039454-servicenow-integration