Getting started using Google APIs: Service Accounts (Part 1)

TL;DR:

Use of Google APIs requires one of three (3) different credentials types, and which you use depends on both the API as well as who owns the data that API provides access to. API keys and OAuth client IDs are covered elsewhere; this post kicks off our look at service accounts, the typical credential type used for Google Cloud (GCP) APIs. Lesser known: service accounts are also used to manage Google Workspace (GWS) domains. If using GCP APIs, managing GWS domains or using the GAM tool to do so, you're probably in the right place. On the other hand, if you only use other Google APIs (non-Cloud), this content is (likely) optional. After this intro post, you will: 1) know what service accounts are, 2) when they're typically used, 3) what types of service accounts exist, and 4) what they look like.

Introduction and motivation

Welcome to the blog dedicated to using Google APIs from Python (and sometimes Node.js). Regardless of which APIs you care about, I try to put "oil" for any onboarding friction you may encounter. I especially like to cover content that's not in Google's documentation. Here are some topics covered on the blog so far:

• Google Cloud/GCP (AI/ML, serverless)
• Google Workspace/GWS (Gmail, Drive, Docs, Sheets, etc.) and this series
• YouTube
• Maps
• Gemini
• Credentials (API keys, OAuth client IDs, service accounts [this post])

Before diving into service accounts, let's do a quick overview of the different credentials types to provide context for where service accounts come into play.

Credentials & authorization overview

Google API access has an element of authentication ("authn;" you are who you say you are) and mostly authorization ("authz;" do you have data access via API). Your Google, Gmail, or Workspace account addresses the first: you need to successfully log into your account. The latter is addressed by credentials.

Google APIs support three different "credentials" types:

1. API keys
2. OAuth client IDs
3. Service accounts

Which is required by an API depends on who owns the data it accesses, as illustrated in this chart:

Credential type	Data accessed by API	Example API families
API key	Public data	Maps APIs
OAuth client ID	Data owned by (human) users	GWS APIs
Service account	Data owned by apps/projects	GCP APIs

 

1. API keys -- for APIs that access public data, e.g., looking for places on Google Maps, sending a picture to the GCP Vision API, searching YouTube for videos, sending a sentence to the GCP Natural Language API for analysis, and so on. Because all Maps APIs access public data, expect to only use API keys.
2. OAuth client IDs -- for APIs that access data owned by (human) users. Your app needs a user's permission (in the form of "scopes") to access their documents on Drive, their messages in Gmail, videos in a user's YouTube playlists, and so on. Since Workspace data is almost always personal data, expect to use OAuth client IDs with all GWS APIs.
3. Service accounts -- for APIs that access data owned by an app or project. For cloud-based apps, there's no human to prompt for permissions, plus the data isn't owned by humans anyway. Authorization is implicitly granted via service account and IAM (identity and access management roles) and public-private key-pairs created with those specific permissions. As you can also guess, "cloud-based" primarily means GCP APIs.

Some Google APIs accept more than one type of credentials. For example, while you'd typically use service accounts with the GCP Cloud Vision API, sending an image (rather than reading a file from someone's Google Drive or a GCP project's Cloud Storage bucket) is considered "public data," so an API key works.

Another sample app I wrote uses OAuth client IDs to call the Vision API. The images are read from a user's Google Drive, so I was already using OAuth client IDs. Adding use of an API key or service account mixes credentials, making the code harder to read/understand. While API keys suffice, stricter credentials (OAuth client IDs or service accounts) are acceptable for the Vision API.

Service accounts

The world of service accounts is vast, and it will take more than one post to present the broad usage available. For this intro post, it's important to keep it at a high-level to introduce the concepts so you know what they are. We can dive deeper in upcoming posts.

Service accounts are peo... principals too

Before taking a step further, I need to clarify that service accounts themselves are just principals, which you can think of as "users" in the general sense. Most of the time, principals refers to human users whose accounts are identified by email addresses. A service account is also a principal because it is also identified by an email address... it just doesn't belong to a person. You can think of a service account mildly as a "robot account."

How service accounts differ from user authz

So where does the "credential" part come into play? As discussed earlier, service accounts are primarily used when running applications that access cloud resources, data owned by a cloud project and not human users.

When OAuth IDs are involved, you have one or more human developers (mainly you) and one or more human end-users. Whoever is running your code, the owner of the data, must grant the permissions required by your app in order for it to function. Those permissions come in the form of scopes. (Some scopes required more scrutiny before your app can be made available for users.)

When you write an app and test it yourself, you play both roles: you're the developer as well as the end-user who owns the data. But we're not talking user-owned data now, so OAuth client IDs aren't going to work. The data lives in the cloud, and there's also no end-user to ask for permissions.

To summarize, a service account is a principal that is given pre-determined privileges to access the data it needs to access. Rather than permission scopes, service account permissions come in the form of Identity and Access Management (IAM) roles and permissions. You don't prompt a user for permissions when they (those permissions) have already been granted.

For additional reading, I recommend this Google Cloud blog post which states two clear points:

1. "Service accounts represent non-human users and... are intended for scenarios where an application needs to access resources or perform actions under its own identity."
2. "Unlike normal users, service accounts cannot authenticate using a password or single sign-on (SSO)."

Service account types

In total, there are three (3) different types of service accounts:

As just mentioned, most of the time, your app will be using user-managed service accounts. Default service accounts are a different beast, "user-managed" but Google-created service accounts for specific platforms, like App Engine or Compute Engine.

App Engine apps and Compute Engine VMs can call many GCP APIs because default service accounts give broad permissions and are attached to those platforms, simplifying the prototyping experience. While they do their job at getting your app kickstarted, when moving towards production, switch to user-managed service accounts with locked-down permissions, just enough for your app to function correctly and adhere to the principle of least privilege.

Service agents are "the easiest." They're service accounts you don't need to think about. They're created by Google and only used by Google, custom-made for specific products. They help each GCP product "do their jobs."

Service account formats

Now you know what kinds of service accounts there are, how about what they look like? You know they're email addresses, but I have to tell ya: They're not pretty to look at. Here are some examples:

1. google@appspot.gserviceaccount.com
2. 123456789-compute@developer.gserviceaccount.com
3. firebase-adminsdk-y7bg@google.iam.gserviceaccount.com
4. svcacct1@google.iam.gserviceaccount.com
5. service-123456789@container-engine-robot.iam.gserviceaccount.com
6. service-123456789@serverless-robot-prod.iam.gserviceaccount.com
7. 123456789@cloudservices.gserviceaccount.com

Doesn't seem to be clear which ones are user-managed, default, or service agents. While they vary greatly, you'll notice they all have a "domain name" of gserviceaccount.com, so that's your sign it's some kind of service account. Most of the time, the ones you make and use will likely resemble the one in the middle, #4. That's an example of a user-managed service account, one created by you. The chart below will help you determine what kind of service accounts you see:

... where ...

Email address component	Description
SERVICE	Something that somewhat identifies the GCP service your app is using
SVC_ACCT	Service account name you chose
PROJECT_ID	Project ID (not to be confused with project number)
PROJECT_NUM	Project number (not to be confused with project ID)
HASH	Short, random hash value

 

The first pair are default service accounts. These are the service accounts described earlier that are automatically-created providing broad permissions to help your App Engine or Compute Engine apps get off the ground quicker, enabling those apps to call many GCP APIs. User-managed service accounts will be the ones you use the most. The final three are service agents, created by Google and only "for internal use" by the GCP project they were created for.

All projects have names, IDs, and numbers. You choose the first. Project IDs are strings that uniquely identify a project while project numbers are Google-generated numeric values, also uniquely identifying projects. Any confusion between these three (3) can be clarified with this page in the documentation.

Using service accounts with Workspace

While most service account usage takes place in GCP, e.g., applications running on GCP compute platforms that call GCP APIs, or accessing data in GCP data products, there is a use case for using service accounts with GWS. When managing many end-users in Workspace domains, domain administrators often have to perform maintenance tasks on behalf of their users. For this purpose, they can use service accounts with domain-wide delegation.

Doing so allows, "internal and third-party apps to access ... users’ Google Workspace data, bypassing end user consent. To do this,... create a service account in the Google Cloud console and delegate domain-wide authority to the account in [the] Google Admin console." Without requiring permissions from every user in the domain, admins can get important tasks completed in a timely fashion. Obviously, this grants broad permissions to admins. With great power comes great responsibility, so admins are advised to adhere to domain-wide delegation best practices.

Summary and next steps

This introductory post on service accounts covered basics such as how service accounts differ from other Google API credentials types like API keys and OAuth client IDs. They access private data requiring authz but where you have data that live in the cloud, and belong to a Cloud project rather than a human user, and where there are no human users to request authz anyway. They are a principal but are given pre-determined Cloud IAM permissions.

There are different types of service accounts, including default service accounts and service agents. However, the primary type of service account you interact with are user-managed service accounts. Each of these service account types come in various formats.

While service accounts are typically used for apps or data that live in GCP, service accounts may also be useful for GWS domain administrators who have to perform maintenance tasks on behalf of end-users. In such cases, service accounts with domain-wide delegation can complete those tasks without requiring user consent.

Wrap-up

Now that you know what service accounts are, when you'd typically use them, what types of service accounts exist, and what they look like, I'll show you how to use them in upcoming posts. If you found an error in this post or would like me to cover a specific topic besides service accounts in future posts, let me know in the comments below. I enjoy meeting users on the road... see if I'll be visiting your community in the travel calendar on my consulting page.

NEXT POST: Getting started using Google APIs: Service Accounts (Part 2: How to use [TBD])

ALTERNATIVE 1: Getting started using Google APIs: API Keys series
ALTERNATIVE 2: Getting started using Google APIs: OAuth client IDs series

References

Below are various resources relevant to this post which you may find useful.

• Quick intro to service accounts
• Full overview of service accounts
• Types of service accounts
• Service account credentials
• Best Practices
• Principle of least privilege
• Service accounts blog post
• GWS domain-wide delegation with service accounts
• Domain-wide delegation best practices
• GAM GWS domain admin management tool

---

WESLEY CHUN, MSCS, is a Google Developer Expert (GDE) in Google Cloud (GCP) & Google Workspace (GWS), author of Prentice Hall's bestselling "Core Python" series, co-author of "Python Web Development with Django", and has written for Linux Journal & CNET. He runs CyberWeb specializing in GCP & GWS APIs and serverless platforms, Python & App Engine migrations, and Python training & engineering. Wesley was one of the original Yahoo!Mail engineers and spent 13+ years on various Google product teams, speaking on behalf of their APIs, producing sample apps, codelabs, and videos for serverless migration and GWS developers. He holds degrees in Computer Science, Mathematics, and Music from the University of California, is a Fellow of the Python Software Foundation, and loves to travel to meet developers worldwide at conferences, user group events, and universities. Follow he/him @wescpy & his technical blog. Find this content useful? Contact CyberWeb for professional services or buy him a coffee (or tea)!