Access GSuite APIs on your domain using a service account

This tutorial provides a step-by-step guide to creating a service account that has delegated domain-wide access to your GSuite domain so that you can use various APIs to access and modify settings and data for your users.

My specific example simply accesses the Gmail sendAs addresses for any of the users in the domain. You could quite easily continue and modify Gmail signatures.

Many of the online tutorials on the subject focus on using OAuth user credentials that require consent to ensure that the relevant permissions are granted. Using a service account is quite straight forward but there are one or two steps that bit me so I’ve tried to write a step-by-step guide here.

Enable the GMail API

From the project, click on ENABLE APIS AND SERVICES and search for the Gmail API.

Click on ENABLE. You now have the Gmail API enabled for your project. All you need now is to create some credentials for using the API.

Create a Service Account

From the IAM tab click on CREATE SERVICE ACCOUNT

Give your new service account a name / ID. The identifier for my service account here is gmail-signature-updater@hazel-envoy-218810.iam.gserviceaccount.com

Click on CREATE. I don’t need to grant any other roles or permissions to the account at this stage so I simply CONTINUE through the next step.

Now we want to create a key and download it so that our code can provide credentials to the API. So click on CREATE KEY.

Choose the JSON option and click CREATE. You’ll be prompted with the JSON key file being downloaded. In my example the file is called hazel-envoy-218810–5b5a90e7bf98.json. Save this somewhere very safe (goes without saying… this contains the private key for your service account)

At the end of this simply click DONE and we’ve create a service account with a key pair as seen below.

Grant Domain Access to the Service Account

From that Service Accounts screen you are on, click on the account you just created (click on the “email” address). This brings up a page with the details of the account. You want to change the “Enable G Suite Domain-wide Delegation” setting so click on EDIT on the top and the select that checkbox.

When you select that checkbox, you’re prompted for the product name needed for the OAuth consent screen. A bit confusing admittedly as this is a service account, nevertheless, I simply called mine the Signature Updater and clicked SAVE at the end.

We now have a service account that has been granted Domain-Wide access. However, we haven’t told the GSuite domain yet what this account is allowed to do.

To do this we need to log into the admin console of the GSuite domain using an account that has sufficient admin permissions to make security changes.

From https://admin.google.com select Security then Advanced Settings and then Manage API client access. The page looks something like this:

We want to supply the identifier of the service account and the Scope of what it is allowed to do on the domain. For updating signatures, the scope is simply https://www.googleapis.com/auth/gmail.settings.basic. In the Client Name box we copy in the identifier for the service account we created. Referring back to some of our previous steps, the Client ID we created is 106900028520942987323. Put these in and click Authorize.

You’ll end up with an entry in the table for your client ID and the scopes granted it. This means that the service account we just created now has access to the basic settings of the Gmail settings.

The service account also has domain-wide delegation so we can use it to impersonate users on the Gmail API. We’re all set to dive into code.

Use the API

We start by creating the service object we want to use (the Gmail API) using the credentials we’ve created. Remember we downloaded the hazel-envoy-218810–5b5a90e7bf98.json file when we created keys for the service account, we use those credentials and then delegate access to the users in the domain that you want to access.

From these delegated credentials, you can call the API to access data and settings for that user.

The above code ends up with addresses containing the sendAs addresses for the user specified in USER_EMAIL. From here, you could simply loop over a list of the users you want or you can increase the scope of the service account and access one of the directory APIs for the domain.

Conclusion

From here one can play with any of the available APIs by simply granting that scope to the domain-wide account.

Note, the accounts, credentials and details provided in the examples above don’t exist. There is no use trying to access them.

A wolf in geeks clothing