When and how to use a service account in Terra

Yashasvika Duggal
  • Updated

Do you need to grant access to data that's stored in Google Cloud but outside of a Terra workspace? Learn a bit of the "under the hood" workings that let you interact with Google Cloud Storage and Google Cloud Compute -  without directly interfacing with the Google Cloud console. This article explains the basics of service accounts and best practices for interfacing directly with external cloud resources with a personal group.  

Overview: How Terra interfaces with Google Cloud

To maintain the high security required for working with controlled-access data in the cloud, Terra cannot use your user ID when interacting with cloud resources external to Terra. Instead, Terra creates and uses additional Google accounts (specific to you) called "pet service accounts." Terra also puts all of these "pet service accounts" into a convenient Google Group (specific to you) called a "Proxy Group."  

Pet service accounts

In addition to the user account you have registered with Terra, you also have one or more service accounts that Terra creates for you. A service account is a special type of Google account that lets Terra interface directly with Google Cloud on your behalf. For example, with a service account, your workflows and notebooks can access your data in Google Cloud. 

Your pet service account has the format:    

Best Practices: Use a Terra group instead of a proxy

Because the pet service account proxy group has such a long, un-human-friendly format, we recommend creating a Terra group (with a sensible name) as a proxy for your proxy. Managed groups include the proxy service account by default and are much easier to manage!

Managed group example

If your registered Terra account is j_doe@someplace.org, create a Terra Group named j_doe_at_someplace_org. Don't add anyone else to this group. You can then make grants to j_doe_at_someplace_org@firecloud.org. This group contains one member, the proxy group for j_doe@someplace.org. This is much easier for a human to recognize and remember.

Why use a Terra group for external access?While it's necessary for accessing resources that exist outside of Terra, the pre-defined Proxy Group identifier is not very human-friendly. If you're looking at a list of users with access to an external GCS bucket, seeing that there's a grant to PROXY_11564882405514439@firecloud.org is not helpful unless you happen to have a way to look up that Proxy Group.

By contrast, when you see j_doe@someplace.org, you will immediately know exactly who this grant covers. 

Note: This approach extends to when you actually want to make grants to groups of Terra users. It is better to add them all to a Terra group and then grant access to that group's firecloud.org Google Group.

Create your personal Terra group in four steps

1. Go to your Groups page ("Main menu" --> "Groups" from the top left of any page in Terra).
screenshot of Groups page on Terra highlighting vertical 3 lines on top of groups page with arrow and numeral 1, also highlighting the word Groups with numeral 2

2. In the Create a New Group card, click on the blue + icon.
screenshot of Groups page on Terra highlighting the words Create a New Group with an arrow pointing to a plus sign

3. Enter your human-friendly user-ID (can be the same as your Terra login) and click the Create Group button.
screenshot of Groups page on Terra with  Enter a unique name box overlaid on page

What happens

Terra creates a mirrored Google group that includes your Proxy (which already includes your user ID). When you (or the owner/admin) grant access on a Google Cloud resource to the <terra-group>@firecloud.org group, both your end-user credentials and your pet service accounts have access to the resource.  

Enabling access

To allow access to external resources, owners can now grant permission to your Terra group (i.e.  j_doe_at_someplace_org@firecloud.org) in GCP console.  
screenshot of Groups page on Terra with Group Management text showing the name of a fictional Terra group

Using "j_doe_at_someplace_org@firecloud.org" makes it easier to see who has access permissions!

Pro-tip: Granting permission to groups of Terra usersYou can extend this to groups of Terra users by first setting up a group for each person's Terra proxy (following the steps above).

Then create a managed group (i.e.your-lab-group) that includes all these personal groups.

To give permission to everyone in the group, you would grant access to your-lab-group@firecloud.org. Since you can add or remove group members right in Terra, it's easy to adjust who has access.

How to find your proxy group

1. On the upper left-hand side, click on the main menu (three lines at the top of any page on Terra).

2. Next to your name, click the drop-down arrow

3. Click to expand the profile section under your name. 

screenshot of highlighted word Profile on upper lefthand corner of profile page in Terra

4. You'll see your proxy group listed near the bottom left.

screenshot of highlighted words Proxy Group near bottom lefthand corner of Terra page

Additional resources

Want to learn how to access advanced Google Cloud features not (yet) available in Terra?

  • WRITE to BigQuery
  • Interact with Cloud Storage buckets other than the workspace bucket
  • Run dsub jobs
  • Run Cloud Dataflow jobs
  • Run Cloud ML engine jobs

See Accessing Google Cloud features that are not in the Terra UI.

Additional recommendations

See Best practices for accessing external resources (Google buckets, Google Cloud VMs, etc.).

Was this article helpful?



Please sign in to leave a comment.