Liongard Roar

Roar Users Guide & Documentation

Welcome! You'll find comprehensive guides and documentation to help MSPs start working with Liongard's Roar as quickly as possible, as well as support if you get stuck. Let's go #MakeITRoar!

Get Started    

G Suite

This document provides the steps required to configure the Google G Suite Inspector.

Quick Details:

Typically Runs From: Managed Cloud Agent
Is Auto-Discovered By: N/A
Can Auto-Discover: Google G Suite Child Inspectors (Google Partners)
Parent/Child Type Inspector: Yes

Inspector Setup Preparation

Step 1: Google Cloud Platform (GCP)

A portion of the Inspector setup process has been automated via Google Cloud Shell, a free service provided in the Google Cloud Platform. The script included below creates a new project for the Inspector, enables the required APIs, creates a service account, and adds all required IAM roles. It also creates and prompts you to download a secret key file which you'll need later on in the setup process.

  1. Click the button below. Doing so will prompt you to log into Google Cloud Platform, launch a Google Cloud Shell session, and clone our Git repository containing the setup script:

Open in Cloud Shell

You can also copy and paste this script into Google Cloud Shell manually:

#!/bin/bash
if gcloud projects list | grep -q 'liongard-g-suite-inspector'; then
  echo "Project already exists, continuing on..."
else
  while true; do
    read -p "This script will configure a new Google Cloud Platform project. Do you want to proceed? [y/n] " yn
    case $yn in
      [Yy]* ) break;;
      [Nn]* ) echo 'Exiting...' && exit;;
      * ) echo "Please answer yes or no.";;
    esac
  done
  
  echo "(Step 1) - Creating Project"
  gcloud projects create liongard-g-suite-inspector
  if [ $? -ne 0 ]; then
   echo "Error - Failed to create project."
   exit 1
  else 
    echo "Successfully created project."
    gcloud config set project liongard-g-suite-inspector
  fi
fi

echo "(Step 2) - Enabling APIs"
if gcloud services list --enabled | grep -q 'admin.googleapis.com'; then
  echo "Admin SDK API already enabled, continuing on..."
else
  echo "Enabling Admin SDK API"
  gcloud services enable admin.googleapis.com
  if [ $? -ne 0 ]; then
    echo "Error - Failed to enable Admin SDK API"
    exit 1
  else
    echo Successfully enabled Admin SDK API.
  fi
fi

if gcloud services list --enabled | grep -q 'licensing.googleapis.com'; then
  echo "Enterprise License Manager API already enabled, continuing on..."
else
  echo "Enabling Enterprise License Manager API"
  gcloud services enable licensing.googleapis.com
  if [ $? -ne 0 ]; then
    echo "Error - Failed to enable Enterprise License Manager API"
    exit 1
  else
    echo Successfully enabled Enterprise License Manager API.
  fi
fi

if gcloud services list --enabled | grep -q 'reseller.googleapis.com'; then
  echo "Reseller API already enabled, continuing on..."
else
  echo "Enabling Reseller API"
  gcloud services enable reseller.googleapis.com
  if [ $? -ne 0 ]; then
    echo "Error - Failed to enable Reseller API"
    exit 1
  else
    echo Successfully enabled Reseller API.
  fi
fi

echo "(Step 3) - Creating Service Account"
if gcloud iam service-accounts list | grep 'liongard-service-account'; then
  echo "Service account already created, continuing on..."
else
  echo "Creating service account"
  gcloud iam service-accounts create liongard-service-account --display-name "Liongard Service Account"
  if [ $? -ne 0 ]; then
    echo "Error - Failed to create service account."
    exit 1
  else
    echo "Successfully created service account."
    EMAIL=$(gcloud iam service-accounts list --filter 'liongard-service-account' --format='value(email)')
    if [ -z "$EMAIL" ]; then
      echo "Error - Failed to fetch service account email address"
      exit 1
    fi
  fi
fi

echo "(Step 4) - Assigning Service Account IAM Roles"
if gcloud iam service-accounts get-iam-policy $EMAIL --flatten="bindings[].members" --filter="bindings.members:$EMAIL" | grep 'roles/iam.serviceAccountUser'; then
  echo "'Service Account User' role already added, continuing..."
else
  gcloud iam service-accounts add-iam-policy-binding $EMAIL --member serviceAccount:$EMAIL --role roles/iam.serviceAccountUser
  if [ $? -ne 0 ]; then
    echo "Error - Failed to assign service account IAM roles."
    exit 1
  else
    echo "Successfully assigned service account IAM roles."
  fi
fi

if gcloud iam service-accounts get-iam-policy $EMAIL --flatten="bindings[].members" --filter="bindings.members:$EMAIL" | grep 'roles/iam.serviceAccountTokenCreator'; then
  echo "'Service Account Token Creator' role already added, continuing..."
else
  gcloud iam service-accounts add-iam-policy-binding $EMAIL --member serviceAccount:$EMAIL --role roles/iam.serviceAccountTokenCreator
  if [ $? -ne 0 ]; then
    echo "Error - Failed to assign service account IAM roles."
    exit 1
  else
    echo "Successfully assigned service account IAM roles."
  fi
fi

echo "(Step 5) - Creating key"
gcloud iam service-accounts keys create --iam-account $EMAIL secret_key.json
if [ $? -ne 0 ]; then
  echo "Error - Failed to create key."
  exit 1
else 
  echo "Successfully created key."
fi

while true; do
  read -p "Do you want to download the key you just created? [y/n] " yn
  case $yn in
    [Yy]* ) sleep 1 && cloudshell download secret_key.json; break;;
    [Nn]* ) exit;;
    * ) echo "Please answer yes or no.";;
  esac
done

echo "Done."
  1. Once you've copied the script, simply run sh setup.sh to invoke the script.

  2. Once the script completes, navigate to the IAM & Admin section, and select Service accounts. Then, click Edit under the Actions menu for the service account you just created.

  1. Click Show Domain-Wise Delegation, and select the box for Enable G Suite Domain-wide Delegation.

You will be prompted to configure an OAuth consent screen. Once you've done so, navigate to the bottom of the page and click Save. Your service account has now been assigned a client.

Client ID

Make note of the Client ID associated with your service account, as you'll use it when granting the application API scopes within G Suite.

Step 2: Google G Suite Admin Portal

  1. Once you've completed the steps above, navigate to the G Suite Admin console and log into your G Suite account as a domain administrator.

  2. Navigate to Security from the list of visible controls. Then, select Advanced settings > Manage API client access.

  1. Under Client Name, enter the Client ID from the Google Cloud Platform portion of the setup process. Under One or More API Scopes, copy and paste the following comma-delimited list of API scopes:
https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly,
https://www.googleapis.com/auth/admin.directory.group.member.readonly,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/admin.directory.orgunit.readonly,
https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.directory.user.alias.readonly,
https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,
https://www.googleapis.com/auth/admin.directory.userschema.readonly,
https://www.googleapis.com/auth/admin.directory.customer.readonly,
https://www.googleapis.com/auth/admin.directory.domain.readonly,
https://www.googleapis.com/auth/admin.directory.device.mobile.readonly,
https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly,
https://www.googleapis.com/auth/admin.reports.audit.readonly,
https://www.googleapis.com/auth/admin.reports.usage.readonly,
https://www.googleapis.com/auth/apps.order.readonly,
https://www.googleapis.com/auth/calendar.readonly,
https://www.googleapis.com/auth/calendar.events.readonly,
https://www.googleapis.com/auth/calendar.settings.readonly,
https://www.googleapis.com/auth/drive.readonly,
https://www.googleapis.com/auth/drive.activity.readonly,
https://www.googleapis.com/auth/apps.licensing
  1. Finally, select Authorize to grant the listed API scopes on your Google G Suite account to the application you created.

Roar Inspector Setup

Step 1: Parent Inspector Setup

Since G Suite is a multi-tenant system where a single portal is used to manage many Environments, you will set up a single "Parent" Inspector that will then auto-discover "Child" Inspectors for each Environment.

In Roar, navigate to Admin > Inspectors > Navigate to the Google G Suite Inspector > Add System.

Fill in the following information:

  • Environment: Select the Environment this System should be associated to
  • Friendly Name: Suggested "[Environment Name] G Suite"
  • Agent: Select Cloud-Linux
  • G Suite Admin Email: Email of a Domain Administrator on the Google G Suite account to be inspected under G Suite Admin Email
  • Private Key: The contents of the Service Account Secret Key file you created during the Google Cloud Platform (GCP) portion of the setup process.
  • Enable Google G Suite Reseller API: If you're enrolled as a Google G Suite Authorized Reseller, select this option to enable auto-discovery.
  • Scheduling: The Inspector will default to run once a day at the time the Inspector is set up. Here you can adjust the schedule
  • Inspector Version: Latest
    Select Save. The Inspector will now be triggered to run within the minute.

Step 2: Child Inspector Setup

After the first run of the Parent Inspector, your client G Suite organizations will be Auto-Discovered in the Discovered Systems tab on the Inspectors > G Suite page.

Navigate to the Discovered Systems tab in your Inspectors > G Suite page

  • Activate or Archive your Discovered Systems by ensuring that they're mapped to the correct Environment > Check the checkbox to the left of Inspector(s) > Select the Actions drop down menu > Activate Launchpoints

Troubleshooting

This section documents some common errors you may run into and how to resolve them.

  • Error Message: "Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested."
  • Potential Cause/Resolution: This error generally indicates that your client (application) isn't sufficiently authorized to perform some action in Google Cloud Platform.
    Check the following:
    • Check that "Domain-wide delegation" is enabled for your service account in the Google Cloud Platform console. This is included under Step #9* in the GCP portion of the setup process. For more information, reference this article from Google Cloud Platform's developer documentation
    • Check that the scopes included in this document are properly entered in the G Suite Admin Console and that those scopes are associated with the Client ID of the service account you created. This is included under Step #4 in the G Suite portion of the setup process.
    • Ensure that the "Service Account Token Creator" and "Service Account User" IAM roles are assigned to your service account.

Last Updated: 2019-01-16

Updated 4 days ago

G Suite


This document provides the steps required to configure the Google G Suite Inspector.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.