Authentication

This page explains how to configure authentication in the Cloud Healthcare API.

Note: Authentication and authorization are complex topics; the precise way you configure your application or service depends on a variety of factors, including who you want to authenticate, what tasks you allow the authenticated entity to perform (commonly referred to as "authorization"), and what, if any, container you use (such as Compute Engine or App Engine). See the Google Cloud Authentication Overview for more information.

Obtaining a service account key file

You can create service accounts with roles specific to Cloud Healthcare API such as a Healthcare Dataset Administrator or a Healthcare FHIR Store Administrator. To view all the available Cloud Healthcare API roles, see Roles.

You must grant the appropriate Identity and Access Management (IAM) roles to a service account to allow that service account to access relevant API methods.

The following steps show how to create a service account with the Healthcare FHIR Store Administrator role and to download a key file for this service account.

Console

Create a service account:

1. In the Google Cloud console, go to the Create service account page.

   Go to Create service account
2. Select your project.

3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

   In the Service account description field, enter a description. For example, Service account for quickstart.

4. Click Create and continue.

5. To provide access to your project, grant the roles/healthcare.fhirStoreAdmin role to your service account.

   To grant the role, find the Select a role list, then select roles/healthcare.fhirStoreAdmin.

   Note: The Role field affects which resources your service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
6. Click Continue.

7. Click Done to finish creating the service account.

   Do not close your browser window. You will use it in the next step.

Create a service account key:

1. In the Google Cloud console, click the email address for the service account that you created.
2. Click Keys.
3. Click Add key, and then click Create new key.
4. Click Create. A JSON key file is downloaded to your computer.
5. Click Close.

gcloud

Set up authentication:

1. Create the service account:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name for the service account.

2. Grant the roles/healthcare.fhirStoreAdmin IAM role to the service account:

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=roles/healthcare.fhirStoreAdmin

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   Note: The --role flag affects which resources your service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.

3. Generate the key file:

   gcloud iam service-accounts keys create FILE_NAME.json --iam-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

   Replace the following:

   • FILE_NAME: a name for the key file
   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account

Providing credentials to your application

The Cloud Healthcare API can use language-specific Google client libraries to authenticate applications and make calls to Google Cloud. For example, using the Google API Client Library for Python, you can build a service object using your credentials and then make calls to it.

You can provide credentials automatically or manually. Automatically providing credentials is useful when testing and experimenting, but can make it hard to tell which credentials your application is using. As an alternative, provide the credentials manually.

Setting the environment variables

You can provide authentication credentials to your application code or commands by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS to the file path of the JSON file that contains your service account key.

Note that, if you are running your application on Compute Engine, Google Kubernetes Engine (GKE), or App Engine, you only need to set the GOOGLE_APPLICATION_CREDENTIALS environment variable if you are using a service account other than the default service account that those services provide.

The following samples show how to set the GOOGLE_APPLICATION_CREDENTIALS environment variable:

curl

If you're using curl, run the following command. Replace PATH with the file path of the JSON file that contains your service account key, and FILE_NAME with the filename. This variable only applies to your current shell session, so if you open a new session, set the variable again.

export GOOGLE_APPLICATION_CREDENTIALS=PATH/FILE_NAME

For example:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account.json"

PowerShell

If you're using Windows PowerShell, run the following command. Replace PATH with the file path of the JSON file that contains your service account key, and FILE_NAME with the filename. This variable only applies to your current shell session, so if you open a new session, set the variable again.

$env:GOOGLE_APPLICATION_CREDENTIALS="PATH/FILE_NAME"

For example:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service_account.json"

After you've set the GOOGLE_APPLICATION_CREDENTIALS environment variable, Application Default Credentials (ADC) can implicitly determine your credentials.

Finding credentials automatically

Google API client libraries use Application Default Credentials (ADC) to automatically find your application's credentials.

When your code uses a client library, the client library checks for your credentials in the following order:

1. ADC checks if the environment variable GOOGLE_APPLICATION_CREDENTIALS is set. If the variable is set, ADC uses the service account file that the variable points to. Setting the environment variables describes how to set the environment variable.
2. If the environment variable isn't set, ADC uses the default service account that Compute Engine, Google Kubernetes Engine (GKE), or App Engine provide, if your application is running on any of those services.

If ADC can't use either of the above credentials, an error occurs.

The following code sample shows the use of ADC. The sample doesn't explicitly specify the application credentials. However, ADC can implicitly find the credentials and store them in the auth variable as long as the GOOGLE_APPLICATION_CREDENTIALS environment variable is set, or as long as the application is running on Compute Engine, GKE, or App Engine.

Node.js

Uses the Node.js client library.

View on GitHub Feedback

const google = require('@googleapis/healthcare');
const healthcare = google.healthcare({
  version: 'v1',
  auth: new google.auth.GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  }),
});

const createDataset = async () => {
  // TODO(developer): uncomment these lines before running the sample
  // const cloudRegion = 'us-central1';
  // const projectId = 'adjective-noun-123';
  // const datasetId = 'my-dataset';
  const parent = `projects/${projectId}/locations/${cloudRegion}`;
  const request = {parent, datasetId};

  await healthcare.projects.locations.datasets.create(request);
  console.log(`Created dataset: ${datasetId}`);
};

createDataset();

Obtaining and providing service account credentials manually

You can create and obtain service account credentials manually, and then pass the credentials to your application in its code. See Passing credentials manually for more information.

Service account authorization using JSON Web Tokens (JWTs)

You can make authorized calls to the Cloud Healthcare API using a signed JSON Web Token (JWT) directly as a bearer token, instead of an OAuth 2.0 access token. The Cloud Healthcare API doesn't require a specific token generation method. You can find a collection of helper client libraries for creating JWTs on JWT.io. When you use a signed JWT, you can avoid having to make a network request to Google's authorization server before making an API call.

When using a JWT, specify https://healthcare.googleapis.com/ in the aud field.

To authorize calls to the Cloud Healthcare API using a JWT instead of an OAuth 2.0 access token, complete the instructions in Addendum: Service account authorization without OAuth.

Note: The Cloud Healthcare API doesn't have a service definition published in https://github.com/googleapis/googleapis, so the required information is provided in the following sample.

The JWT you create should resemble the following sample:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "PRIVATE_KEY_ID"
}
.
{
  "iss": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
  "sub": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
  "aud": "https://healthcare.googleapis.com/",
  "iat": CURRENT_UNIX_TIME,
  "exp": EXPIRATION_TIME
}

Important: Make sure that there's a trailing "/" in the aud field.

What's next

Learn about best practices for managing credentials.