This page explains how to integrate a third-party medical imaging viewer with the Cloud Healthcare API.
Authorizing and authenticating requests using OAuth 2.0
Google Cloud APIs support the OAuth 2.0 protocol for both authentication and authorization.
A medical viewer needs to handle authentication and authorization to access DICOM data stored in the Cloud Healthcare API. You can grant these permissions in two ways. Each method has its own costs and benefits:
- End users authenticate themselves through the medical viewer to the Cloud Healthcare API.
- The medical viewer accesses the Cloud Healthcare API on behalf of the end user.
- Permissions are managed at the level of the user and the user's actions are logged to Cloud Audit Logs with the user's unique identifier.
- Using the Google sign-in flow is more complex than using a service account. For example, your application needs to handle callbacks to store the authorization token, which can add unnecessary complexity to a simple application.
- You configure the medical viewer to use its own method of authorization and access control to determine whether an end user can view a given Cloud Healthcare API resource. Using a service account is helpful if you already have a viewer that performs its own user management and authentication checks.
- Actions performed in the viewer are logged to Cloud Audit Logs, but you cannot see logs at the level of individual end users.
- Authentication using a service account is simpler than using the Google sign-in flow. For example, there is no need to prompt a user to log in, and therefore there is no need to store an access token.
Authorizing using Google sign-in OAuth 2.0 flow
At a high level, the sign-in flow has the following steps:
- A user opens your medical viewer application. The viewer displays a consent window from Google that shows the name of your application and the Google API services that it is requesting permission to access with the user's authorization credentials. The user can then consent or refuse to grant access to your application.
- The user is sent to a Google sign-in page. If the user grants your application the requested access, then your application gains permission to access the user's data.
Do not store refresh tokens in the viewer. The access tokens granted to the viewer by the user should be short-lived and only exchanged when the tokens expire.
Refresh tokens are also unnecessary because:
- The user is always present when using the viewer
- Using refresh tokens requires extra work to store the token securely
Authorizing using a service account
You can manage authentication and authorization at the level of the medical viewer, rather than at the level of an end user, by using OAuth 2.0 with a service account.
For instructions on how to use a service account to authenticate a medical viewer to the Cloud Healthcare API, see Authenticating to the API.
For the viewer to function properly, a user must have the following roles:
roles/healthcare.dicomViewer(to view DICOM resources)
roles/healthcare.dicomEditor(to view, edit, and create DICOM resources)
In the sign-in flow, it is expected that the user has already configured these roles, and the
viewer does not need to do anything else. When using a service account,
the roles must be set in the service account. The viewer should return
PERMISSION_DENIED errors to users who do not have the
required permissions for accessing their DICOM stores.
Accessing DICOMweb endpoints
After the user authenticates to the viewer, the viewer can make requests to DICOMweb endpoints. Each DICOM store exposes a single DICOMweb endpoint.
When the user is in the viewer, they must specify which projects and DICOM stores they want to access. The simplest process is to ask the user to provide the IDs for the project, dataset, and DICOM store they want to access. However, providing each individual value might take the user a long time.
As an alternative, you can provide a combination of user input and auto-completion in the viewer. For example, you might have the user enter a project ID, and then the viewer would automatically populate a list of the datasets and DICOM stores within that project. Or, you could provide a single input field that automatically populates the projects, datasets, and DICOM stores that the user has access to. The following API methods might be helpful when setting up either of these alternatives:
projects.list: Lists projects that are visible to the user and that satisfy a specified filter.
projects.locations.list: Lists information about the supported locations for the Cloud Healthcare API.
projects.locations.datasets.list: Lists the Cloud Healthcare API datasets in a project.
projects.locations.datasets.dicomStores.list: Lists the DICOM stores in a dataset.
You might also consider pre-populating a list of a user's resources. However, if a user has hundreds or thousands of DICOM stores or datasets, pre-populating and displaying the list might be infeasible.
Accessing resources in the viewer using DICOMweb
The Cloud Healthcare API supports the DICOMweb standard. To allow users to access their data, the viewer must implement the DICOMweb RESTful HTTP methods instead of the legacy DIMSE protocols.
There are two main components to any viewer: the worklist provider and the image viewer. You can use the DICOMweb standard with both components.
Viewing the worklist provider
Typically, the first thing a user sees when they open a viewer is a list of all available studies in each DICOM store. The viewer can retrieve these studies using the Search Transaction.
See the Cloud Healthcare API DICOM Conformance Statement for specifics on how the Search Transaction is implemented in the Cloud Healthcare API.
After the user is in the worklist provider, they will typically select a study for viewing. To render the study, the viewer must access the study's raw pixel bytes and the DICOM metadata. The viewer can retrieve this information using the Search Transaction family of methods. The Search Transaction methods let you retrieve an entire raw DICOM file or the file's raw pixel data. The Search Transaction methods also support transcoding between different transfer syntaxes.
See the Cloud Healthcare API DICOM Conformance Statement for specifics on how this method is implemented in the Cloud Healthcare API.
Maximizing network throughput
Sometimes, such as when rendering a CT scan, a viewer might need to download many instances at once to render the image. For best results, fetch each instance in parallel using a high number of concurrent requests (such as 50 or more). The exact number depends on your application and network bandwidth.