Configuring permissions on Google Cloud Platform

A guide to understanding Projects, Permissions and Accounts.

Google Cloud Platform uses multiple approaches for authorization and authentication across the various components and services of the Platform. This paper will help you navigate the tools and terminology so you can configure the permissions and authorization options in the Google Cloud Platform to protect your data, applications and development assets.

This document is intended for project owners and application developers as a guide to the choices, and to suggest practices that avoid common pitfalls.

Table of Contents


There are differences in the permission structures for Google App Engine, Google Compute Engine, Google Cloud Storage and the other Google Cloud Platform services. There are additional interactions and constraints for customers of Google Apps for Business.

With the continued evolution of the Google Cloud Platform and its documentation, configuring project permissions will become easier and more consistent. In the meantime, this document will help guide the new project developer to understand the issues and avoid potential problems.


This document assumes you are administering or developing applications and services on the Google Cloud Platform, and that you are possibly registered as a Google Apps for Business user. You are expected to have access to the Google Cloud Platform Console.

Terminology and basic concepts

When reading various online documentation and training materials, you may notice that some frequently used terms refer to related (but distinct) concepts. While each usage is correct in its own context, it may not always be clear which connotation is intended or assumed.

This section highlights important terms that may have multiple connotations:

Account has two meanings:

  • A billing account – The entity by which your Cloud Platform projects are billed; a billing account may be associated with a credit card or a Google Apps for Business account[1]
  • An identity associated with an email address – Examples include an Email account (with any email address), a Google account (Gmail or Google Apps) or a service account (an identity for running application code)

In this document, the term “account”, though used in multiple ways, will be paired with a descriptor to clearly indicate which type of account it refers to.

Domain refers to a DNS domain (or subdomain) name but is used with various connotations:

  • App Engine Domain – The DNS domain on which your App Engine application is served
  • Google Apps Domain – Identifies the DNS domain(s) of email addresses for the end-users that are in your Google Apps account

User may either refer to:

  • An external end-user – A user accessing your application by its external web interface
  • A “Team Member” of a Project – A user of the Google Cloud Platform tools and APIs
  • A member of a Google Apps domain – The user is identified by their email address in that domain

In this document we will explicitly use the phrases “end-user” or “Team Member” where the distinction is significant.

Project properties and identifying attributes

All Google Cloud Platform resources such as Compute Engine Virtual Machines, Cloud Storage Buckets and BigQuery Datasets, are associated with a project. Usage is metered against a project, permissions are checked against a project and credentials are managed against a project. A project has multiple Team Members who can use or manage the project’s resources.

It is important to distinguish between these identifying attributes of a project:

  • Project Name - An arbitrary label you provide, it is displayed but not otherwise used by the Google Cloud Platform
  • Project Number - A numeric value displayed on the project’s Overview page in the Cloud Platform Console that uniquely identifies a project
  • Project ID - An immutable alphanumeric value you can set up and use to identify a project when you first create it. This string is the same as the Application ID (App ID) for App Engine, and is the subdomain in the URL for your App Engine application.

Basics of Access Control, Authentication and Authorization

You can control three modes of project and application access:

  • Team member access: Allow developers to access, modify and deploy your application
  • Application access: Allow and control access to Google APIs from within your application
  • End-user access: Allow external users to access your App Engine application through the Internet

Team members - for development and administrative activity

Team members for a Project are assigned and managed in the console IAM & Admin pane for the project, where an owner can add new team members by entering their email address, which is associated with a Google account. If you are using a Google Apps domain, the administrator for your domain should first create the Google account from within the Users panel of your Admin Console.

Team members may be authorized to have one of three levels of access:

  • “can View” allows read-only access.
  • “can Edit” allows modify and delete access.
    This allows a developer to deploy the application and modify or configure its resources.
  • “is Owner” allows full administrative access.
    This includes the ability to add members and set the authorization level of team members.

You are advised to give “is Owner” permission to multiple team members for continuity in case a single Owner leaves the organization or has their account deleted for any other reason. If the sole owner’s account is deleted, then the entire project would also be deleted. The recommended practice is to use Google accounts for your project’s team members. When someone leaves the company, your Google Apps administrator should use the Google Apps Admin Console to mark the account as suspended (instead of deleting the account.) The domain administrator can then perform various tasks such as reassigning ownership of apps and docs before deleting the team member’s account.

Application access - for runtime access to resources and APIs

A typical Google Cloud Platform deployment will consist of two parts:

  1. Code that you’ve written – This code can be hosted on Google infrastructure or elsewhere, such as with other hosting providers, on-premise or under your desk
  2. Data stored in Google Cloud Platform services – Google Cloud Storage, Google Cloud Datastore, Google Cloud SQL and Google BigQuery

The Google Platform services control access to the data based on an access token supplied to the API by your application code. An access token represents the “proof of identity” of the code that is invoking the API. An access token is obtained in one of several ways, depending on where the code is running.

The ‘identity’ for your running code is defined by a service account. A service account has a public/private key pair for certificate-based authentication of server-to-server interactions. A service account is represented by an associated email address which can be used in access control lists. The service account establishes the long-term identity of your application, whereas an access token is a short-term representation of the access rights of your application to other services.

Google’s infrastructure automatically creates service accounts for your code when that code is hosted on Google Cloud Platform. How a service account is assigned and the way your application obtains the associated access token differs between Compute Engine and App Engine:

When your code is hosted elsewhere (for example, on another hosting provider or under your desk), you assign an identity by creating a service account with a downloadable private key. Use this key to sign an assertion of the application’s identity (a JWT) and request an access token from the authorization server.

Once you have a valid access token, add it as a header (“Authorization: Bearer <your access token here>”) to any API call against in order to identify your application. For additional details and examples, view this presentation.


The App Engine SDK includes support for end-user authentication based on the the user signing in with a Google account. By default, the authentication type is “any Google account”. You can change this by editing the console Application Settings for your project, but must do so before you deploy and allow users to access the application. For some use cases, you may want to restrict access to users in a particular Google Apps domain. Additional details and options are described later in this document.

Issues and recommendations

Choosing a project structure

Starting out, you may have a single project and a handful of team members working as developers. In that case, just create your project in the Cloud Platform Console. Then use the Permissions page of the project to identify and authorize each developer with “can Edit” permission.

Permissions are project-wide, which means that developers in a project can modify and deploy the application and the other Cloud Platform services and resources associated with that project.

If you have a larger and more complex operation, you may want to create multiple projects. In that case, you can assign different team members to each project.

Recommendations for test and dev environments

It is common to have separate projects and associated deployment environments for the various stages (development, test, production) of the release pipeline. For example, you may have one project for the development or integration environment (where many developers may be working) and separate projects, with more restricted access, for the QA/test and production environments. That allows controlled release and rollout by the members responsible for the critical project resources. Using related project names and App Ids for each project, such as project-dev, project-test, project-prod, makes it easy to identify the environment in use.

Developers can do much of their individual, pre-commit testing using the locally-runnable “Development Web Server” (also known as “Dev App Server”). The development web server provides a local sandbox application which can be run and debugged without interfering with the cloud-hosted deployments. The development web server simulates the App Engine runtime environment and all of its services, including the datastore. Using the RemoteApi, you can also can also test against your Cloud-based datastore or other services.

In some cases, developers may need to test in a Cloud Platform-based environment, for example to test external internet interfaces to the application. It is easy for developers to create and name a project (for example: projectmyuser), allowing them to deploy and test independently of the main projectdev integration environment.

Continuous Integration

Development teams should be committing their changes to a source control system. Most source control systems (like git or one of the associated variants) are able to trigger a rebuild and redeployment for each commit. A common approach is to use Hudson or Jenkins (or similar product) to notice the changed source files, initiate a build (using a build system like Gradle or Maven) and attempt the application deployment using command line tools and scripts. Use an OAuth token on your deployment server and the proper command line arguments.

Google Compute Engine: networks and firewalls

To restrict the flow of traffic between instances, Google Compute Engine offers a configurable and flexible networking system that enables you to specify permitted connections between the outside world and instances. You can manage your Google Compute Engine network by configuring three objects: the Network object, Firewall objects and individual instance settings.

Google Compute Engine: access to create and edit instances

If your project is enabled for Google Compute Engine, then the team members get access to all Google Compute Engine resources in that project as described by their roles, for example: viewer, writer or owner. If team members have edit permission, then they can modify instances and also access the instances using ssh. If team members are authorized as an owner, they are also able to create Google Compute Engine resources in the project.

Google Compute Engine: access to instances using ssh

To manage and configure your instances, team members can connect to a Compute Engine instance using ssh. The easiest way to ssh into an instance is to use: gcutil --project=<project-id> ssh <instance-name> from your local computer. Every time you run gcutil addinstance or gcutil ssh, gcutil checks for key files in your ~/.ssh directory. If there are no existing key files, gcutil will generate and store the keys for future use, so you won't need to set up keys for later projects.

Google App Engine modules

Within an App Engine project, modules is a feature that lets developers factor large applications into logical components that can share stateful services and communicate in a secure fashion. You can configure any module to accept requests from other modules in your app by adding the "login:admin" specification to the module's handler. In that case, any URLFetch from any other module in the app will be automatically authenticated by App Engine, and any URLFetch call from a module that is not part of the application will be rejected.

Cloud SQL

Controlling access to Cloud SQL is different. To access a Cloud SQL server from App Engine, you must register your application’s App ID in the Cloud SQL console page. To enable access from a Google Compute Engine instance, you must authorize the IP address of that instance. To enable an individual user to access a Cloud SQL instance, you must add the user's Google account name as a project member of the Cloud SQL project.

After a connection to a Cloud SQL server instance has been negotiated, the user or application must sign in to the MySQL instance using the MySQL authorization system. By default, all instances have a user named root with a blank password and full permissions on the instance. It is strongly recommended that you set a strong password for the root user, and create additional users to manage finer grained access to your database. See MySQL Access Privilege System for more information about managing MySQL users and granting access to the tables in your database.

Understanding authentication for your end-users

Google App Engine supports a ‘built-in’ authentication service for two scopes of authentication. Each of the following forms of authentication resolve the identity of a user to a unique string (you can also get the associated email address and other User properties, but those should not be used for identification):

  1. Allow anyone with a Google account to access the application. Anyone can get a Google account, and the App Engine will prompt the user to create one if necessary.

    This method is recommended as the simplest way to get your application up and running for public access.

  2. Allow only members of a Google Apps domain to access the application. This is ideal for “intranet” applications where access is limited to the users in your domain.

    This method can only restrict to a single Google Apps domain. This will not work if you use multiple domains with Google apps. If you are using multiple domains, then select “Allow anyone with a Google account” and extend your application code to restrict access to end-users that are from your set of Google Apps domains. Your application can use the value of the user_organization of the signed-in user (rather than parsing the email address) to determine the domain name of the user.

If development and test versions of your application are deployed, then it may make sense to configure them with access restricted to a small Google Apps domain populated by your developers and testers.

Note: To enable the members of a Google Apps account to access a restricted application, you also need to add the App Id to the Google Apps account through the Google Apps control panel. You can find instructions for doing this near the bottom of this article.

If you want to enable Federated login, the recommended approach is to use the Google Identity Kit (GITkit) for OpenID. To improve the user experience, GITkit supports an account chooser widget that selects from a variety of popular identity providers. In many cases it will enable a user to login to your site, even if they have never visited it before, simply by clicking the picture of the email address they want to use. To enable GITkit for your project, follow the instructions and examples in the online documentation.

Google recommends you take advantage of existing popular sign-in methods using GITkit, as discussed earlier. However, if that is not sufficient because you need to allow other types of users or need to apply fine-grained access control, then you can use your own authentication code or filters. Be aware, however, that creating your own identity and authentication framework is difficult to do securely.

Syncing with your corporate user directory

You can keep your Google Apps users and groups synchronized to an existing LDAP directory using Google Apps Directory Sync.

There are other service provider partners that can help you with more complex scenarios. For more information see Google Cloud Platform Partners or the Google Apps Marketplace.

Implementing Single Sign On

To implement Single Sign-On for an App Engine application so a user is authenticated by enterprise credentials, consider using SAML for SSO.


There are many factors to consider when configuring the permissions for your projects. With care and consideration, you can protect your applications and assets from unauthorized access while allowing your developers to provide applications and services for your users.

[2] This domain also is or becomes a Google Apps Domain, although that Google Apps Account may not have access to any Google Apps.

[4] Note that any and all applications on the VM instance can obtain the service account access token from the metadata server and thereby access services. This means you must secure access to the project and to the VM instance. In particular, if untrusted end-users have access to libraries or interpreters that might gain general access to the VM instance or your access tokens, then you should configure that server with no service accounts.

Send feedback about...