Add AWS to SaaS Agent

Task List

Task 1: Prepare AWS for use with CI Sync

This task explains how to prepare AWS for use with your customer specific instance of CI Sync.

Doing this allows your CI Sync SaaS Agent to authenticate to your AWS so you can run CI Sync jobs between AWS and your CMDB.

1. Setup AWS Config using the 1-Click Setup at https://aws.amazon.com/config/

   

2. Update the Recording settings to Daily recording:

   1. Go To Settings, Under Recorder select Edit

      

      
      

   2. Change Recording frequency to Daily recording

      

3. Within AWS Config, create a new Aggregator for use by CI Sync.

   

4. Setup the new Aggregator as follows:

   1. Select “Allow AWS Config to replicate data….”

   2. Enter a meaningful and univserally unique name (e.g. “CISync-Aggregator”).

5. Select the AWS Source Accounts to be included in the scope of this CI Sync Aggregator.

6. Specify the AWS Region/s to be included in the scope of this CI Sync Aggregator (i.e. the AWS Regions containing the resources that you intend to synchronize into your CMDB).

7. Navigate to the Authorisations page within the new CI Sync Aggregator as shown below.

8. Click the Add Authorization button.

   

9. Review the details:

   1. The Account ID should be your AWS Account ID.

   2. The Aggregator region should be the region in which the AWS Config service was created.

10. When ready, Click the Add Authorization button.  If successful you should see “Authorized” appear for the Authorization Status (this may take a few minutes).

11. Navigate to AWS IAM, create a new user.

12. Enter a meaningful User name such as “CISync-Config-Reader”.

    

13. Using the Set permissions page

    1. Click Attach policies directly

    2. Then click Create policy

       

14. Within the new policy set the following actions only for the Config service:

    1. ListDiscoveredResources

    2. GetAggregateResourceConfig

    3. BatchGetResourceConfig

    4. ListAggregateDiscoveredResources

    5. BatchGetAggregateResourceConfig

15. Ensure the resource policy is scoped appropriately:

    1. Click Add ARNs to open the Specify ARNs dialog box

       

       
       

    2. Specify the aggregator created in Step 4.

16. Once the user is created, you should be redirected the the user list. Open the newly created user and click Create Access Key.
    Note: choose Third-party service as the Use case

    

17. Securely record the generated Access Key and Secret Access Key. 

    

Task 2: (Optional) Grant additional permissions in AWS if using the Extended Relationships feature in CI Sync

Context

The default rules in CI Sync create a variety of CI-to-CI Relationships (sometimes called Dependencies in ServiceNow) between the various resources CI Sync reads from AWS.

Customers can optionally enable a CI Sync Connection Setting that triggers CI Sync to create additional or extended relationships between AWS resources. Please read these pages for more information the default relationships and how to enable extended relationships:

1. For Default Relationships see: Rule 2 - AWS CI-to-CI Relationships

2. For the Connection Setting to enable Extended Relationships see: Extended CI Relationships (CI Dependencies) for AWS

If you will be using the Extended Relationships feature of CI Sync you need to add additional permissions to the CI Sync User account using the AWS portal.

Instructions

1. In AWS, navigate to IAM → Users and open the user created for CI Sync in Task 1 above.
   

   

2. Edit the policy to ensure that it contains the following permissions against * resource:

   "config:ListDiscoveredResources",
   "config:GetAggregateResourceConfig",
   "config:BatchGetResourceConfig",
   "config:ListAggregateDiscoveredResources",
   "config:BatchGetAggregateResourceConfig",
   "sns:ListSubscriptions",
   "sts:AssumeRoleWithWebIdentity",
   "lambda:ListFunctions",
   "lambda:ListFunctionEventInvokeConfigs",
   "lambda:ListEventSourceMappings",
   "lambda:GetPolicy"
   

3. In the JSON view of the Policy editor, it should look like the following:
   

   

   
   

4. The Visual view should look like the following:
   

   

5. Once the permissions have been added to the role, it may take a few minutes for them to apply.

Task 3: Add AWS as a Source System using the CI Sync SaaS UI

1. Login to your CI Sync SaaS instance at https://YourCo.syncfish.app

2. In the CI Sync UI, navigate to Settings > Connections.

3. Find the “SaaS Agent” sub-heading under the Source Connections section. If you don’t see “SaaS Agent” it means your CI Sync instance hasn’t been configured for this feature. Please contact your Sync representative to discuss.

4. On the right hand side of the form, click the +Add button.

5. The New Connection form now appears. Use the Connection Type drop down list to select the source system you wish to add (in this case Amazon Web Services Cloud Platform).

6. Update the fields using these instructions

   1. Connection name

      1. This is a friendly name that represents the source system connection.

      2. The name you enter here will appear when you create a new sync job and are selecting from the available source system list.

      3. Note: Syncfish recommend using a textual suffix on the connection name if for any reason you have setup multiple CI Sync Connections to AWS.

   2. Alias: Please ingore this field (it is not used for the CI Sync Cloud Agent and is being deprecated).

   3. Environments

      1. Select from the available choices Production, Test, or Production/Test (the latter being both).

      2. The selection you make for this field affects which source systems appear when you create a new sync job (i.e. when you are selecting the source system list based on the “Environment” you have chosen for the sync job). See this page for more details on creating a CI Sync job: Run a Small Initial Sync Job (then run more).

      3. FYI: CI Sync allows a source system to be both Production/Test because CI Sync only reads from a source system (it doesn’t write to it). Destination systems can only be Test or Production (not both).

   4. Config Aggregator Name

      1. Paste the Config Aggregator Name captured by your AWS Admin in Task 1 above.

   5. Aggreator Region

      1. Paste the Aggregator Region captured by your AWS Admin in Task 1 above.

   6. Access Key

      1. Paste the Access Key captured by your AWS Admin in Task 1 above.

   7. Secret Access Key

      1. Paste the Secret Access Key captured by your AWS Admin in Task 1 above.

   8. The click the Consent to update fields checkbox.

   9. Finally click the Create connection button.

You will be returned to the main settings screen and your new source system connection will appear in the list as shown below.

Task 4: Check status of new AWS Source System connection

1. To check the status of the newly added AWS Source System connection click the green Check Status link. This will test whether your CI Sync AWS connection can successfully reach and authenticate to the AWS Entra ID defined in the connection itself.

2. 

   If the connection is successful, you will see a green dot next to the source connection name.

3. 

   To test again in the future, you can click the green Refresh Status button.

4. If the test is unsuccessful, you will see a red dot next to the source connection name and an error message underneath. If you need assistance resolving an error, please contact Syncfish support.

This means you are ready to run a sync job using the new source connection using these high-level instructions: Run a Small Initial Sync Job (then run more).

Task 5: Perform Updates in ServiceNow (if required)

In this section your ServiceNow SME will assess various updates to ServiceNow to support this CI Sync connector:

• Task 5a: Assess if the CMDB CI Class Models plug-in is required

• Task 5b: Assess if additional permissions are required

• Task 5c: (Optional though recommended) Assess your ServiceNow CI forms and update to include additional Related Lists

Task 5a: Assess if the CMDB CI Class Models plug-in is required

Context

A number of record sets (asset types/resource types) available to sync using the AWS Connector rely upon CMDB CI Classes that are only available via the CMDB CI Class Models plug-in. 

You therefore need to install the CMDB CI Class Models plug-in to your ServiceNow instance.

If you already have the plug-in you may want to upgrade it to the latest version (as ServiceNow occasionally updates the plug-in to include extra CI Classes/tables).

Instructions

Follow these steps to add this plug-in (and similar steps to locate it and upgrade it if required):

1. Assess the use/inclusion of this plug-in within your ServiceNow (ensure you are comfortable installing this plug-in).

2. Search for Plugins via the ServiceNow navigation menu.

3. Locate the CMDB CI Class Models plug-in.

4. Click Add -> Install and follow the instructions provided.

Task 5b: Assess if additional permissions are required

Use Case - If you are planning to use CI Sync to write AWS Tags to the CMDB

Context

CI Sync writes AWS Tags to the cmdb_key_value table in ServiceNow.

The standard/out-of-the-box roles provided by ServiceNow (and recommended by Syncfish during S3 - Configure ServiceNow for CI Sync) do not provide access to the cmdb_key_value table. Therefore, the CI Sync Integration User account created during S3 - Configure ServiceNow for CI Sync requires additional permissions to write to the cmdb_key_value table.

Syncfish provides a ServiceNow updateset to prepare your ServiceNow instance for CI Sync. The updateset does the following:

• Creates a read/write ACL on the cmdb_key_value table.

• Applies the ACL on the cmdb_key_value table and assigns the ACL to the ServiceNow role called “Asset” (which is one of the roles granted to the CI Sync Integration Account created during S3 - Configure ServiceNow for CI Sync).

Instructions

Follow these steps to apply the updateset provided by Syncfish:

1. Download the update set from Syncfish at the below URL:
   https://downloads.syncfish.app/servicenow/cisync-cmdb-key-value.xml

2. Login to your ServiceNow instance with Admin permissions.

3. Open a browser and navigate to your ServiceNow instance

4. In the left nav menu search for “Retrieved Update Sets” and click to open

5. Right click on the column heading row and select “Import XML”

6. Select “Choose File”

7. Select the downloaded file “cisync-cmdb-key-value.xml”

8. Click to open the Update Set

9. Click “Preview Update Set”

10. If there are no preview errors, Click “Close”.

11. Click “Commit Update Set”.

12. Your ServiceNow instance is now ready to receive Tag data from AWS via sync jobs from CI Sync.

Task 5c: (Optional though recommended) Assess your ServiceNow CI forms and update to include additional Related Lists

Context

CI Sync populates various child tables (related lists) associated with parent CIs. The following table shows the Related Lists (per CI Class) populated by the CI Sync AWS Connector.

Instructions

Below are the steps to modify a ServiceNow CI form to expose a new Related List.

1. Login to your ServiceNow instance with Admin permissions.

2. Navigate to any CI in the relevant CI Class (i.e. one/all of those listed in the table in the Context section above). For example, navigate to a Windows Server CI).

3. Right-click in the heading area of the form, then click Configure and then Related Lists from the sub-menus.

4. Identify the Related List you want to expose on the CI form using the table in the Context section above.

5. Find the Related List in the left hand column which lists all Available Related Lists.

6. Click the Related List and then click add (the selection arrow) to move the item to the Selected column and then click Save.

7. Repeat for each additional CI Class listed in the table in the Context section above.