Googlefy Your Apps

Introduction

The differences between desktop and browser applications keep blurring from the point of a user. Internet connectivity is more available than it used to be. A number of features are now considered to be standard in desktop applications, yet started as special internet functionality: Checking for new updates, sending documents by e-mail, go to vendor web site, report errors online.

It’s not unthinkable anymore to extend desktop applications with internet features or integrate desktop applications into an infrastructure such as Google Apps. While this would be possible with many web features and many providers this white paper is only about integrating with Google.

If you link your application with Google you might want to think a little about who Google is and how their business works...

Google

Users are those that actually use a particular product. Customers are those who pay you as a business. On a micro level they are different groups or persons. One department is responsible for purchasing a product, but is rarely also the one actually using it. At home parents are usually the customer, but the entire family is the user.

At a macro level, though, the two are interchangeable. As a software developer you sell software to another corporation that uses the software. A grocery store sells to consumers that - as the name implies - consume those products. In other words, most companies make money by selling products to users or representatives of those users.

Apple is clearly targeted at the consumer. Their products are sold because their customers want to use them. Microsoft creates products for corporations. Their customers use Microsoft products to run their own business.

Not so Google.

Google users are consumers, businesses, individuals... At the end of the day the majority of the human race is or was a Google user. Rarely does anyone pay Google for doing so. Search is free, GMail is free, Maps is free, YouTube is free... Google established an ecosystem in which users are not expected to pay.

Customers, on the other hand, pay as customers do. Google is foremost an advertising company. Their customers are companies that want to sell anything to Google’s users. Simplified spoken: Google taketh from the companies and giveth to the consumers. A model with serious implications.

The (non-)power of users

Users have little power. They might wish, but there’s little ground to actually demand. Customers are in a more powerful position because there’s a direct relationship between them giving money and what they demand. When there’s a disparity between users and customers, users become a product. The fact of them being users and behave in certain predictable ways is the essence of what companies like Google sell to their customers.

In other words, everything Google does for its users it does so in order to not make them go away. That’s a relationship a few levels below going out of ones way to make a customer happy. Like any successful company Google follows a clear long term strategy which can be qualified as “the web”. Web doesn’t refer to its meaning from a decade ago as a synonym for cloud or internet. Think about a big spider and its web.

The proposition of Google is to keep users which - applying the law of logic - is the same as not losing users. So how do they do this?

Psychological studies have shown over and over again that people tend to prefer avoiding losses over acquiring gains. This concept known as loss aversion plays an important role when people need to change anything. The higher your potential loss is due to a change the even higher the resulting gain has to be to compensate.

Google’s services are mostly interconnected. They don’t offer you search, dog food and medical assistance. They offer you search linked to reviews based on your mails which opens attachments in Google Docs linked to maps showing pictures on Picasa. Or YouTube videos you can +1 on Google+, share on a Google Sites and talk about in a blog to build circles that you manage in contacts.

This turns Google’s offerings into one single huge product with the Android phone being at the top of the food chain - metaphorically speaking. Adding a phone to its portfolio has been a clever move. Phones have become a important interface to the world. Most people carry around a phone longer each day than they are together with their spouse. Cell phones have surpassed keyboards, light switches and toilet seats as the primary source of germs. A phone isn’t just the device, it’s also a door towards those you want to talk with. Part of what you feel for the other side on the line is absorbed by the phone, from wanting to throw it away after a heated and annoying conversation to looking at the picture of a loved one when the phone rings.

Once stuck into this single huge offering it becomes harder and harder to go away, to become a non-user to Google.

When users are customers

The second implication of the disparity between customers and users is that Google isn’t very good at dealing with cases when both are the same.

Google has a number of paid services... Ranging from hardware search appliances, Google Apps for Businesses, to paid API usage.

It rarely is a seamless experience in the way Microsoft or Apple as big competitors manage it. Google needed ages before you could use a personal GMail account and a Google Apps account. Google+ is not yet available for Google Apps users. Information about APIs are sometimes hard to decipher, most products remain in beta or lab status for a very long time. APIs keep changing for paying customers just like for free customers.

Legal issues

Using Google

Usually, legal issues are difficult. With Google it’s surprisingly simply: For most businesses in the world it’s illegal to use Google.

Google, Apple, Microsoft, Amazon, Oracle... The big players are US companies, often Californian companies. Their customers and users, on the other hand, are all around the world. Not surprisingly, most of the world has different laws than California.

Apple censors British and German newspapers due to differing morale standards. Microsoft hands out confidential documents of French companies to US services which lately haven’t been too convincing in their ability to keep data confidential. Google violates privacy laws by publishing pictures of people in their own yard. Yahoo violates Iranian laws by returning links to articles that are illegal in Iran. eBay violates fundamental European consumer protection laws with the way PayPal works.

Laws are designed for national borders. The internet in general makes it very easy to cross this border. Most users aren’t even aware where services are located and how this impact their rights. Skype is a Luxembourgian company founded in Estonia with a majority owner in the US state of Washington. Do you know which laws apply when you make a Skype call from Canada to a friend in Italy?

When you and your customer are both based in the US, it’s relatively easy, though not inexpensive, to get legal advice on using Google. Otherwise it can be very difficult to figure out the legal status of using Google. In fact, unless your company is a multi-national corporation with more employees than most cities have inhabitants, it’s impossible to even figure out what you are supposed to do, much less actually act this way.

Using the API

Fortunately, everything is easier when it comes to the legal issues of using the API. As with most services Google has its own terms and conditions that define how you can use Google’s API in your application.

Introduction to the Google API

Overview

The Google Web API started in late 2002, in good Google tradition as a beta version. The only function available at that time was the search function allowing users to directly run searches instead of scraping them from the results page as has been done before. Google’s offerings were heavily search related. Google News was the latest service, Google Toolbar the only non-web product. The total number of products and services was 15.

Following the zeitgeist of 2002 the Google Web API was based on the rather complicated SOAP and WSDL standards that the big players at that time were actively pushing. API quotas origin in this first API, as well. Not being the global player of today Google feared a lot of competition and better offers using Google search technology. Meta search engines, even desktop programs such as Copernic where very popular back then. Therefore the API only allowed 1000 searches a day for non-commercial use. A policy that Google kept until today for many of its APIs, although the quota increased over time.

Shortly after renaming the Google Web API to the Google SOAP Search API, Google Code was launched early 2005. This web site has been the home of Google APIs ever since. When Microsoft released VFP 9, the final version of Visual FoxPro, the entire Google API consists of AdWords, Blogger, Deskbar, Desktop Search, Froogle, Gmail, Groups, Keyhole and Web Search.

2006 was when the world started to look like it looks today. Google Calendar launched, Authorization APIs became available, generic APIs such as the Google Data API saw the light of the world.

Fast forward to mid-2011:

Google offers an extensive list of APIs to various products. Some of them are free, some of them are quite expensive. Many are specific to certain products and usage scenarios, others can be applied broadly. The whole lists is now pages long. This white paper can only cover a very narrow and limited set of APIs.

Registration

Before you can use the API functions you should register with Google. Some APIs work without registration. However, Google monitors API usage and only allows a certain number of requests per user. The user is typically identified by IP. The API quotas do vary depending on frequency of calls and load on Google servers. Registered users still have a quota, but a higher one. Paid users have even higher quotas.

Before you can register for an API you need a Google account. Create one if you don’t have one already. Then navigate to the API console:

https://code.google.com/apis/console/b/0/#access

Click on “Create project...” to create a new project.

Click on “Create an OAuth 2.0 client ID...” to register a new application. A dialog prompts you to enter some branding information. You can provide Google with your logo should you wish so.

For desktop applications written in Visual FoxPro you have to choose the option Installed application on the next page:

With “Create client ID” you’ve registered your application successfully. The result is a page that indicates your branding information and also specifies the Client ID and the Client secret. Whenever you access API functions you need those two values. Do never share them with anyone else as they allow others to impersonate your application:

Authorization

Some Google APIs require authorization because they need to access data associated with a Google account. Google Documents List API, Contacts API, Google+ API are examples for this kind of authorization.

Other APIs are paid services such as Google Maps Premier API. For those services Google needs to validate your request as you potentially pay per usage.

A third group of APIs is free, but with low API quotas. By registering and providing an API key you can increase the allowance in exchange for letting Google know who is using their services. This kind of authorization has already been covered in the previous section about API registration. In the following chapter we will have a look at authorizing users with the Google account.

Authorization is not the same as authentication. Authentication means to verify the identity of a user. Authentication is what your login dialog in your application does. Google supports the OpenID standard for authorization. Hence, if you wish you could allow users to use their Google account to log into your application after an initial mapping has been defined between the Google account and your internal user ids.

In a Google App environment this can actually be a useful mechanism as Google App administrators have similar possibilities as domain administrators in a traditional Windows Active Directory domain as far as authentication is concerned. Google even offers enterprise level tools to synchronize and mix Google app accounts with company accounts.

However, authentication with Google accounts hasn’t really caught up in the desktop application segment. It’s more popular for web applications as a mean to achieve single sign-on. In desktop applications established infrastructures such as Active Directory are preferred.

Authorization, on the other hand, is the process of Google giving you (the application) access to a customer’s data after the customer has been authenticated. The process of authorization verifies that you are entitled to access data or perform actions that you want to carry out.

Requirements

If your application offers features based on Google APIs that use Google accounts for authorization purposes, your users must have a Google account. That is obvious if you think about, but still unusual. While users rarely hesitate to log onto a web service with their Google account, many instinctively hesitate when they have to log on to their account in a desktop application.

Consequently, you need to teach your users why authorization is needed, what you do with the account and what you don’t. Even though users have the same degree of control it just doesn’t feel the same for users. Be prepared to answer questions or be rejected due to the Google account requirement.

Authorization methods

Google authorization has evolved over time. Unlike certain companies from Cupertino Google has maintained backward compatibility for a long time. Older authorization protocols are still supported with older APIs. So if your application was written in 2006 to update appointments on a Google Calendar using ClientLogin authorization it will likely continue to work.

It should be mentioned, though, that newer APIs only support newer methods of authorization and Google already started withdrawing support for certain older APIs.

The following pages describe all those methods sometimes in great detail. If you are not interested in all of those details, focus on OAuth 2.0, which is the authorization method that I’d recommend for new applications.

ClientLogin

ClientLogin was Google’s first approach to authorization and authentication. Web sites or applications prompt the user for their email address (GMail mostly) and password. Both are posted as a regular web form to https://www.google.com/accounts/ClientLogin along with some extra information such as access to which service is requested.

Google validates user name and password, and then responds with an Auth token. Secured API function require this token to be passed along with every API call.

ClientLogin is straightforward to implement and seemed secure enough initially. After all, communication happens over an encrypted SSL channel. Then dictionary attacks increasingly became an issue. Google responded by adding a captcha challenge to ClientLogin.

Source: Google Code

Whenever Google deems it necessary, the login service wouldn’t return an Auth token, but rather an image. The web site or desktop application display the image and let the user enter the word displayed on the image. This input is passed back to Google and validated.

Adding the CAPTCHA challenge didn’t fix a fundamental design flaw of ClientLogin, though. The user has to give their username and password to a third party, whether that is a web site or a desktop application. Not only requires this a lot of trust, it also is an all-or-nothing approach.

Even though the user intended to only give access to the calendar, the other party has now access to every web offer that uses ClientLogin, those not from Google included. They even have access to the account page and can change the password effectively locking out the legitimate user.

If a user wants to revoke access the only option is changing their own password themselves. Even then the account might get locked when too many attempts to log on are made with the old password.

AuthSub

AuthSub was Google’s response to this problem at least for web applications. It doesn’t work for desktop applications which Google calls installed applications.

Source: Google Code

The sensitive part of the login process - entering user name and password - is moved out of the realm of the web application to Google’s servers. Too request an authorization token the application redirects the user to https://www.google.com/accounts/AuthSubRequest passing additional information like requested scope of access and the next page. When authorization was successful, Google redirects the user back to the application passing in the authorization token for further requests.

Web applications need to be registered with Google in order to use this service to its full extent. The registration process is explained on http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html.

Registration of applications enables Google to keep track of which application a user has granted what type of access and whether they already have logged into the application recently. Consequently the redirected page might not display a log-in dialog, rather return a log-on token immediately.

The whole process is managed by Google which keeps it flexible enough for future modifications. This includes alternative ways to log in like last year’s introduction of a two-factor authentication with PINs sent to a phone. Applications don’t need to change yet benefit from a higher degree of security.

There are two drawbacks of AuthSub. Less important to us is the fact that AuthSub is Google specific and only works with Google services. Most likely you want to implement authorization because you intend to use a particular Google service in your application. So that’s more of a non-issue.

More seriously, though, Google AuthSub only works with web applications. It’s not designed to be used in a desktop application. Of course, you can implement a web application that is being called by your desktop application to handle authorization. But that’s a lot of extra work for a less than seamless experience.

SAML

Security Assertion Markup Language is an XML based standard for user authorization across domains. Google App Premier users can provide a Single Sign-On implementation to connect Google with their own authentication system, for instance Microsoft Active Directory. With SAML Single Sign-On in place, users are authenticating with their company user name and password on their company server whenever they want to access services such as Mail or Calendar.

SAML enables companies to switch their mail system to Google Apps Mail without having to hand out new user accounts and passwords to all users, or have users to change passwords in multiple places every time the password expires. SAML is very interesting... if you are an administrator.

OAuth

OAuth is the latest and greatest in authorization and a blazingly fast emerging standard.

OAuth isn’t a propietary protocol like ClientLogin and AuthSub. It’s a standard developed and implemented by many companies not just Google. Details vary in their implementation, but most of the following chapter is just as valid for any other cloud service that uses OAuth for authorization.

The past five years have seen an increase in composite applications. You are not logging into one application provided by a hosting company and using it. Instead you mix and match various services. 1Password stores passwords in your Dropbox. Google Docs sends documents to Evernote. Your e-mail client adds task to Remember The Milk. Blogs let you like them on Facebook, re-tweet them via Twitter or +1 them on Google+.

Services such as ifttt support entire workflows, eg. automatically download any photo on which you are tagged, receive an SMS if there’s good weather tomorrow, automatically add your Foursquare location to a diary, archive any Facebook message, tweet, Google+ posting in Evernote or Dropbox, etc.

ifttt combines 35 different cloud services. Giving out user name and password to a single web page for all these services would be a serious issue for most web users (hopefully). Doing so would basically give the web site access to your life, at least when you are one of the younger ones or living a more digital life style.

OAuth solves these problems. Instead of giving account information to a third party you are now authorizing a third party to perform certain activities with the ability to withdraw authorizations more easily. On Google you can do this by opening your Account settings from the Google bar at the top of your browser window.

On the first page in the Security section click on the Authorizing application & sites link to edit what application has access to your account and to revoke access.

Google Profiles isn’t yet supported on Google Apps accounts. Therefore the setting looks a little bit different:

With a single click on Revoke Access you can lock the third party out. It’s good security practice to go through this list from time to time to find apps that you don’t use anymore.

OAuth comes in two flavors: OAuth 1.0a and OAuth 2.0. OAuth 2.0 support is still experimental at Google, yet it is the preferred means to authorize. Despite some drawbacks OAuth 2.0 will be the method we look at in more depth in a few moments.

Within the security community there’s quite a bit of discussion going on regarding the development of OAuth 2.0. Remember that OAuth 2.0 is an open standard supported not only by Google, but also by Facebook, Twitter, Yahoo, Microsoft, and other big players in the online market. Considering the increasing amount of data in the cloud, OAuth 2.0 will drive security implementations and failures for the next couple of years. It’s not just a matter of adding an appointment to your Google calendar.

The reason behind the discussion is that OAuth 1.0 is technically speaking more secure than OAuth 2.0. Security usually involves complexity. OAuth 1.0 is pretty complex with its cryptographic components making it difficult for most developers to implement correctly. The proponents of OAuth 2.0 prefer a secure enough solution that is done correctly by the majority, whereas opponents are worried about a new weakest link in the system.

As previously mentioned authorization is all about securing access to resources, whether that’s documents, pictures, contacts, blogs, tweets, and so forth. OAuth is about one system trying to access resources on a different system with the permission of the resource owner. This involves three parties:

Requesting access is a multi-step process. Say you want to have access to Google contacts on behalf of your application’s user.

You, as the client system, need to register with Google as the resource provider. Registration involves that you and Google share a secret. Anyone could send a request to Google pretending to be you. Google uses the shared secret to verify your identity. Shared secrets can have one of two forms: You can either provide a certificate for RSA-SHA1 authentication, or a accept a secret key that Google generates for you when you prefer HMAC-SHA1 signatures.

This step is only required once for every application. You do not need a separate registration for every user of your application. Application registration ensures that the other server is at least listening to you.

The first step to carry out every time you access resources on behalf of someone else, is to obtain a request token. Basically this means that you use the shared secret to log onto the other server as yourself. The resource provider validates that your request is still valid and issues a request token back to you.

Part of the request is the scope. Scope in the context of OAuth defines what resources you want to access and what operations you want to perform on them. This sounds a lot more complicated than it actually is, as a scope is merely a URL. To access a Google calendar with read/write access you would pass

http://www.google.com/calendar/feeds

as the scope parameter. By giving a more specific URL you can limit access to certain calendars, certain activities, etc.

With the request token you can in a second step request access to a specific resource. For this you need to obtain an access token from the server providing your request token. In fact, that’s the only purpose of the request token.

To request the access token you have to forward the user to a web page. This is true for web application as well as desktop application. Google has discussed a device mode without full browser requirement for a long time but never actually implemented this feature. In other words, in order to use most Google API functions you either have to launch a browser or embed the web browser control.

When you redirect the user to Google two things happen. First, Google authenticates the user. This means Google asks the user to identify himself or herself. Depending on the type of account and its settings Google might just read a cookie and authenticate the user automatically, or they may actually call him on the phone, read a number while the user has to enter email, password and this PIN.

Once Google has established that the user is for real it’s up to the user to authorize you for whatever resource you want to access. Google prompts them with the name of your application (based on your registration) and a list of permissions you want to have. Only if the user accepts, you receive an access token back.

That’s the generic model which is true for OAuth 1.0 and OAuth 2.0. The differences are where the difficulties are hidden.

OAuth 1.0 access token don’t expire, or more precisely, they rarely expire. The user is free to revoke any access token that has been handed out. Google will from time to time end a session and require re-authentication. OAuth 2.0 access token have a default lifespan of one hour.

What causes this dramatic difference?

OAuth 1.0 requests need to be signed. They encode the request consisting of the HTTP command, the Url and all parameters into a string and sign it with either the shared secret (HMAC_SHA1) or the private certificate (RSA_SHA1).

Certificates have a public and a private key. The public key is what you pass on to Google and can, in theory, be published to anyone. The private key is what you need to keep secret. RSA_SHA1 shortens the message by creating a single hash value from the actual text. Then this hash value is encoded using the private key.

This operation is asymmetric. You can encrypt text with the private key and decrypt it with the public key, but you can’t use the public key for encryption and decryption.

HMAC_SHA1 is a little less secure. Instead of using data that is only known to one party it relies on a shared secret. A two-step process turns text into a hash value by combining the actual text and the shared secret.

No matter which process you choose, you end up with a hash value that can’t be faked. Google uses the same mechanism to generate the base string using the HTTP command, URL and parameters. If they manage to create the same verification key as you send in, then none of the information that compromise the base string have been changed. The reliance on cryptography has multiple benefits:

1. Both parties can validate their respective identity. It’s impossible for someone to pretend to be your application and trick the user into granting access.
2. By using signatures communication doesn’t have to be encrypted. A simple HTTP connection is sufficient.
3. Every single request using the access token has to be signed. This ensures that only you can use the access token even if it becomes known to someone else.

On the other hand, signing requests is difficult and requires some extra programming for every single request. You can’t just enter a URL into the browser and simulate an API call.

OAuth 2.0 was meant to solve this issue. Instead of using signatures OAuth 2.0 relies on SSL encryption, or in other words, on the HTTPS protocol.

SSL encryption ensures that nobody else can listen to the communication. The connection between the two end-points is absolutely secure. While the consumer can still verify the identity of the service provider the reverse isn’t true. This requires using a shared secret as the only means to ensure identity. The new approach raises a few concerns:

Because the server can’t verify the identity of the client anyone with the shared secret can impersonate your application. It’s even more important than before to keep the secret secure.

OAuth 1.0 secure communication between your application and the service. OAuth 2.0 only secures communication between your computer’s and the service’s computer SSL layer. Installed tools on either computer may intercept traffic and modify it. This technology is used by virus scanners, firewalls and, of course, viruses, worms, rootkits, and similar evil software.

With OAuth 1.0 every request has to be signed, even when you use the API. OAuth 2.0 only signs the initial request with the shared secret and issues a session token as a result. For further requests only the session token is required. If someone obtains the session token, they have access to the same resources as your client application.

This moves the responsibility of securing the connection from the server to the client. Most client developers are no experts in security. After all, this was the initial idea of changing the OAuth process, after all. It’s therefore unlikely that many developers will get session token handling right.

Those in favor of the change argue that most authentication in web applications is cookie based. After authenticating and authorizing a user, a cookie is returned and remains the only mean of authorizing request. A session token is similar to a cookie and therefore no extra risk.

Given the large history of cookie based attack vectors, OAuth 2.0 will likely be the weakest link in years to come and therefore one of the primary attack targets.

Due to the importance of the session key, OAuth session keys typically expire quickly. Google issues sessions keys that are only valid for one hour. Any request send after an hour is denied with a 401 error message

<HTML>

  <HEAD>
    <TITLE>Token invalid - Invalid AuthSub token.</TITLE>
  </HEAD>

  <BODY BGCOLOR="#FFFFFF" TEXT="#000000">
    <H1>Token invalid - Invalid AuthSub token.</H1>
    <H2>Error 401</H2>
  </BODY>

</HTML>

To circumvent the expiry of session tokens, Google issues a refresh token. This token should not be used in communication and is therefore less likely to be stolen. It never expires and can be used to request a new session token.

Google demands that you shall only store the refresh token if you can securely store it. Considering that the alternative is that users have to re-enter their password every hour, I can’t see any developer not storing the refresh token unless you are needing access only once.

Despite those worries it currently looks like OAuth 2.0 will be the path forward for most companies including Google. The benefit of easing access is more important than total security for these companies. OAuth 2.0 isn’t insecure, just less secure than OAuth 1.0 but still secure enough.

Let’s look at what you need to do gain access with OAuth 2.0 on Google. If you haven’t registered your application with Google yet, now is the time to do so. The registration process has been explained in detail in a previous chapter. For the following steps you need the client secret and client id from your API page.

As the first step you need to log onto the Google server. Open a browser window from within your application. The simplest approach is to use the WebBrowser control. Navigate to the following URL:

https://accounts.google.com/o/oauth2/auth?client_id=1234567890.apps.googleusercontent.com&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://docs.google.com/feeds/&response_type=code

This URL has several elements you need to change depending on your configuration and needs. The first is the client_id value. Replace the value with the client_id from your API console.

The scope defines what data you want to access. The sample URL attempts to read documents from a users Google Docs account. Everything else can remain as it is.

Google redirects to a page where the user has to log on. If the user is logged on, this page might be skipped. If the user has multiple logins, they can pick the one to use for the application.

In the next step the user has to grant access. This page displays the application name and logo that you specified when you registered your application.

When the user allowed you to access their data, Google responds with a request token.

The user can copy this value into your application. Alternatively you can watch for the window title and read the key from the caption:

With the request token you can now ask Google for an access token. This needs to happen soon after you obtained a request token, because the request token expires after a brief period. From now on everything happens with HTTP requests that your applications sends directly to Google using WinINet API functions. You don’t need the browser window anymore.

The first request is a POST operation. The body content is

client_id=1234567890.apps.googleusercontent.com&
client_secret=abcdefgh&
code=4/xyz1234xyz1234xyz&
redirect_uri=urn:ietf:wg:oauth:2.0:oob&
grant_type=authorization_code

client_id and client_secrect are the values that Google assigned your application when you registered for API access. You can copy and paste these values directly from the API console. Make sure that you protect the client_secret in your application. The user should never see it.

code is the value that you received back as an authorization token. Currently they always seem to begin with “4/”. Every variable must be on a separate line, must end with an ampersand except for the very last line and must not contain any additional spaces at the end. Post this data block to

https://accounts.google.com/o/oauth2/token

If you make a mistake in the request you receive an error message which can be generic or actually helpful like this one:

<HTML>

  <HEAD>
    <TITLE>Invalid grant_type: refresh_token                                                               </TITLE>
  </HEAD>

	<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
    <H1>Invalid grant_type: refresh_token                                                               </H1>
    <H2>Error 400</H2>
  </BODY>

</HTML>

Don’t expect more details than that. The error message can be an HTML message or it can be JSON:

{"error":"invalid_grant"}

What you get depends on the error. Some errors are in HTML, some are in JSON, likely depending on where in the execution hierarchy at Google computers the error is being caught. When being successful you receive an access token and a refresh token in JSON format:

{"access_token":"ya29.AHES6ZT574agkbNcC4G3mSea8SoEJosXSkL-PEFcEC4uW2A","token_type":"Bearer","expires_in":3600,"refresh_token":"1/xR2tLFRMlures1Cbtce7ymsfyUzxY4qXXXXXWhaInE"}

The access_token value is what you need to pass on to API functions. When the access token expires after 3600 seconds (one hour), you can use the refresh_token to request a new access token. For this send a different POST request:

client_id=1234567890.apps.googleusercontent.com&
client_secret=abcdefgh&
refresh_token=1/xR2tLFRMlures1Cbtce7ymsfyUzxY4qXXXXXWhaInE&
grant_type=refresh_token

to the same URL that you posted the request token. Refresh tokens start with “1/” usually. The response is a new access token, but no new refresh token:

{"access_token":"ya29.AHES6ZTOgyaeTtAFDu4S7OosoeTKfqwqSAjeORNlv8BqVGEl","token_type":"Bearer","expires_in":3600}