Creating a GCP Service Account for MBPY

Problem & Context

The MBPY utility enables schools to populate Google Spreadsheets and Google BigQuery with ManageBac data. To do this, MBPY must authenticate with the school's Google Cloud Platform (GCP) domain.

The following instructions explain how to connect MBPY to your school's GCP.

Creating a Service Account

A service account is a special account within GCP that allows applications to authenticate and interact with Google services. A user with Administrator privileges must create this account. Once set up, MBPY will use it for authentication.

The service account is required for either BigQuery or Spreadsheet services.

Steps to Create a Service Account

1. Access the GCP dashboard
2. Create a project, for example called "MBPY project". A project is the container for settings in the GCP, and will become the parent container for the service account that will be created in the next steps.
   
   1. Help on creating and managing projects is available via GCP help docs.
3. Navigate to "IAM" (Identity Access Management) area, and navigate to that area within the project
4. Go to "Service Accounts" section of the IAM area of the project.
5. Click "Create Service Account"
   1. Google help file for creating service accounts is here.
   2. Fill out the service account name, ID, and description as desired
   3. Granting access to project or granting users to the service account is optional
6. Download the service account credentials
   1. Click on the three dots of the service account, and select "Manage Keys"
   2. Click "Add Key"
   3. "Create new key"
   4. Key type: JSON
   5. The credentials will download to your computer
   6. This is the credentials file 

For BigQuery Services

1. Assign permissions in IAM
   1. In GCP, go to IAM & Admin (make sure you are on the project created for MB)
   2. Click "Grant Access"
   3. Add the service account you created earlier as 'New principal'
   4. Give it an 'Data Editor' role
   5. Give it the `bigquery.jobs.create` permission
2. Grant Access to BG
   1. In BQ, create a dataset for MB, if not already,
   2. Right-click and click on  'Copy ID'
   3. Include this dataset ID in an email with the credentials file

The credentials file should be securely shared with your school's technology administrator, preferably via encrypted email.

For Spreadsheet Services

If this service account will be used to populate a Google Spreadsheet, please follow these additional instructions.

Enable Google Sheets API

If the service account will be used to populate Google Spreadsheets, follow these steps.

Follow these steps to allow the service account to access Google Spreadsheet APIs:

1. With the project created in the previous step active, navigate to "APIs & Services"
2. Click on "Enabled APIs & Services"
3. Click "Enable APIs and Services"
4. Type "Sheets" in the search bar
5. Enable the "Google Sheets API"

Share spreadsheet with the service account

MBPY will populate a blank spreadsheet, which you can create yourself, and then share with the service account. These are the steps to activate the APIs for the service account:

1. Navigate to the "IAM" and "Service Accounts"
2. In the list of service accounts, there is an email address corresponding to the service account created that ends with `gserviceaccount.com`.
3. Share the spreadsheet with this email address (with edit rights), in exactly the same way you would share with an individual.

Now the service account can be used to keep the spreadsheet updated.

Configure MBPY to use credentials

If you are setting up MBPY yourself, follow these steps. If using a service provided by Schools Technology, simply send the credentials file to your Faria contact.

1. Place the downloaded files into a known location to you.
2. Inspect the help file for the gspread loader:`mbpy extract - gspread --help` which contains the names of the environment variables that need to be set, specifically `MBPY_GSPREAD_SERVICE_ACCOUNT_PATH`.
3. Set these variables in the configuration environment file.