This article describes the process of creating and registering a service account, and sharing a workspace with this account.
A service account is a special type of account that’s used to give limited permissions within the scope of a specific set of tasks. It’s necessary if you want to use a product like TensorFlow to apply machine learning algorithms to data in a workspace bucket. It’s also generally useful because it simplifies using Terra programmatically, as its better to authenticate programmatically with a service account rather than your full user account.
There are three steps:
- Creating a Service Account
- Registering the Service Account for Use in FireCloud
- Sharing a Workspace with the Service Account
1. Creating a Service Account
To create a service account, go to the Google Cloud Console and navigate to your Service Accounts section by selecting the IAM & Admin option in the main menu (note that you should use a non-Terra Google Project to do this):
Once you’ve found this page, click “Create Service Account” to make a new service account, and name it however you like:
After you’ve created the account, you have to do one last thing before moving on to the registering step: Under the “Actions” button by your service account, select the “Create Key” option. This will download a JSON file to your computer that you’ll need to use to authenticate your service account, as you’ll see in the next step.
2. Registering the Service Account for Use in FireCloud
In this step, you’ll register your service account by providing the credentials JSON file you generated at the end of the last step. The advantage of the service account is that it uses this “key file” to authenticate the account, rather than a traditional password. The first thing you’ll need to do is open your terminal and run the following activation command by authenticating your service account with Google. The command requires the file path to the location where you downloaded the file at the end of the previous step:
gcloud auth activate-service-account --key-file=[path to your SA credentials json file]
Once you’ve successfully done this, you can complete the registration process by running the command below. For more details on this step, see these instructions on Github.
docker run --rm -it -v "$HOME"/.config:/.config -v [path to your service account
credentials json file]:/svc.json broadinstitute/firecloud-tools python /scripts
/register_service_account/register_service_account.py -j /svc.json -e [email address
for owner of this service account, it's where notifications will go]
3. Sharing a Workspace with the Service Account
You should now be able to use the email address for that service account (which should also have been part of the output printed by that last registration command you ran in the previous step). It should look something like this:
[Service Account Name]@[autogenerated project name].iam.gserviceaccount.com
Simply share the workspace in question with this email account, making sure to select the right permissions, including adding the service account email to any necessary Authorization Domains, as described in these instructions for sharing workspaces.