Service Accounts

#Service Accounts

What is it?

Most Cmdlets for Google Apps require that you have authenticated as an administrator to that Google Apps domain. However, some other Cmdlets need to work on behalf of the user instead. For instance, if you need to do anything with any other user's Gmail Messages, you will need a Service Account.

In order to use a Service Account, you will need to take some additional steps beyond what is needed to run the Cmdlets as they are. Details from Google can be found here.

Overview

You will need to create a service account in the Google Developer's console. Once you have created that service account, you will have downloaded a key file that you will use with Set-GShellServiceAccount. You then have to set the service account up to have domain-wide-delegation, and you have to register this service account in your domain's CPanel. After you have done this, you will be able to use any target cmdlet (if it supports service accounts) in the Gmail, Drive or Calendar APIs by using the additional parameter TargetUserEmail.

Step By Step

Step 1 - Create the Service Account

A) Log in to the Google Developer's Console and choose the project you set up to use gShell.
B) In the navigation menu on the left, choose the Credentials link. Click the blue Create credentials button and choose Service account key.
C) When prompted in the next screen, in the Service account drop-down choose New service account. Give your service account a name, and note how it correlates to the Service Account ID.
D) Choose either the JSON or P12 key type, this will be the file downloaded to your computer.
E) Hit Create, and confirm that you downloaded the key file (you'll need that shortly).
F) In the Credentials section again you should now see the service account listed at the bottom of the page. Click the blue link in the top right of that section for Manage service accounts.
G) To the far right in the row for your service account click the three-dot button to open a menu, and choose Edit.
H) In the form that opens, check the box for Enable Google Apps Domain-wide Delegation, and hit save. I) Keep this open for Step 3.

Step 2 - Set-GShellServiceAccount

Back in PowerShell, make sure you have run at least one command for your domain that has successfully worked prior to this step, for instance Get-GAUser.

Once you have verified that is working, run Set-GShellServiceAccount with your appropriate settings, like so:

PS C:\> Set-GShellServiceAccount -Domain mydomain.com -ServiceAccountId "Whatever-The-Name-Was@apiauthflowtest.iam.gserviceaccount.com"
-CertificatePath "C:/The-Path-To-The-Key-File-You-Downloaded/ProjectName-5f8582c7f.json"

You should get no errors if it worked properly.

Step 3 - Register the service account with your domain

A) Log in to your domain's admin panel.
B) Navigate to the Security tab, then click on Show More and choose Advanced settings.
C) Click the link for Manage API client access.
D) Once here, you need to enter the Client ID for your service account. If you still have the window from step 1 open (at the Manage Service Accounts page) you should see a link on the service account for 'View Client ID', click that. Copy the Client ID which should be different from the Service account name/email. Copy and paste this in to the Client ID field in your Admin Panel.
E) For the scopes, you have to specify what you want the service account to have access to. The three scopes below are examples of what you would use if you want full access. If you want to specify access, check the pages for Gmail, Calendar and Drive to figure that out.

• Full Access For Email: https://mail.google.com/
  
• Full Access For Calendar: https://www.googleapis.com/auth/calendar
  
• Full Access For Drive: https://www.googleapis.com/auth/drive
  

Note: As of 0.10.0, you should always add the following scope, as well: https://www.googleapis.com/auth/userinfo.email

F) Save out.

Step 4 - Use it!

Prior to having a service account set up, you just use the traditional parameters as you would see on the Google API References. For instance to get the first 100 messages in your inbox you might use the following:

Get-GGmailMessage -MaxResults 100 -All -UserId me

Now that you have set up the service account, you can add the service account parameter, TargetUserEmail:

Get-GGmailMessage -MaxResults 50 -All -UserId me -TargetUserEmail cburke

That's all there is to it! Remember, you only want to use this when you need to use the Gmail, Drive or Calendar APIs to impersonate the user. For other things like any EmailSettings Cmdlets, those already assume you are using them as the admin, so you don't need to do anything else. Plus, the service account parameter isn't available for any incorrect APIs anyways!

######Edited: 2016/07/22