Integration Setup

Integrations

Below is an easy to follow setup guide to get you started with SecurityScout's integrations.

Each geographic location uses a shared VPC connector and public IP address for integrations. You can add the necessary IP address to an allowlist for your integrations.

The IP address for each geographic location is as follows:

  • US: 35.188.19.23

* Due to rate limit issues from Microsoft, their integrations are unable to use the VPC connector.

1. AWS Identity Center

Video walkthrough - Create Role

SecurityScout integrates with your AWS Identity Center account by creating a custom role and trust policy for SecurityScout to assume.

The below steps will outline how to get the AWS Identity Center details we need to setup the integration and how to create the custom role and trust policy.

Get the trust policy from SecurityScout:

  1. Log in to your SecurityScout tenant
  2. Go to the integrations page
  3. Click "Configure" on the AWS Identity Center integration
  4. Copy the entire JSON trust policy from the text box
  5. Keep the configuration modal open

Create a custom role for SecurityScout to assume:

  1. Go to the AWS Management Console for your management account (the one you're using to manage your AWS Identity Center)
  2. Navigate to IAM
  3. Click "Roles" in the left navigation
  4. Click "Create role"
  5. Select "Custom trust policy"
  6. Paste the trust policy you copied from SecurityScout into the "Custom trust policy" text box
  7. Click "Next"
  8. Search for and select the following policies:
    • AWSSSODirectoryReadOnly
    • AWSSSOReadOnly
    • IAMReadOnlyAccess
  9. Click "Next"
  10. Give the role a name (e.g. "securityscout-integration")
  11. Copy the role name and paste it into the "Your AWS Role Name We Assume" field in SecurityScout
  12. (optional) Add a description (e.g. "Role for SecurityScout to access AWS Identity Center")
  13. Click "Create role"

Get your AWS Management Account ID and Region:

  1. Click "IAM Identity Center" at the bottom left of the screen
  2. Click on the region dropdown in the top right corner and identify the region you're in
  3. In the SecurityScout configuration modal, enter the Region into the "AWS Management Account Region" field
  4. Click on the account menu in the top right corner
  5. Copy the Account ID and paste it in the "AWS Management Account ID" field in SecurityScout

Setup the integration in SecurityScout:

  1. Validate that the Account ID, Region, and Role name are entered correctly, then click "Connect"

2. CrowdStrike

Video walkthrough - Create API Client

Create an API client:

  1. With an admin account, go to your CrowdStrike tenant, e.g. https://us-1.console.crowdstrike.com
  2. Click "Support and resources" -> "API client and keys"
  3. Ensure you are under the "OAuth2 API clients" tab
  4. Click "Create API client"
  5. Enter a name for the client, e.g. "SecurityScout Integration"
  6. Select the below scopes:
    • Hosts - Read
  7. Click "Create"
  8. Copy the credentials:
    • Copy the Client ID
    • Copy the Client Secret
    • Copy the Base URL

Add the credentials to SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the CrowdStrike integration
  3. Enter the Cloud Tenant, e.g. "us-1", that appears in the Base URL which looks like https://api.us-1.crowdstrike.com
  4. Enter the Client ID
  5. Enter the Client Secret
  6. Click "Connect"

3. Google Cloud

Video walkthrough - Create Service Account

SecurityScout integrates with Google Cloud by running as a service account in your organization. To do this, you create a service account, grant it the necessary permissions, create and download json credentials for the service account, and add the credentials to SecurityScout.

With an admin account, go to Google Cloud Console

Create a service account:

  1. Go to "IAM & Admin" -> "Service Accounts"
  2. Click "Create Service Account"
  3. Enter a name and description
  4. Click "Done"

Create a JSON key file:

  1. Copy the email of the service account for later
  2. Click the email of your service account
  3. Go to "Keys" tab
  4. Click "Add Key" -> "Create new key"
  5. Select "JSON" format
  6. Click "Create" (the key file will be automatically downloaded)

Grant organization-level permissions:

  1. Change to organization level (top of hierarchy)
  2. Go to "IAM & Admin" -> "IAM"
  3. Click "Grant Access"
  4. Enter the service account email
  5. Add the following roles:
    • Browser
    • Security Reviewer
  6. Click "Save"

Get the organization ID:

  1. Go to the resource selection dropdown in the top left
  2. Find your organization in the list
  3. Copy the Organization ID

Add the credentials to SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Google Cloud integration
  3. Enter the Organization ID
  4. Paste the contents of the json key file into the "GCP Service Account JSON" field
  5. Click "Connect"

4. Google Workspace

SecurityScout integrates with your Google Workspace organization by logging in with a Google account and granting the necessary permissions. We recommend that you create a unique service account for your integration (e.g. svc-securityscout-integration@your-domain.com).

The account used to setup the integration needs to be a Super Admin.

We recognize this elevated access requirement is not ideal; however, Google Workspace does not provide granular role permissions that allow reading user roles and verified domains. Without these API permissions, several security alerts and visibility features would be unavailable.

We request the minimum necessary read-only permissions, listed below. No additional permissions can be granted to our integration without you reconnecting and explicitly granting them.

Connect to SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Google Workspace integration
  3. Click "Login with Google"
  4. Login with a Super Admin Google account, following the prompts to grant access to:
    • View delegated admin roles for your domain
    • View domains related to your customers
    • View groups on your domain
    • See info about users on your domain

5. Hexnode

Video walkthrough - Get API Key

Get the API key:

  1. Login to your Hexnode portal (e.g. https://{company}.hexnodemdm.com)
  2. Go into the "Admin" tab at the top and "API" on the left hand side
  3. Copy the API key

Add the API key to SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Hexnode integration
  3. Enter the Hexnode domain, e.g. {company}.hexnodemdm.com
  4. Enter the API key
  5. Click "Connect"

6. Jamf

Video walkthrough - Create User

Jamf's API uses a bearer token that is retrieved by sending a user's credentials to the Jamf API. Given this, we recommend that you create a unique user for your integration so that, if a user leaves, the credentials are not revoked.

Create a user:

  1. With an admin account, go to your Jamf portal (e.g. https://{company}.jamfcloud.com)
  2. Go to "Settings"
  3. Under "System", go to "User accounts and groups"
  4. Click "New"
  5. Leave the option at "Create Standard Account" and click "Next"
  6. For the user:
    • Enter a username, e.g. "svc-securityscout-integration"
    • Enter a name, e.g. "SecurityScout Integration"
    • Enter an email, e.g. "securityscout-integration@your-domain.com"
    • Enter a password in the "Password" and "Verify Password" fields (save this password for later)
  7. Go to the Privileges tab
  8. Under "Jamf Pro Server Objects", add the following READ privileges:
    • Advanced Computer Searches
    • Advanced Mobile Device Searches
    • Advanced User Searches
    • Automated device enrollment
    • Computers
    • Device extension attributes
    • Enrollment Profiles
    • Mobile Device Apps
    • Mobile Device Configuration Profiles
    • Mobile Device Enrollment Invitations
    • Mobile Device Managed App Configurations
    • Mobile Device PreStage Enrollments
    • Mobile Devices
    • Users
  9. Click "Save"

Setup the integration in SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Jamf integration
  3. Enter the jamf domain, e.g. {company}.jamfcloud.com
  4. Enter the username and password you created
  5. Click "Connect"

7. Kandji

Video walkthrough - API Token Creation

Log into your Kandji portal (e.g. https://{company_domain}.kandji.io) and follow these steps.

Get your API domain:

  1. Go to Settings (on the left hand side)
  2. Be sure you are on the "General" tab at the top
  3. Scroll to the bottom of the page and look under "Device domains"
  4. Copy your API domain. It is in the format of "{subdomain}.web-api.kandji.io"

Create an API token:

  1. Click on "Access" at the top of the page
  2. Scroll down to find the "API Token" section
  3. Click "Add API Token"
  4. Give your token a name, e.g. "SecurityScout Integration", and description, e.g. "API token for SecurityScout integration"
  5. Click "Create"
  6. Copy the token value immediately - you won't be able to see it again!
  7. Check the "I have copied the token" checkbox
  8. Click "Next"
  9. Click "Configure"
  10. Select the below permissions (in red):
    • Device details
    • Device list
    • Device ID
  11. Click "Save"

Setup the integration in SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Kandji integration
  3. Enter the API domain, e.g. {subdomain}.web-api.kandji.io
  4. Enter the API token
  5. Click "Connect"

8. Microsoft Azure

Video walkthrough - App Creation, Subscription Permissions

If you are setting up multiple Microsoft integrations, you can use the same app registration and adjust the permissions as needed.

Create a new app registration:

  1. With an admin account, go to Azure Portal App Registrations
  2. Click "New Application"
  3. Click "Create Your Own Application"
    • Give the application a name
    • Select "Integrate any other application you don't find in the gallery (Non-gallery)"
    • Click Create
  4. In the application settings:
    • Go to Security -> Permissions
    • Click "Application Registration"
    • Click "Add permission"
    • Select "Microsoft Graph"
    • Click "Application Permissions"
    • Add the following permissions:
      • AuditLog.Read.All
      • Directory.Read.All
    • Click "Add Permissions"
  5. Click "Grant admin consent for Default Directory", "Yes", then wait for completion
  6. Go to "Overview":
    • Copy the Application (client) ID from Properties
    • Copy the Directory (tenant) ID
    • Click "Add a client certificate or secret"
      • Click "New client secret"
      • Add description and expiration
      • Click "Add"
      • Copy the Value (this is your secret)

Create an Azure Subscription role:

  1. Go to the Azure Portal Management Groups page with an admin account
  2. Click on the Tenant Root Group (to grant access to all subscriptions)
  3. Click on "Access Control (IAM)"
  4. Click "Add" -> "Add custom role"
  5. Enter the name e.g. "SecurityScout Integration" and click "Next"
  6. Select the role "Reader"
  7. Add the following permissions:
    • Microsoft.Authorization/roleDefinitions/read
    • Microsoft.Authorization/roleAssignments/read
    • Microsoft.Management/managementGroups/read
    • Microsoft.Resources/subscriptions/read
  8. Click "Review + Create"
  9. Click "Create"

Assign the role:

  1. In the "Access Control (IAM)" section, click "Role assignments"
  2. Click "Add" and "Add role assignment"
  3. Select the custom role you just created
  4. Click "Next"
  5. Click "Select members"
  6. Search for and select your app registration
  7. Click "Select"
  8. Click "Review + assign"
  9. Click "Review + assign" again

Setup the integration in SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Microsoft Entra ID integration
  3. Enter the Tenant ID
  4. Enter the Application (App) ID
  5. Enter the App Secret
  6. Click "Connect"

Note: If you receive the error "Tenant is not a B2C tenant and doesnt have premium license":

  1. Go to Microsoft 365 Admin Center
  2. Purchase one "Azure Active Directory Premium P1" license (no need to assign it)
  3. Verify the license appears in your licenses
  4. Return to the app and Force Sync

8. Microsoft Entra ID

Video walkthrough - App Creation

If you are setting up multiple Microsoft integrations, you can use the same app registration and adjust the permissions as needed.

Create a new app registration:

  1. With an admin account, go to Azure Portal App Registrations
  2. Click "New Application"
  3. Click "Create Your Own Application"
    • Give the application a name
    • Select "Integrate any other application you don't find in the gallery (Non-gallery)"
    • Click Create
  4. In the application settings:
    • Go to Security -> Permissions
    • Click "Application Registration"
    • Click "Add permission"
    • Select "Microsoft Graph"
    • Click "Application Permissions"
    • Add the following permissions:
      • AuditLog.Read.All
      • Directory.Read.All
      • UserAuthenticationMethod.Read.All - Required to check MFA enablement on the account.
    • Click "Add Permissions"
  5. Click "Grant admin consent for Default Directory", "Yes", then wait for completion
  6. Go to "Overview":
    • Copy the Application (client) ID from Properties
    • Copy the Directory (tenant) ID
    • Click "Add a client certificate or secret"
      • Click "New client secret"
      • Add description and expiration
      • Click "Add"
      • Copy the Value (this is your secret)

Setup the integration in SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Microsoft Entra ID integration
  3. Enter the Tenant ID
  4. Enter the Application (App) ID
  5. Enter the App Secret
  6. Click "Connect"

Note: If you receive the error "Tenant is not a B2C tenant and doesnt have premium license":

  1. Go to Microsoft 365 Admin Center
  2. Purchase one "Azure Active Directory Premium P1" license (no need to assign it)
  3. Verify the license appears in your licenses
  4. Return to the app and Force Sync

9. Microsoft Intune

Video walkthrough - App Creation

If you are setting up multiple Microsoft integrations, you can use the same app registration and adjust the permissions as needed.

Create a new app registration:

  1. With an admin account, go to Azure Portal App Registrations
  2. Click "New Application"
  3. Click "Create Your Own Application"
    • Give the application a name
    • Select "Integrate any other application you don't find in the gallery (Non-gallery)"
    • Click Create
  4. In the application settings:
    • Go to Security -> Permissions
    • Click "Application Registration"
    • Click "Add permission"
    • Select "Microsoft Graph"
    • Click "Application Permissions"
    • Add the following permissions (user related permissions are to map the user information to the device):
      • Device.Read.All
      • DeviceManagementManagedDevices.Read.All
      • Directory.Read.All
      • User.Read.All
    • Click "Add Permissions"
  5. Click "Grant admin consent for Default Directory", "Yes", then wait for completion
  6. Go to "Overview":
    • Copy the Application (client) ID from Properties
    • Copy the Directory (tenant) ID
    • Click "Add a client certificate or secret"
      • Click "New client secret"
      • Add description and expiration
      • Click "Add"
      • Copy the Value (this is your secret)

Setup the integration in SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Microsoft Intune integration
  3. Enter the Tenant ID
  4. Enter the Application (App) ID
  5. Enter the App Secret
  6. Click "Connect"

Note: If you receive the error "Tenant is not a B2C tenant and doesnt have premium license":

  1. Go to Microsoft 365 Admin Center
  2. Purchase one "Azure Active Directory Premium P1" license (no need to assign it)
  3. Verify the license appears in your licenses
  4. Return to the app and Force Sync

10. Okta

We recommend that you make the API key under a unique service account for your integration (e.g. svc-securityscout-integration@your-domain.com) so that, if a user leaves, the API key is not revoked.

Create the new user:

  1. With an admin account, go to the Okta Admin Console (e.g. https://companyname-admin.okta.com/admin/dashboard)
  2. Navigate to Directory -> People
  3. Click "Add Person"
  4. Select "Create New User"
  5. Enter the new user's First Name, Last Name, Username and Primary email.
  6. Ensure "Activate now" is selected
  7. Select "I will set password"
  8. Enter a password and be sure to save it
  9. Click "Save"

Create a new Resource (if you don't have one already):

  1. With an admin account, go to the Okta Admin Console (e.g. https://companyname-admin.okta.com/admin/dashboard)
  2. Navigate to Security -> Administrators
  3. Go to the "Resources" tab
  4. Click "Create new resource set"
  5. Enter a name, e.g. "{Company Name}"
  6. Click "Add resources"
  7. Add the following resources:
    • Users - All users
    • Groups - All groups
    • Identity and Access Management - All Identity and Access Management resources
  8. Click "Create"

Create a new role for the user:

  1. With an admin account, go to the Okta Admin Console (e.g. https://companyname-admin.okta.com/admin/dashboard)
  2. Navigate to Security -> Administrators
  3. Go to the "Roles" tab
  4. Click "Create new role"
  5. Give the role a name, e.g. "SecurityScout Read Only"
  6. Select the following permissions:
    • View users and their details
    • View groups and their details
    • View roles, resources, and admin assignments
  7. Click "Save role"
  8. Find the role you just created, click "Edit" on the right side and "View or edit assignments"
  9. Under "Admin" select the user you just created
  10. Under Resource Set, select the resource set you just created or the appropriate one
  11. Click "Save Changes"

Grant the user TEMPORARY Organization Administrator access (needed to create the API token)

  1. With an admin account, go to the Okta Admin Console (e.g. https://companyname-admin.okta.com/admin/dashboard)
  2. Navigate to Security -> Administrators
  3. Go to the "Roles" tab
  4. Find the "Organization Administrator" role, click "Edit" on the right side and "View or edit assignments"
  5. Under "Select Admin" select the user you just created
  6. Click "Save Changes"

Login in as the new user and follow these steps to create the API token:

  1. Login as the user you just created, go to the Okta Admin Console (e.g. https://companyname-admin.okta.com/admin/dashboard)
  2. Navigate to "Security" and "API"
  3. Be sure you are on the "Tokens" tab
  4. Click "Create Token"
  5. Give your token a meaningful name (e.g. "SecurityScout Integration")
  6. Select that API calls can be made from "Any IP"
    • Optional: Use a zone with the geographic IP address at the top of the page to restrict where the token can be used from
  7. Copy the token value immediately - you won't be able to see it again!

Setup the integration in SecurityScout:

  1. Go to the integrations page
  2. Click "Configure" on the Okta integration
  3. Enter the corporate email domain, i.e. the domains of emails that will exist in your Okta instance, e.g. @yourdomain.com (used for identifying existing users)
  4. Enter the Okta domain, e.g. yourdomain.okta.com (used for API calls)
  5. Enter the API token
  6. Click "Connect"

Remove Organization Administrator access

  1. With an admin account, go to the Okta Admin Console (e.g. https://companyname-admin.okta.com/admin/dashboard)
  2. Navigate to Security -> Administrators
  3. Go to the "Roles" tab
  4. Find the "Organization Administrator" role, click "Edit" on the right side and "View or edit assignments"
  5. Click the trash icon to remove the user
  6. Click "Save Changes"