Application design considerations

The design of your app and the way that it handles authentication and authorization are deeply interdependent. This section describes how authorization works for Marketplace apps.

Your app must use single sign-on, so that the user doesn't have to re-authenticate. By implementing single sign on, your app can integrate smoothly with the Google APIs and easier to for users to install and use.

OAuth 2.0 and scopes

All G Suite applications use OAuth 2.0 to handle authentication and authorization. See Using OAuth 2.0 to Access Google APIs to learn more.

Your app specifies one or more scopes: strings which identify resources that it needs to access. These scopes are used together with a set of tokens to secure a user's access to resources. A scope represents a particular form of access to a single resource or to a group of resources, for example:

  • Read files on Google Drive
  • Read or write Google Calendar data
  • Create a user account

A user's access to a resource is authorized using an access token; your app can get an access token in various ways depending on the architectural style of the app (see below). Although you can code the web service authorization calls explicitly, you normally should simplify your app by using the Google API client libraries available for many programming languages. And for many client-side JavaScript apps, you can handle most of the process just by including the Google Sign-In button and using the Google API client JavaScript library.

App architectural styles

Google Marketplace apps can be divided into three architectural styles:

  1. Web server apps: These run on the server side and often include an offline access authentication flow using service accounts (see below).
  2. Client-side apps: These are JavaScript apps that run in the browser, often using the Google Sign-In button to cache authentication details.
  3. Service accounts: These apps impersonate users to (a) implement administrative tasks and integration between systems, or (b) support offline access for web server apps.

Each of these styles has an associated authentication flow as described in the following section.

Authentication flows

The following descriptions explain the authorization flows for each of the architectural styles just defined.

Web server apps

Web server apps using languages such as PHP, Java, Python, or Ruby should handle authorization using the appropriate Google API client library. The authorization sequence begins when your app redirects a browser to a Google URL; the URL includes query parameters that indicate the type of access being requested. If successful, the response includes an authorization code, which your app can exchange for an access token and a refresh token.

Apps implementing offline access should use this flow to get identifying information such as Google ID and Email. An access token is returned but can be ignored. The app should then extract the user ID, making all subsequent calls using the service account flow.

Web server app auth flow

For more information, see Using OAuth 2.0 for Web Server Applications.

Client-side (JavaScript) apps

Client-side JavaScript apps run in a web browser, and should handle authorization using the JavaScript Google API client library. The authorization sequence begins when your app redirects a browser to a Google URL; the URL includes query parameters that indicate the type of access being requested. If successful, the response includes an access token, which the client should validate before including it in a Google API request. When the token expires, the app repeats the process.

You may use the Google Sign-In button in addition to the client library in order to simplify some of this process. The Google Sign-In button helps by starting the sequence and redirecting the browser to a Google URL as well as automatically generating a new access token as needed.

Client side app auth flow

For more information, see Using OAuth 2.0 for Client-side Applications.

Service accounts

Some Google Marketplace apps implement offline access: they are able to do processing on a user's behalf when the user is not logged in. These apps use a service account to impersonate a user and access resources on the user's behalf. This type of app is configured in the Google API Console, which provides a private key and client ID that you must save securely on your server. Your app also needs to get the user ID from an access token, as described above in "Web Server apps".

Your app uses the private key, client ID, and user ID to ask the Google OAuth 2.0 Authorization Server for an access token. The application then can use the token to access a Google API. When the token expires, the application repeats the process.

Service account auth flow

For more information, see the service-account documentation.