In the last post, we looked at how application default credentials differ from your personal gcloud credentials and why the idea of application default credentials is particularly useful for developing server-side applications.
If your plan is to develop a tool or desktop app instead of a server-side application, the benefits of application default credentials are less obvious and reusing the user’s personal gcloud credentials instead might seem attractive. But there are some pitfalls.
Using application default credentials
When you develop a tool, script, or desktop application that needs to access Google Cloud APIs, you can
rely on application default credentials for authentication. A clear advantage of relying on application
default credentials is that it is easy – all you need to do is call
(or its equivalent, like
google.app.default() in Python).
Another advantage is that application default credentials are issued for the OAuth scope
https://www.googleapis.com/auth/cloud-platform. That is, these credentials give you access to all Cloud APIs.
But there is also a clear disadvantage to this approach – on a user’s workstation, trying to load application default credentials is quite likely to end in an error:
- Users usually do not (and should not!) have any service account key file on their machine.
- It is unlikely that the user runs the tool on Compute Engine, Kubernetes Engine, Cloud Run, or App Engine.
- The user might not have run
gcloud auth application-default login(few users do), or might not even have the Cloud SDK installed.
If the tool is aimed at developers, requiring the Cloud SDK as prerequisite might be acceptable – and anybody who has the Cloud SDK installed is likely to have stored personal gcloud credentials. So how about we simply load these personal gcloud credentials instead of application default credentials instead?
Using a user’s personal gcloud credentials
The official and “right” way to access a user’s personal gcloud credentials is to run
gcloud auth print-access-token or
gcloud auth print-identity-token to obtain an access token or
IdToken, respectively. Especially for scripts, this approach usually works well and is easy to implement.
But for more complex tools, there are two limitations that can make the “right” way seem less appealing:
gcloud auth print-access-tokenis slow – it can easily take multiple seconds to obtain a token.
- The access token is short-lived and will expire after an hour. Refreshing the token will require you to
gcloud auth print-access-tokenagain.
There is a second, unofficial way to obtain a user’s personal gcloud credentials – and that is to reach into the gcloud folder structure:
- Look up the active account in the
This process is fast and the result is a proper
GoogleCredential (if you use .NET) that will automatically
take care of refreshing tokens. That sounds great – but unfortunately, there are a few problems with this
approach as well.
The first problem is that you are relying on an implementation detail. At some point,
gcloud might drop
support for legacy credentials in which case your code might stop working.
The other problem is less obvious: If you use a custom GCP session length,
adc.json might fail with an
indicating that a re-authentication is required.
The only way to perform such a re-authentication is to run
gcloud – and because
gcloud might prompt the
user for credentials, this has to be done in the foreground, not in the background. However, depending on the
tool that you are writing, having to run
gcloud might either defeat the intent of not having to spawn gcloud
processes or might not be viable at all.
Using a custom OAuth client ID
The third, and arguably the cleanest way to authenticate a user is to register a custom OAuth client ID and to perform a 3-legged OAuth authorization flow.
By using a custom client ID, you avoid any dependencies on
gcloud and gain full control over how and when to
authenticate a user. Once a user has authenticated, your tool will also be listed on
myaccount.google.com under Apps with access to your account, giving the
user the ability to revoke access at any time.
Coming along with additional flexibility afforded by using a custom OAuth client ID is the responsibility to securely store refresh tokens. If you use the .NET client library, you can use the FileDataStore class for this purpose. However, be aware that this class stores tokens in plan text, so it is far from ideal from a security perspective. A better option is to use DPAPI to encrypt the tokens, and then store them in the user’s (roaming) user profile, either as a file or registry value. For an example on how this can be implemented, take a look at the Cloud IAP plugin source code.
Depending on the OAuth scopes that your took needs access to, you also have to get your client ID whitelisted. Google classifies OAuth scopes into three sets:
- Restricted scopes. These are scopes that allow an application to access GMail or Google Drive data, which is considered particularly delicate.
- Sensitive scopes. These are scopes that permit access APIs and data that are not quite as delicate as GMail and Google Drive, but still somewhat risky. Pretty much all Google Cloud APIs fall into this class.
- Other scopes. This includes all scopes that are not restricted or sensitive.
You can see whether a scope is considered restricted or sensitive when you create your OAuth client ID in the Cloud Console:
If your tool does not need access to sensitive or restricted scopes, then you can simply create an OAuth client ID in the Cloud Console, and you are all set. For restricted or sensitive scopes, your application needs to be verified first.
The idea behind verification is to prevent applications from requesting too many permissions.
In theory, the OAuth user screen should be enough of an incentive for application authors to request as few scopes as necessary and also enough to incentivize users to be careful about authorizing applications that request more permissions than seems appropriate. In practice, users are often not that careful – so the verification process is a way to nudge (or even force) developers to do the right thing.
The exact process for verification depends on the nature of your application and the exact scopes it needs access to. Getting a client-side tool that needs access to few and narrow OAuth scopes verified is usually fairly straightforward. In contrast, verification for a server-side application that needs access to broad scopes (such as ../auth/cloud-platform) might be a bit challenging.
For server side applications, using application default credentials is almost always the way to go. For tools and desktop apps, application default credentials are a good choice if the tool is targeting developers who are likely to have the Cloud SDK installed and are familiar with using gcloud. In pretty much all other cases, consider registering a custom OAuth client ID, even if it means having to get your app verified.
The only legitimate cases where I think using a user’s gcloud credentials makes sense is when your tool or application integrates tightly with gcloud or if a workflow requires a user to switch back and forth between gcloud and your tool. In these cases, sharing credentials across gcloud and your application can help reduce friction and ensure a smooth user experience. In all other cases, it’s best not to even try to use the user’s personal gcloud credentials.« Back to home