There are several “actors” involved in the use of any Google API. The two main actors from a Google user account standpoint are:
These accounts belong to the “application” that will be accessing an API (Developer Account) and the access to services (User of Services). Functionally they are separate actors, so for clarity of understanding, it is important to think of these as separate accounts even if in practice they are the same. Perhaps the easiest way to think of it is that the developer actor does the work, but the user actor must give it permission to do so on its behalf.
The developer account is used to create a “developer project” within the Google console (https://console.developers.google.com). Within the portal, the developer can enable the various Google APIs the application is going to utilize and creates one or more unique security credentials for the application. These identifiers are used by OAuth2 flows to request access to read or modify (via API) the services of the user actor.
There are various rate limits imposed upon the application by Google. They are generally related to the number of calls that can be made, and they typically vary by API and the type of call. This can become important when decided whether to use a single application definition for all API activities or to create separate applications for each API. Since an application can also have multiple security identifiers, thought should be given as to whether there is a need to use different identifiers for each API, or even each specific purpose.
OAuth2 Flow
To be clear, simply enabling an API within the developer console does not actually grant access to any assets within Google services. The user must grant the permission to the application via OAuth2.
In a typical scenario, the OAuth2 flow is initiated when a user interacts with an application that needs to access Google services to perform its function on their behalf. The specific functionality the application requires is referred to as the scope. To put it another way, the scope is specific to the service you wish to be authorized for use via API. For example, AdWords has a single scope. Other services allow finer authorization control. For a complete list of scopes, click here.
The OAuth2 flow for granting access has several steps that can lead to further confusion. The first step is to obtain the authorization code. This is accomplished by making an authorization request and passing the Client ID and Client Secret from the application’s credentials along with the desired Scope to the Google OAuth2 service. The user is then prompted in the browser to accept or decline authorization. The prompt includes the name of the application associated with the Client ID and Client Secret.
If approved, the authorization code is sent to the redirect URL that was provided in the original authorization request. Passing the service a redirection URL of urn:ietf:wg:oauth:2.0:oob results in the authorization code being returned in the same browser window.
If the application is a user app (e.g. phone or tablet) rather than a back-office process, then the app uses the authorization code and proceeds directly to the next step. When configuring a back-office process, the next step usually must be taken manually since there is no actual webservice waiting to handle the redirection from the first step, and the authorization code is passed back to the user as mentioned above.
The authorization code is a single use code, and its sole purpose is to obtain an access token. The access token has a timeout, so if it is going to be used more than once, the next step is to obtain not only the access token, but also the refresh token. The refresh token can be used again and again to retrieve a new access token, so long as the user doesn’t manually revoke access. These tokens are obtained by requesting them from the Google OAuth2 token service @ https://www.googleapis.com/oauth2/v4/token. Again, the Client ID and Client Secret from the application’s credentials along with the authorization code acquired in the previous step.
That completes the process of a 3rd party (the developer) granting access to a 1st party’s (a user’s) data and services via API, limited by the scope in the access request. No actual data or services have been accessed yet as we have only taken care of granting access to it. The OAuth2 process of accessing an API on a user’s behalf, which we still haven’t done yet, is similar to the flow to obtain the access token and refresh token. A request is made to https://accounts.google.com/o/oauth2/token, passing the Client ID and Client Secret from the application’s credentials, along with the refresh token to obtain a new access token. The access token is passed in the header of any API request in the following form:
Authorization: Bearer THE_ACCESS_TOKEN
Using an API to do work
Now that we have granted access to our worker application, we should be able to perform any function the API allows, right? Not so much.
The access and capability to do work on the user’s behalf are limited to the things the user has access to see and do. In other words, the application has no rights beyond those of the user. Additionally, there may be configuration that prevents the application from doing work at the account level within the service. For example, use of AdWords requires the AdWords API be enabled for the account, and a developer token must be generated for making any API requests that perform work on the account. Therefore, it is extremely important to separate the concept of the developer, which the application was created under, from the user, which has access to the service and account(s) on that service
Share:
