This article shows the recommended way to authenticate to a Cloud API.
Authentication refers to the process of determining a client's identity. Authorization refers to the process of determining what permissions an authenticated client has for a set of resources. That is, authentication refers to who you are, and authorization refers to what you can do.
For authentication, we recommend using a service account: a Google account that is associated with your GCP project, as opposed to a specific user. Service accounts can be used for authentication regardless of where your code runs (locally, Compute Engine, App Engine, on premises, etc.). For more information about other authentication types, see authentication overview.
Creating a service account
GCP Console
-
In the GCP Console, go to the Create service account key page.
Go to the Create Service Account Key page - From the Service account drop-down list, select New service account.
- In the Service account name field, enter a name .
From the Role drop-down list, select Project > Owner.
Note: The Role field authorizes your service account to access resources. You can view and change this field later by using GCP Console. If you are developing a production app, specify more granular permissions than Project > Owner. For more information, see granting roles to service accounts.- Click Create. A JSON file that contains your key downloads to your computer.
Command line
You can run the following commands using the Cloud SDK on your local machine, or within Cloud Shell.
-
Create the service account. Replace [NAME] with your desired service account name.
gcloud iam service-accounts create [NAME]
-
Grant permissions to the service account. Replace [PROJECT_ID] with your project ID.
gcloud projects add-iam-policy-binding [PROJECT_ID] --member "serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com" --role "roles/owner"
Note: The Role field authorizes your service account to access resources. You can view and change this field later by using GCP Console. If you are developing a production app, specify more granular permissions than Project > Owner. For more information, see granting roles to service accounts. -
Generate the key file. Replace [FILE_NAME] with a name for the key file.
gcloud iam service-accounts keys create [FILE_NAME].json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
Setting the environment variable
If you plan to use a service account, you need to set an environment variable.
Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. Replace [PATH] with the file path of the JSON file that contains your service account key, and [FILE_NAME] with the filename. This variable only applies to your current shell session, so if you open a new session, set the variable again.
Linux or macOS
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
For example:
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/[FILE_NAME].json"
Windows
With PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
For example:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"
With command prompt:
set GOOGLE_APPLICATION_CREDENTIALS=[PATH]
Setting the environment variable allows you to provide credentials separately from your application, without making changes to application code when you deploy. Alternately, you can explicitly specify the path to the service account key file in your code. For more information, see the production guide.
Verifying authentication
After setting the environment variable, you don't need to explicitly specify your credentials in code when using a Google Cloud Client Library. The client library can determine your credentials implicitly. For this reason, you can verify that authentication works by setting the environment variable, and then running client library code, such as the following example. If the request succeeds, authentication works.
You must install the Cloud Storage client library to run the following example.
C#
Go
Java
Node.js
PHP
Python
Ruby
What's next
-
Learn about setting up authentication for server to server production applications.
-
Learn about setting up authentication as an end user.
-
Learn about using API keys.