Google OAuth2 for Devices Revisited

Sun, 01 Jan 2017 13:03:00 +1000

I just dusted off an old project that uses Google’s OAuth 2.0 for Devices API to authenticate against Google Docs, and cleaned up my implementation.

OAuth2ForDevices is really useful for IoT projects that use Google APIs. I’m using it for a device that records data directly a Google Sheet.

While the API itself is pretty straight forward, getting the implementation 100% battle-hardened takes a bit of work and iteration, so I’ll share here what I’ve learned. If you are coding in Python, you might find the OAuth class in the py-gaugette library useful.

Theory of operation

First-Boot OAuth2 Flow

The first time a device boots, it needs to request permissions from the user to access Google Docs.

call the OAuth2 API to specify the permissions required and request an authorisation code.
show the auth code to the user
poll the OAuth2 API waiting for confirmation that the user has granted access to the device.
save the refresh token in persistent storage for next startup.

To confirm access, the user uses a web browser on a separate device, and navigates to https://www.google.com/device to enter the authorisation code.
The user must be logged in to a Google account when they confirm the permissions, and the device will be granted access on behalf of that account. The level of access is determined by the scope parameters passed by the device, and the user will be shown which permissions have been requested before they confirm.

After the First Boot

On subsequent boots the device can use the saved refresh token to authenticate, so no further user interaction is required.

Here’s What It Looks Like

1. The Device Presents a Code

On my time clock, I display the code on the one-line OLED display. The device code can be quite long - the API docs recommend ensuring you can display 15 ‘W’-sized characters, although current codes are formatted as XXXX-XXXX. The length of generated codes has increased since I first started using this API and I now need to use horizontal scrolling to display the entire code.

2. The User Enters the Code

You need to communicate the URL (https://www.google.com/device) to the user somehow.
This is the web page they will see. They may first be prompted to log in to their Google account or select from multiple logged in accounts.

3. The User Confirms Access

The permissions listed here are determined by the scope variables you have passed. The list of available scopes is defined here.

On the Device

Here’s what it looks like on the device.

Making API Calls With OAuth2 tokens

The most complicated aspect of this API is passing the credentials and handling exceptions, and a lot has changed since I wrote the earlier Feeds implementation. Now I’m using the Google API Client Libraries for Python and passing in the token via a oauth2client.client.GoogleCredientials instance.

One nasty little surprise I discovered with long-running applications is that after the device has idled for a long time (say 24 hours without making an API call) I start getting BadStatusLine exceptions on all API calls. To handle this and other errors, I use @wrap from functools to wrap all of the API calls in a retry function. This keeps the extra complexity of error recovery nicely abstracted away.

py-gaugette Gets a Refresh

Sat, 12 Nov 2016 14:39:00 +1000

I’ve made some major changes to the py-gaugette library to address several issues that have accumulated over time, namely:

added interrupt-driven option to rotary encoder
fully Python 3 compatible
works with current version of Py-WiringPi
uses dependency injection for GPIO and SPI interfaces
updated Google Sheets code to use new API

Dependency Injection for GPIO and SPI

Classes that interact with the GPIO or SPI interfaces now take an instance of that interface as a parameter to the constructor. This avoids the issue of having multiple classes trying to initialise the GPIO library, and makes it easy to pass alternative interface implementations.

Interrupts for Rotary Encoders

The original implementation of the rotary encoder library used polling. On the Raspberry Pi it now supports interrupts. The previous polling behaviour is still supported.

Fully Python 3 Compatible

While the library has been mostly Python 3 compatible, there were a few exceptions. In particular the SSD1306 class depended heavily on the Python 2 behaviour of the division operator, which changed in Python 3. I’ve rewritten the calculations to mostly use bit shifts rather than division.

Gaugette