This is part 2 of a 2 part blog series. In Part 1 I discussed authentication using OpenID Single Sign-On.
Couple Jira Studio with Google Apps and you have a complete set of software development and collaboration tools in the cloud. In this blog post we’ll look at how you too can integrate your application with Google Apps using open standards and alert you to some of the hidden gotchas relating to data access.
Data Access with the Google Apps APIs
Once you have your app’s user-base hooked up with Google’s, you’re ready to start getting access to some of that sweet data.
As with authentication, there have been many protocols for secure data access. Network-level RPC (remote procedure call) mechanisms have been around for ages and usually comprise a communication protocol over a socket. You can always roll your own, but why would you when there has been significant effort put into standardising the communication protocols for web-based RPC. Internally at Atlassian we have been starting to expose REST end-points to provide developers with access to data.
Google offers a rest-inspired API for accessing and mutating data stored in Google Apps. This set of APIs are generally well-documented and provide access to a host of content including:
- Mail: we use this in Jira Studio to retrieve a feed of unread emails.
- Calendar: we use this to allow users to quickly view upcoming events and set up meetings from within Jira Studio.
- Docs: this is used extensively to allow attaching, previewing and embedding documents, spreadsheets and presentations into the Jira Studio issue tracker and wiki.
- Provisioning: the provisioning API allows us to keep the user-base within Jira Studio in sync with the user-base from the Google Apps domain.
The sweet thing is that Google already provides client implementations to access data through these APIs to help kick-start development on integration points.
It’s one thing to provide well-defined APIs but it’s another thing to authorise access to them. Google provides a few mechanisms to get access to protected data, including basic username/password-based authentication. This option will require the user to enter their Google password in order for your web app to access their Google data. The clear downside is that the user will be entering their Google password on your app!
Just like OpenID is becoming the standard for delegated authentication, it’s sibling OAuth is becoming the standard for delegating secure access to data. The OAuth protocol allows a user to authorise secure access to data from one service to another service. A classic use-case is allowing Facebook to import potential friends from your GMail contacts, without you actually handing over your GMail password to Facebook.
Google has implemented both 3-legged and 2-legged versions of the OAuth protocol to allow secure access to it’s data APIs. The 3-legged version of OAuth (3LO) requires a user to explicitly allow access data. So if you wanted to embed a Google Doc in a Jira issue, then the user would need to authorise Jira Studio to allow access to the Google Docs API. Although this ensures the user never has to enter their login details to Jira Studio, the user-experience will start to get annoying.
In contrast, the 2-legged version of OAuth (2LO) specifically takes the user out of the equation. In this situtation, Google Apps trusts Jira Studio to make requests to certain API’s. The advantage of this approach is the user no longer needs to authorise access to Jira Studio – instead, the administrator sets up the trust relationship in Google Apps. Google have made this process easy with the introduction of the Google Marketplace. Developers define a collection of API scopes that’s used by their application to access Google Apps data. When an admin purchases an application, they authorise the application access to the API scopes.
If you’re looking to get started with 2LO access, it’s best to just dive straight into the code to see how easy it is to get started
There are some things to watch out for when using OAuth for the Google Data API’s:
- User State: if you are using 2LO, then some operations require a specific user context, e.g. getting a list of documents. These API calls retrieve the Google Docs for that specific user. 2LO allows your application to state who that user is; conversely, your application needs to store the username of the currently authenticated user. This isn’t much of a problem as most apps maintain the currently authenticated user in session. You need to take extra care because if your application is susceptible to attacks on your authentication/session management layer, then exploiting this could allow unauthorised access to Google Apps data within your domain. 3LO doesn’t share this problem.
- Provisioning API: the provisioning API allows you to access and mutate the Google user-base. This API is only available via 2LO or password-based authentication. Currently, only paid Google Apps domains have write-access via this API. Jira Studio gets around this problem by not needing to mutate any data in the Google user-base, instead we use the Google user-base as the source of truth.
Beyond Basic Integration
Google have provided a convenient platform for integrating existing and new applications with the Mail, Docs and Calendaring services provided by Google Apps.
We’ve cranked it up a notch and have also integrated:
- Gadgets in Google: if you’re the type that manages everything via email, you can have complete access to what’s going on inside Jira Studio without needing to move off your email window.
- Chat in Jira Studio: now you can send instant messages from within your browser to your team members. Take a look at Rich’s developer blog post for an insight into the implementation of this slick feature.
Miss part 1 of this blog? Integrating Atlassian’s hosted development suite with Google Apps »
Want to see the integration at work? Try Atlassian’s software development suite in the cloud »