Thursday, October 9, 2014

Python and Google Apps Provisioning with the Admin SDK Directory API

After wading through documentation, blog posts, and StackOverflow answers I've finally figured out a way to authenticate using OAuth 2.0. Since we didn't want to have to interactively grant "user consent" for each of our domains, this is acting as a "web server" for computer-computer interactions.

I assume that you have Python 2.7 installed (three shalt thou not use), but I'd recommend installing Anaconda to make your life easier for all of this. You'll also need to install the Google APIs Client Library for Python.

EDIT: I was finally able to get it to work with the default SignedJwtAssertionCredentials.
 as well as PyCryptoSignedJWT. To install PyCryptoSignedJWT, download and unzip, then from the command line (in the directory you unziped to) type python setup.py install in order to install.

The next step is to set up your project. Here's the documentation from here to "Set up your API":
  • Enable the API access from the Admin console in order to make requests to the Directory API. To enable the API, log in to your admin account and select Security. If you do not see Security listed, select More controls and then Security from the options shown in the gray box. Select API reference, and then select the checkbox to Enable API access. Save your changes.
  • Set up a new project in the Google APIs Console and activate Admin SDK service for this project. See the Google APIs Console Help in the upper right corner of the Console page for more information about creating your API project.




Still in the Developers Console, you'll need to create credentials for your project. Click on Credentials (under APIs) and click the button Create new Client ID and then select Service account.


Download the key file, and make a note of the private key password (which is always "notasecret"). Then click the Okay, got it button.

You'll need to make a note of the Service Account EMAIL ADDRESS that is displayed (a long string of characters ending in @developer.gserviceaccount.com) and the CLIENT ID (the same string ending with .apps.googleusercontent.com).

The next step requires you to authorize your API client to access your admin console. Assuming your're still logged in to your Super Admin account, go to Manage API client access (or go to Security, Advanced Settings, Authentication, Manage third party OAuth Client access). For the Client Name, paste in the CLIENT ID that you noted previously. In the One or More API Scopes, put in a comma-separated list of the scopes that you'll be using. For our example I'd suggest https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.orgunit (you can always change this later). Then click the Authorize button.



The file you downloaded previously will be something like APIProject.p12 but we'll need to convert it to a PEM file. On a Mac or Linux machine this can be done from the command line ( openssl pkcs12 -passin pass:notasecret -in APIProject.p12 -nocerts -out APIProject.pem ), but on Windows other software is required (try Win32OpenSSL that can be downloaded from here). As a last resort for those who don't worry about security, you can convert it using this site.

So you now have a p12 key file, a Service Account Email Address, and of course your Super Admin account. You're set to start writing some code. I like the Spyder development environment that is installed with Anaconda, but feel free to just use Notepad (or Notepad++) if you're so inclined.

Here's the minimum Python code that works for me, fill in the appropriate values for yourself.


superAdmin = 'you@example.com'
serviceAccount = 'somethingorother@developer.gserviceaccount.com'
pemFile = 'APIProject.p12'
scope = 'https://www.googleapis.com/auth/admin.directory.user'

import httplib2
from apiclient.discovery import build
from oauth2client.client import SignedJwtAssertionCredentials

keyFile = file(p12File, 'rb')
key = keyFile.read()
keyFile.close()
credentials = SignedJwtAssertionCredentials(serviceAccount,
  key,
  scope,
  prn=superAdmin)

http = httplib2.Http()
httplib2.debuglevel = False #change this to True if you want to see the output
http = credentials.authorize(http=http)
directoryService = build(serviceName='admin', version='directory_v1', http=http)

# You are now authenticated, so you can say something like this:
user = directoryService.users().get(userKey = 'me@example.com')
print user.execute()



Hopefully that's enough to get you started. The documentation about what you can do with the Admin Directory API is here. just remember that some of them will require you to declare other scopes.

No comments: