Configure App Engine service accounts

App Engine applications require a service account to access other Google Cloud services and execute tasks.

There are two types of service accounts in App Engine and any service account in your Cloud project can be assigned to act as either the app-level default or per-version service account:

• App-level default service account - This service account is used for all of your deployed services when you do not configure a "per-version service account". You can choose to assign a service account that you created or use the auto-created default service account that gets created when you initially deploy a service to your Cloud project. For example, the App Engine default service account ([e-mail]).

• Per-version service account - A service account configured as the identity for a specific version of your deployed service. When deploying an existing version or a new version, you can specify a service account to act as that version's identity. For example, if a version requires permissions that differ from the app-level default service account, you can assign a service account that is specific to that version.

View your configured service accounts

To view the current app-level default service account, run the gcloud app describe command.

To view the service account used by a deployed version:

gcloud

Run the gcloud app versions describe command:

  gcloud app versions describe VERSION_ID --service=SERVICE_NAME

Replace:

• VERSION_ID with the ID of the version.
• SERVICE_NAME with the name of the service that you created.

Console

1. Go to the App Engine Versions tab in the console. Go to Versions
2. Locate the email address of your App Engine version-specific service account. Example: SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Assign an app-level default service account

By default, the app-level default service account is the auto-created [e-mail] service account. You can assign another service account to act as the app-level default service account using Google Cloud CLI, Google Cloud console, or Admin API.

Specify an app-level default service account during app creation

During the initial App Engine application creation process, you can choose to assign a service account that you created or use the auto-created [e-mail] service account to act as the default.

To create a your App Engine application and assign an app-level default service account, you can use one of the following:

gcloud

Run the gcloud app create command:

gcloud app create --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

• SERVICE_ACCOUNT_NAME with the name of the service account that you created.
• PROJECT_ID with ID of the Google Cloud project in which you want to assign the service account.

Console

1. Go to the App Engine page:

   Go to App Engine

2. Create a Google Cloud project.

3. In the Create App section, select a service account from Identity and API access.

Update the app-level default service account for your app

To update the app-level default service account for your application, you can use one of the following to assign a new service account:

Important: Only versions deployed after the update will use the new app-level default service account. All previously deployed versions will not use the new app-level default service account until you re-deploy that version.

gcloud

Run the gcloud app update command.

    gcloud app update --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

• SERVICE_ACCOUNT_NAME with the name of the service account that you created.
• PROJECT_ID with ID of the Google Cloud project in which you want to assign the service account.

Each new version that you deploy hereafter uses the new app-level default service account unless you explicitly assign a version-specific service account.

Console

1. Go to the App Engine Application Settings tab in the console and click Edit Application Settings.

   Go to Application Settings

2. Choose an app-level default service account from Select a Service account and click Save.

   You will be redirected to the Application Settings tab where you can view the email address of your updated app-level default service account. Example: SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

   Each new version that you deploy hereafter uses the new app-level default service account unless you explicitly assign a version-specific service account.

Deploy with a version-specific service account

You can set a version-specific service account only during the deployment of new versions. Using a version-specific service account enables you to grant different privileges to each application version, based on the specific tasks it performs, and avoid granting more privileges than necessary.

You need to have an existing service account before deploying your application.

Note: If a version-specific service account is specified in both the app.yaml file and in the gcloud CLI, the gcloud setting takes precedence.

Set a version-specific service account

gcloud

Run the gcloud app deploy command:

  gcloud app deploy --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

• SERVICE_ACCOUNT_NAME with the name of the service account that you created.
• PROJECT_ID with ID of the Google Cloud project in which you want to assign the service account.

app.yaml

In your app.yaml file, specify your service account by adding the service_account element:

service_account: SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

• SERVICE_ACCOUNT_NAME with the name of the service account that you created.
• PROJECT_ID with ID of the Google Cloud project in which you want to assign the service account.

appengine-web.xml

If you use the Java 11/17 runtimes and include the App Engine legacy bundled services, specify your service account by adding the <service-account> element in your appengine-web.xml file:

<service-account>SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com</service-account>

Replace:

• SERVICE_ACCOUNT_NAME with the name of the service account that you created.
• PROJECT_ID with ID of the Google Cloud project in which you want to assign the service account.

App Engine default service account

By default, the auto-created [e-mail] service account has the Editor role in the project. If you deploy your App Engine app using the auto-created [e-mail] service account, your app can access all resources in the project.

For the auto created [e-mail] service account, if you use an organization policy constraint to prevent the default Editor role from being granted automatically, you must update the roles manually. The roles you grant to the App Engine default service account need to enable the app to access the resources it requires. To learn how to grant roles to service accounts and other principals, see Manage access to service accounts.

For modifying permissions, deleting, and restoring your service accounts, see Creating and managing service accounts.