The Google Cloud docs can help with different parts of your job. Sometimes you want to learn a new service or see a feature in action. On another visit to the docs, you might need to develop an application for production use.
Our docs are often written to help you get a service or feature up and running. In a production or development environment, there might be some security best practices to consider for your organization. You might need to authenticate your applications differently than shown in the docs.
To help pick the right authentication method for your applications, use the following decision tree. The rest of this article explains each of the secure ways to authenticate your applications.
Overview of Application Default Credentials
Most of the time, you want your code to make API requests. You can use a strategy called Application Default Credentials (ADC) to automatically find the required credentials and authenticate your application. All Google Cloud Client Libraries support ADC.
With ADC, you can develop locally using one authentication method, then authenticate with a different method when deployed to test or production. There's no code changes required as you move between the different deployment environments and supported authentication methods.
The client libraries determine what authentication methods are available for use. ADC then selects the correct authentication method for your application to make API requests, regardless of whether you're developing locally or running in production. Where possible, look to use ADC for your applications.
Local development and testing with the
gcloud command-line tool
In this scenario, you use the
gcloud command-line tool to make configuration changes to
your project using the Cloud APIs, or write code to test new integrations with
those APIs. This type of interactive use is mostly for development and testing
on your local machine. You provide your own credentials to sign in to the
gcloud command-line tool. This approach lets you track the identity that made the API
request and manage quotas or provide an audit trail for security purposes.
To authenticate interactively with the
gcloud command-line tool to issue your own
commands and make configuration changes, use the
gcloud auth login
command and specify a user-owned billing project with the
flag. Calls to some Cloud APIs, such as for Cloud Translation API or Cloud Vision API,
fail without the user-owned billing project set.
To have your code make Cloud API calls from your local development environment, use the Google client libraries and ADC. To do this, use the gcloud auth application-default login command and specify a user-owned billing project with the --billing-project flag. Again, calls to some Cloud APIs, such as for Cloud Translation API or Cloud Vision API, fail without the user-owned billing project set.
Don't assign your account a role that grants more permissions than are required to make the Cloud API requests for your application. Identity and Access Management (IAM) recommender can review what permissions haven't been needed in the last 90 days so you can remove them.
Within Google Cloud environments
In this scenario, your application code runs in Google Cloud and uses Serverless or the Compute product family, such as Compute Engine VMs, Cloud Run, App Engine, Google Kubernetes Engine (GKE), or Cloud Functions. Because the applications run in the Google Cloud environment, use default credentials.
With default credentials, your application retrieves the identity token associated with the virtual instance that runs your code. The identity token is retrieved from a metadata server that runs on the virtual instance. This token can then be used to authenticate and make Cloud API requests using the ADC.
There's nothing you need to do differently to use default credentials because they're part of the ADC. You don't need to change your code or create and manage service accounts and keys rotation.
On-premises data center or other cloud provider
In this scenario, your application code runs in your own data center infrastructure or in another cloud provider such as AWS or Azure. If there's support for OpenID Connect (OIDC), use identity federation for external workloads and create a workload identity pool for each environment to provide authentication for your applications.
With identity federation, you can use Identity and Access Management (IAM) to grant external identities IAM roles, including the ability to impersonate service accounts. This approach lets you access resources directly using a short-lived access token.
Example identity providers include:
- Azure Active Directory
- On-premises Active Directory
- Kubernetes clusters
If you don't have support for OIDC or don't want to use identity federation, you can create user-managed service accounts. These service accounts are covered in the next section. Take care to securely store these credentials in a digital vault your provider may offer, such as AWS Secret Manager or Azure Key Vault. Don't write these credentials to disk except in an encrypted form.
User-managed service accounts
In this scenario, your code isn't running inside Google Cloud or an environment that supports OpenID Connect and identity federation. So long as the environment is considered trusted and there's no Organization Policy Service constraints to prevent their use, you can use service accounts to authenticate your applications. ADC works with service accounts, so your applications can automatically use different authentication methods in different deployment environments.
A service account is a special type of account used by an application, not a person. Each service account is associated with public/private RSA key-pairs that are used for authentication. Make sure there's little risk of the environment being compromised and of the service account keys being exposed. To protect any keys that you export and minimize potential security risks, review the service account keys best practices.
You can also use a self-signed JWT (JSON Web Token) or OIDC token with your service account to avoid an unnecessary round trip to acquire tokens. For more information, see how to make an authenticated request with JWTs to a Cloud Endpoints API.
Service accounts perform actions on your behalf, but they might have excessive permissions assigned and often aren't deleted when no longer needed. Identity and Access Management recommender can review what permissions haven't been needed in the last 90 days, and you can identify unused service accounts that should be removed.
Semi-trusted or restricted environments
In this scenario, your application code runs in a semi-trusted environment or has policy restrictions enforced that limit what actions can be performed. Don't use service accounts in these environments to authenticate and make Cloud API requests.
Organization Policy Service might be used to enforce constraints on your project that limit you from communicating with resources that run within other projects, especially in production deployments.
As each environment is unique and different security requirements may apply, review any service-specific guidance that might affect you. Work with your operations and security teams to design the best solution for your needs.
At a high level, you need to design a system that lets you securely get a short-lived access token. The following design considerations apply:
- The token should last long enough for your app to run, or is refreshable.
- Narrowly scope the token to the roles required.
- Don't write the token to disk.
Some example solutions may include accessing an on-premises digital key management such as Hashicorp Vault , or limiting access to Cloud Run and then automatically retrieving credentials from Secret Manager or encrypted credentials from Cloud Key Management Service.
You can also reach out to Google Cloud Consulting for help with designing and building a secure solution.
If you use JWT or OIDC tokens as part of your application's authentication process, the tokens are valid for the duration of their lifetime. To reduce risk of exposure, configure the token lifetime to be a little longer than you expect your job to run. For example, if a token is needed for 15 minutes as your job runs, configure the token lifetime to 20 minutes.
You can't revoke these tokens other than deleting the parent service account. Again, take care with assigning token lifetime policies to reduce how long a potentially compromised token would remain usable.
Service account keys could be stolen and used to generate credentials in a mostly untraceable way forever or until the next key rotation. To protect any keys that you export and minimize potential security risks, review the service account keys best practices such as key rotation and auditing.
If needed, you can delete service account keys so they can't be used anymore.
For more information on the use of credentials in applications, see Best practices for managing credentials.