Initial Setup¶

Getting started with PSGSuite.

Prerequisites¶

In order to use this module, you will need the following:

PowerShell 4.0+ or PowerShell Core 6+
G Suite account (SuperAdmin needed for full functionality of the module)

Installing the Module¶

From the PowerShell Gallery¶

Installing items from the Gallery requires the latest version of the PowerShellGet module, which is available in Windows 10, in Windows Management Framework (WMF) 5.0, or in the MSI-based installer (for PowerShell 3 and 4).

This will be slightly behind the GitHub repo. Please see below for installation instructions from the GitHub repo.

Open Powershell and run the following command:

PowerShell

Install-Module -Name PSGSuite -Scope CurrentUser

For more information, please visit the PSGSuite page on the Powershell Gallery

From the GitHub release page¶

This will be equal to the Powershell Gallery, usually

IMPORTANT: You MUST have the module 'Configuration' installed as a prerequisite! Installing the module from the repo source or the release page does not automatically install dependencies!!

Click here to go to the latest releases, then download the PSGSuite.zip file attached to the release
Right-click the downloaded zip, select Properties, then unblock the file. This is to prevent having to unblock each file individually after unzipping.
Unzip the archive.
(Optional) Place the module somewhere in your PSModulePath.
- You can view the paths listed by running the environment variable $env:PSModulePath

Build from the GitHub repo¶

Bleeding edge fans, contributors, etc

IMPORTANT: You MUST have the module 'Configuration' installed as a prerequisite! Installing the module from the repo source or the release page does not automatically install dependencies!!

Clone the repo to your computer: git clone https://github.com/scrthq/PSGSuite.git
Open the cloned directory: cd PSGSuite
Build the module: .\build.ps1

To import the compiled module in a new session, run this from the repo root:

Import-Module ./BuildOutput/PSGSuite -Force

G Suite Users with SuperAdmin access¶

Creating the Project, Service Account and P12 Key in Google's Developer Console¶

Click here to create a new project with the following API's enabled:
- Admin SDK
- Apps Activity API
- Contacts API
- Drive Activity API (Apps Activity API v2)
- Enterprise License Manager API
- Gmail API
- Google Calendar API
- Google Classroom API
- Google Docs API
- Google Drive API
- Google Sheets API
- Google Slides API
- Groups Settings API
- Hangouts Chat API
- People API
- Tasks API
Leave the dropdown set to 'Create a project' and click the blue 'Continue' button.
- If you encounter an error stating that You may not have permission to create projects in this organization. Contact your Google Apps account admin to verify you have the Project Creator role., you may need to manually create a project instead as noted in Issue #116. If you are still unable to create a project manually, you will need to contact your domain's G Suite administrators to have them place you in the Project Creator role or create the project for you.
On the next screen, it will run the wizard to assist in adding credentials. Click the blue link that says 'service account' right above the 'Which API are you using?' question to go to the Service Account Creation page.
On the Service Accounts page, click the blue button on the top of the screen to 'CREATE SERVICE ACCOUNT' and you'll be walked through the following 3 pages:
- Service account details:
  1. Set the service account name to whatever you'd like and optionally add a description
  2. Click the CREATE button
- Grant this service account access to this project:
  1. Set the Service Account permissions to Project > Owner
- Grant users access to this service account
  1. Click the CREATE KEY button
  2. Set Key type to P12
  3. Click the blue CREATE button. You should download the P12 key file in your browser once clicking it.
  4. Click the blue DONE button to return to the Service accounts screen.
Click the 3 dots button at the right side of the service account you just created then select Edit.
Click the blue link to SHOW DOMAIN-WIDE DELEGATION.
Check the box to allow Enable G Suite Domain-wide Delegation. You should see additional fields appear for Product Name and Email Address.
Set an appropriate product name (i.e. PSGSuite), then click the blue SAVE button.
Once back on the Service Accounts page, click the link under where it says DwD to 'View Client ID'. You will be taken to a page that lists the AppEmail (e.g. [email protected]) and the ServiceAccountClientID (e.g. 10264827741861193783987). Save these two in a Notepad, you will need them when you fill out the configuration.
Under API Manager >> Library, make sure the following API's are showing as enabled:
- Admin SDK
- Apps Activity API
- Contacts API
- Drive Activity API (Apps Activity API v2)
- Enterprise License Manager API
- Gmail API
- Google Calendar API
- Google Classroom API
- Google Docs API
- Google Drive API
- Google Sheets API
- Google Slides API
- Groups Settings API
- Hangouts Chat API
- People API
- Tasks API

Adding API Client Access in Admin Console¶

Open a new tab or window to the Google Admin Console
Go to Security
Expand 'Advanced Settings'
Click 'Manage API client access'
Take the ServiceAccountClientID you copied to Notepad earlier (e.g. 10264827741861193783987) and paste it in the left field for 'Client Name'
- If you have already set up a PSGSuiteConfig, you can retrieve your ServiceAccountClientId by running (Show-PSGSuiteConfig).ServiceAccountClientId
Copy / paste the following scopes together on the field on the right for 'One or more API scopes':

https://apps-apis.google.com/a/feeds/emailsettings/2.0/,
https://mail.google.com/,
https://sites.google.com/feeds,
https://www.google.com/m8/feeds/contacts,
https://www.googleapis.com/auth/activity,
https://www.googleapis.com/auth/admin.datatransfer,
https://www.googleapis.com/auth/admin.directory,
https://www.googleapis.com/auth/admin.directory.customer,
https://www.googleapis.com/auth/admin.directory.device.chromeos,
https://www.googleapis.com/auth/admin.directory.device.mobile,
https://www.googleapis.com/auth/admin.directory.domain,
https://www.googleapis.com/auth/admin.directory.group,
https://www.googleapis.com/auth/admin.directory.orgunit,
https://www.googleapis.com/auth/admin.directory.resource.calendar,
https://www.googleapis.com/auth/admin.directory.rolemanagement,
https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,
https://www.googleapis.com/auth/admin.directory.user,
https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.directory.user.security,
https://www.googleapis.com/auth/admin.directory.userschema,
https://www.googleapis.com/auth/admin.reports.audit.readonly,
https://www.googleapis.com/auth/admin.reports.usage.readonly,
https://www.googleapis.com/auth/apps.groups.settings,
https://www.googleapis.com/auth/apps.licensing,
https://www.googleapis.com/auth/calendar,
https://www.googleapis.com/auth/chat.bot,
https://www.googleapis.com/auth/classroom.announcements,
https://www.googleapis.com/auth/classroom.courses,
https://www.googleapis.com/auth/classroom.coursework.me,
https://www.googleapis.com/auth/classroom.coursework.students,
https://www.googleapis.com/auth/classroom.guardianlinks.students,
https://www.googleapis.com/auth/classroom.profile.emails,
https://www.googleapis.com/auth/classroom.profile.photos,
https://www.googleapis.com/auth/classroom.push-notifications,
https://www.googleapis.com/auth/classroom.rosters,
https://www.googleapis.com/auth/classroom.rosters.readonly,
https://www.googleapis.com/auth/drive,
https://www.googleapis.com/auth/gmail.settings.basic,
https://www.googleapis.com/auth/gmail.settings.sharing,
https://www.googleapis.com/auth/plus.login,
https://www.googleapis.com/auth/plus.me,
https://www.googleapis.com/auth/tasks,
https://www.googleapis.com/auth/tasks.readonly,
https://www.googleapis.com/auth/userinfo.email,
https://www.googleapis.com/auth/userinfo.profile

Although the module does not use all of these scopes currently, additional functions are being built to leverage this entire list.

Free Google Account Users and G Suite Users without SuperAdmin access¶

If you are not a G Suite super admin or even a G Suite user at all, you can still use PSGSuite for the following APIs:

Contacts API
Gmail API
Google Calendar API
Google Docs API
Google Drive API
Google Sheets API
Google Slides API
People API (new Contacts API)
Tasks API

You will also need to take a slightly different route when creating credentials and create an OAuth Client ID instead of a Service Account and P12 Key.

Creating the Project and Client ID/Secret in Google's Developer Console¶

Click here to create a new project with the following API's enabled:
- Contacts API
- Gmail API
- Google Calendar API
- Google Docs API
- Google Drive API
- Google Sheets API
- Google Slides API
- People API (new Contacts API)
- Tasks API
  
  2. Leave the dropdown set to Create a project and click the blue 'Continue' button. * If you encounter an error stating that You may not have permission to create projects in this organization. Contact your Google Apps account admin to verify you have the Project Creator role., you may need to manually create a project instead as noted in Issue #116. * If you are still unable to create a project manually, you will need to contact your domain's G Suite administrators to have them place you in the Project Creator role or create the project for you. 3. On the next screen, it will run the wizard to assist in adding credentials. Click the blue link that says client ID right above the 'Which API are you using?' question to go to the OAuth Client ID Creation page: 4. On the OAuth Client ID creation page, click the blue button on the top of the screen to Configure consent screen: 5. On the OAuth consent screen... 1. Set the Application Name. This is what you will see when authorizing the Console Project access to you data via API. 2. Under Scopes for Google APIs, click the Add scope button. 3. Check the check box on the top-left of the pop-up to check all of the boxes, then click Add on the bottom-right of the pop-up. 4. Scroll to the bottom of the OAuth consent screen, the click the blue Save button. 6. Once saved, scroll up to the top of the page then click the main Credentials tab. 7. Click the drop-down button to Create credentials, then select OAuth client ID. 8. Choose Other as the Application type and enter a friendly name such as PSGSuite, then click the blue Create button: 9. Once created, you'll get a pop-up with the client_id / client_secrets info, just click ok to close the pop-up: 10. Once back on the Credentials screen, click the ⬇️ icon on the far right next to your new OAuth Client ID to download the client_secrets.json file to your preferred location:

Creating the PSGSuite Configuration File¶

Import the module:
- Module located in PSModulePath: Import-Module PSGSuite
- or somewhere else: Import-Module C:\Path\To\PSGSuite\PSGSuite.psd1
Have the following information available to paste during Step 3:
- G Suite SuperAdmins
  - P12KeyPath: This is the full path to the P12 file that you created during Step 9 of Creating the Project, Service Account and P12 Key in Google's Developer Console
  - AppEmail: This is email address for the service account created earlier. It will look something like this:
    - {service account name}@{project name}.iam.gserviceaccount.com
  - AdminEmail: This is email address for the SuperAdmin account that created the project (usually your email)
  - CustomerId: This is the Customer ID of the G Suite account. If you do not know it currently, you can set it later. After importing the module, you can run (Get-GSUser).CustomerId and view the Customer ID in the response.
  - Domain: This is the primary domain name for the customer, i.e. scrthq.com
  - Preference: This is referenced by certain functions that allow either the Customer ID or Domain to be queried against. You can choose between "CustomerID" or "Domain" for this value.
  - Service Account Client ID: This stores the Service Account Client ID to allow easy callback without having to open the project page. It is purely a convenience parameter. The Service Account Client ID is the large integer that you copy during Steps 7 & 8 while Adding API Client Access in Admin Console
- Free account / G Suite standard users > Free accounts only need 2 pieces of information in a config for PSGSuite to work with the APIs available to them: ClientSecretsPath and AdminEmail.
  - ClientSecretsPath: This is the full path to the JSON file that you downloaded during Step 10 of Creating the Project and Client ID/Secret in Google's Developer Console
  - AdminEmail: This is the email address for your account.

Run the appropriate command from the following to create the config file using the values from Step 2 of this section to replace the variables below:

G Suite SuperAdmins

Set-PSGSuiteConfig -ConfigName MyConfig -SetAsDefaultConfig -P12KeyPath $P12KeyPath -AppEmail $AppEmail -AdminEmail $AdminEmail -CustomerID $CustomerID -Domain $Domain -Preference $Preference -ServiceAccountClientID $ServiceAccountClientID

Free account / G Suite standard users

Set-PSGSuiteConfig -ConfigName MyConfig -SetAsDefaultConfig -ClientSecretsPath $ClientSecretsPath -AdminEmail $AdminEmail

Here's another way to set multiple configs at the same time:

@(
    @{
        SetAsDefaultConfig     = $true
        ConfigName             = "GSuite"
        P12KeyPath             = "C:\P12s\PSGSuite.p12"
        AppEmail               = "[email protected]"
        AdminEmail             = "[email protected]"
        CustomerID             = "C021xxxxxx"
        Domain                 = "mydomain.io"
        Preference             = "CustomerID"
        ServiceAccountClientID = "98723498723489723498239"
    }
    @{
        ConfigName             = "Gmail"
        ClientSecretsPath      = "C:\Keys\client_secret.json"
        AdminEmail             = "[email protected]"
    }
) | ForEach-Object {
    $props = $_
    Set-PSGSuiteConfig @props
}

First-time authentication for free/non-admin accounts¶

If you are using a client_secrets.json for your configuration, you must also complete OAuth in browser to finalize your configuration. This will generate your refresh_token and initial access_token for the scopes listed below. Follow these steps to complete your configuration:

Import the module: Import-Module PSGSuite
Run Get-GSGmailProfile -Verbose (or any other Gmail, Drive, Calendar, Contacts or Tasks command) to trigger the authentication/authorization process:
- If you are using Windows PowerShell, you should see your browser open with a Google login prompt:
  1. Authenticate using the AdminEmail account configured with Set-PSGSuiteConfig.
  2. Allow PSGSuite to access the below scopes on your account that you desire.
  3. You should see a message in your browser tab stating the following once complete: Received verification code. You may now close this window.
- If you are using PowerShell Core (6+), you will be provided a URL to visit to complete authentication/authorization:
  1. Open your browser and go the the URL provided in the console output.
  2. Authenticate using the AdminEmail account configured with Set-PSGSuiteConfig.
  3. Allow PSGSuite to access the below scopes on your account that you desire.
  4. You should see a pop-up in your browser with a code to copy. Select and copy or click the button to the right of the code to copy, then paste the code back in your console where prompted, then hit Enter.
- You should see the command complete successfully at this point.
Scopes included with client_secrets.json auth:
Screenshots of the PowerShell Core process: