Google Cloud Storage Integration
Connect your Google Cloud Storage (GCS) account to Biodock to browse and import biological image files directly from your existing cloud storage.
Biodock uses a Google Cloud service account that you create and control. The service account receives read access to the buckets you choose, and you provide its JSON key to Biodock to establish the connection.
Once connected, Biodock can browse the authorized storage locations and import selected files into your Biodock workspace.
Before you start
You will need:
A Google Cloud project
A Google Cloud Storage bucket
Permission to create a service account and configure IAM permissions
At least one supported image file in your bucket
Supported files include:
Single-file formats
.tif.tiff.svs.jpg.png.ndpi
Multi-file formats
.mrxswith its associated data folder.vsiwith its associated data folder.zipcontaining a.vsifile and its data folder
Set up Google Cloud
The integration requires two levels of Google Cloud IAM access:
Project-level access — allows Biodock to display the buckets available in your Google Cloud project.
Bucket-level access — allows Biodock to browse and read files from the specific buckets you authorize.
The project-level permission exposes bucket names only. Access to the contents of a bucket is granted separately for each bucket.
1. Create a service account
Open the Google Cloud Console and navigate to:
IAM & Admin → Service Accounts
Make sure the correct Google Cloud project is selected.
Click:
Create Service Account
Enter a name such as:
biodock-import
Then click:
Create and Continue
You do not need to assign a project role during this step.
Skip Grant this service account access to project, then click:
Continue → Done
After creating the service account, copy its email address.
It will look similar to:
biodock-import@your-project-id.iam.gserviceaccount.com
You will use this email when configuring permissions in the next steps.
2. Allow Biodock to list your buckets
Navigate to:
IAM & Admin → IAM
Click:
Grant Access
Under New principals, paste the service account email you created.
Under Assign roles, select:
Storage Bucket Viewer
If available in your Google Cloud environment, Storage Legacy Bucket Reader can also be used.
Click:
Save
This permission allows the integration to retrieve the list of buckets in the Google Cloud project.
It does not by itself grant access to the files stored inside those buckets.
3. Grant access to the bucket you want to use
Now grant read access only to the specific bucket or buckets that you want to connect to Biodock.
Navigate to:
Cloud Storage → Buckets
Select your bucket.
Open:
Permissions
Click:
Grant Access
Under New principals, enter the same service account email.
Under Assign roles, select:
Storage Object Viewer
Click:
Save
Repeat this step for each bucket you want to make available in Biodock.
The Storage Object Viewer permission allows Biodock to browse the objects in the bucket and read the selected files for import.
4. Create a service account JSON key
Return to:
IAM & Admin → Service Accounts
Select the service account you created.
Open:
Keys
Then select:
Add Key → Create new key
Choose:
JSON
Click:
Create
Google Cloud will download a .json file to your computer.
Keep this file secure. The JSON key authenticates as the service account and inherits the permissions assigned to that service account.
Connect Google Cloud Storage to Biodock
Once your Google Cloud configuration is complete:
Log in to Biodock.
Open Files.
Select the Google Cloud Storage tab.
Open the JSON key file you downloaded from Google Cloud.
Copy the entire contents of the JSON file.
Paste the JSON into the Google Cloud Storage connection field in Biodock.
Click Connect.
After the credentials are validated, Biodock will display the Google Cloud Storage buckets available to the service account.
Important: Copy the complete JSON file, including the opening
{, closing}, and the completeprivate_keyfield.
Import files into Biodock
After connecting Google Cloud Storage:
Select a bucket.
Navigate through folders as needed.
Select the files or folders you want to import.
Click Import to Biodock.
Select the destination folder in your Biodock workspace.
Click Import here.
Import progress will appear in the upload tray.
Once processing is complete, the imported files will appear under My Files in Biodock.
Permissions used by the integration
Display your buckets
storage.buckets.list
Project
Browse files and folders
storage.objects.list
Authorized bucket
Import a file
storage.objects.get
Authorized bucket
If the project-level permission is missing, Biodock will not be able to display the project's bucket list.
If the bucket-level Storage Object Viewer permission is missing, Biodock may be unable to browse or import files from that bucket.
Connecting multiple buckets
You can give Biodock access to more than one Google Cloud Storage bucket.
For each additional bucket:
Open the bucket's Permissions settings.
Add the same service account.
Assign Storage Object Viewer.
This lets you control access on a bucket-by-bucket basis without granting the service account read access to every bucket in your project.
Disconnect Google Cloud Storage
To disconnect the integration, open the Google Cloud Storage browser in Biodock and click:
Disconnect
Biodock will clear the stored Google Cloud credentials, and you will be returned to the connection screen the next time you open the integration.
If you also want to revoke access at the Google Cloud level, you can remove the service account's IAM permissions or disable/delete its key from the Google Cloud Console.
Troubleshooting
No buckets appear
If Biodock reports that the service account does not have:
storage.buckets.list
the service account is missing the project-level bucket listing permission.
Return to:
IAM & Admin → IAM
and assign Storage Bucket Viewer to the service account.
Files cannot be imported
If you see:
Failed to import images from Google Cloud Storage. Please ensure your service account has read permissions on the selected objects.
the service account does not have sufficient access to the contents of the selected bucket.
Open the bucket's permissions and assign:
Storage Object Viewer
to the service account.
Missing private_key
If Biodock reports a missing private_key, the complete JSON key was not pasted into Biodock.
Open the downloaded .json file and copy everything from the opening:
{
through the closing:
}
The JSON must include the complete private_key value.
Google Cloud rejects the service account email
If Google Cloud displays:
Email addresses and domains must be associated with an active Google Account
verify that you copied the actual service account email from:
IAM & Admin → Service Accounts
Do not manually replace parts of the email with placeholders such as PROJECT-ID.
Storage Legacy Bucket Reader is unavailable
Some versions of the Google Cloud Console may not show legacy roles.
Use:
Storage Bucket Viewer
instead.
This provides the bucket-listing permission needed by the Biodock integration.
Security
The Google Cloud Storage integration is designed so that you control which storage resources Biodock can access.
The service account is created within your Google Cloud project, and access to file contents is granted separately for each bucket.
Biodock does not require permission to create, modify, or delete objects in your Google Cloud Storage buckets.
The service account JSON credentials entered into Biodock are encrypted at rest and decrypted when required to communicate with the Google Cloud Storage API.
When a file is imported, Biodock reads the selected object from Google Cloud Storage and transfers it into Biodock's storage, where it proceeds through the standard Biodock file processing pipeline.
Need help?
If you have trouble connecting Google Cloud Storage, contact the Biodock team and include:
The error message displayed in Biodock
The Google Cloud project ID
The affected bucket name
For security, do not send your service account JSON key, private key, or other credentials to support by email or chat.
Last updated