Skip to content

Initial Setup

Nate Ferrell edited this page Mar 5, 2019 · 94 revisions

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

This will be slightly behind the GitHub repo. Please see below for installation instructions from the GitHub repo. 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)

  1. Open Powershell and run the following command: 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!!

  1. Click here to go to the latest releases, then download the PSGSuite.zip file attached to the release
  2. Right-click the downloaded zip, select Properties, then unblock the file. This is to prevent having to unblock each file individually after unzipping.
  3. Unzip the archive.
  4. (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!!

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

Building with the default task list will automatically import the module at the end of the build.

If you'd like to import the compiled module in a new session, you can find it under the BuildOutput folder in the root of the repo.

OR

  1. Fork the repo to your local
  2. Import the module by loading the PSD1 file via full path or placing the local repo folder somewhere in your $env:PSMODULEPATH

G Suite Users with SuperAdmin access

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

  1. 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
  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 'service account' right above the 'Which API are you using?' question to go to the Service Account Creation page.
  4. 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.
  5. Click the 3 dots button at the right side of the service account you just created then select Edit.
  6. Click the blue link to SHOW DOMAIN-WIDE DELEGATION.
  7. Check the box to allow Enable G Suite Domain-wide Delegation. You should see additional fields appear for Product Name and Email Address.
  8. Set an appropriate product name (i.e. PSGSuite), then click the blue SAVE button.
  9. 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. psgsuite@kindred-spirit-20183.iam.gserviceaccount.com) and the ServiceAccountClientID (e.g. 10264827741861193783987). Save these two in a Notepad, you will need them when you fill out the configuration.
  10. 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

  1. Open a new tab or window to the Google Admin Console
  2. Go to Security
  3. Expand 'Advanced Settings'
  4. Click 'Manage API client access'
  5. 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
  6. Copy / paste the following scopes together on the right field 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

  1. 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

      image

  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: image
  4. On the OAuth Client ID creation page, click the blue button on the top of the screen to Configure consent screen: image
  5. On the OAuth consent screen... image
    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. image
    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: image
  9. Once created, you'll get a pop-up with the client_id / client_secrets info, just click ok to close the pop-up: image
  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: image

Creating the PSGSuite Configuration File

  1. Import the module:

    • Module located in PSModulePath: Import-Module PSGSuite
    • or somewhere else: Import-Module C:\Path\To\PSGSuite\PSGSuite.psd1
  2. 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:
      • AdminEmail: This is email address for the SuperAdmin account that created the project (usually your email)
        • {service account name}@{project name}.iam.gserviceaccount.com
      • 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.

  3. 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               = "psgsuite@developer-shore.iam.gserviceaccount.com"
            AdminEmail             = "admin@mydomain.io"
            CustomerID             = "C021xxxxxx"
            Domain                 = "mydomain.io"
            Preference             = "CustomerID"
            ServiceAccountClientID = "98723498723489723498239"
        }
        @{
            ConfigName             = "Gmail"
            ClientSecretsPath      = "C:\Keys\client_secret.json"
            AdminEmail             = "mypersonalinbox@gmail.com"
        }
    ) | 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:

  1. Import the module: Import-Module PSGSuite
  2. Run Get-GSGmailProfile -Verbose (or any other Gmail, Drive, Calendar, Contacts or Tasks command) to trigger the authentication/authorization process:

Getting Started

Examples

User Automation

  • Content needed

Drive Management

  • Content needed

Function Help

Authentication

Calendar

Chat

Classroom

Configuration

Contacts

Data Transfer

Delegation

Drive

Gmail

Groups

Helpers

Licensing

Org Units

Reports

Resources

RoleAssignments

Roles

Schemas

Security

Sheets

Tasks

URL Shortener

Users

Badges

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.