This topic explains how to authenticate an application as a service account. For general information about authentication to Google Cloud APIs, including common authentication scenarios and strategies, see Authentication overview. For more information about service accounts, see service accounts in the Identity and Access Management documentation.
Finding credentials automatically
If your application runs inside a Google Cloud environment, and you have attached a service account to that environment, your application can retrieve credentials for the service account. The application can then use the credentials to call Google Cloud APIs.
You can attach service accounts to resources for many different Google Cloud services, including Compute Engine, Google Kubernetes Engine, App Engine, Cloud Run, and Cloud Functions. We recommend using this strategy because it is more convenient and secure than manually passing credentials.
Additionally, we recommend you use Google Cloud Client Libraries for your application. Google Cloud Client Libraries use a library called Application Default Credentials (ADC) to automatically find your service account credentials. ADC looks for service account credentials in the following order:
If the environment variable
GOOGLE_APPLICATION_CREDENTIALS
is set, ADC uses the service account key or configuration file that the variable points to.If the environment variable
GOOGLE_APPLICATION_CREDENTIALS
isn't set, ADC uses the service account that is attached to the resource that is running your code.This service account might be a default service account provided by Compute Engine, Google Kubernetes Engine, App Engine, Cloud Run, or Cloud Functions. It might also be a user-managed service account that you created.
If ADC can't use any of the above credentials, an error occurs.
The following code example illustrates how to use the ADC library in your application code. To run this example, you must install the Cloud Storage client library.
C#
Go
Java
Node.js
PHP
Python
Ruby
Passing credentials manually
If your application runs in an environment with no service account attached, such as on-premises or on another cloud provider, you should use workload identity federation.
If you can't use workload identity federation, then you must create a service account and one or more service account keys, which are credentials associated with the service account. Service account keys can then be manually passed to your application.
Make sure you review the best practices for managing service account keys.
Creating a service account
The following steps describe how to create a service account if you don't have one:
Create a service account:
In the Cloud console, go to the Create service account page.
In the Service account name field, enter a name. The Cloud console fills
in the Service account ID field based on this name.
In the Service account description field, enter a description. For example,
To provide access to your project, grant the following role(s) to your
service account: Project > Owner.
In the Select a role list, select a role.
For additional roles, click
Click Done to finish creating the service account.
Do not close your browser window. You will use it in the next step.
Create a service account key:
Console
Service account for quickstart
.
Set up authentication:
Create the service account. Replace NAME with a name
for the service account:
Grant roles to the service account. Run the following command once for each of the
following IAM roles:
Replace the following:
Generate the key file:
Replace the following:
gcloud
gcloud iam service-accounts create NAME
roles/owner
:
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE
gcloud iam service-accounts keys create FILE_NAME.json --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com
Passing credentials via environment variable
Provide authentication credentials to your application code by setting the
environment variable GOOGLE_APPLICATION_CREDENTIALS
. This
variable applies only to your current shell session. If you want the variable
to apply to future shell sessions, set the variable in your shell startup file,
for example in the ~/.bashrc
or ~/.profile
file.
Linux or macOS
export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH
"
Replace KEY_PATH
with the path of the JSON file that contains your service account key.
For example:
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
Windows
For PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH
"
Replace KEY_PATH
with the path of the JSON file that contains your service account key.
For example:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
For command prompt:
set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH
Replace KEY_PATH
with the path of the JSON file that contains your service account key.
After you've completed the above steps, ADC can automatically find your credentials, as described in the section above. We recommend using ADC because it requires less code and your code is portable in different environments.
Passing credentials using code
You can alternately choose to explicitly point to your service account file in code, as shown in the following example. You must install the Cloud Storage client library to run the following example.
C#
Go
Java
Node.js
PHP
Python
Ruby
Troubleshooting API errors
Learn more about how to troubleshoot failed API requests at Cloud APIs errors.
What's next
- Review our best practices for managing service accounts and service account keys
- Learn more about best practices for securing service accounts
- Learn about authenticating to a Google Cloud API
- Learn about authenticating as an end user
- Learn about using API keys
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Get started for free