Autenticar com a API Cloud Healthcare

Neste documento, descrevemos como se autenticar programaticamente na API Cloud Healthcare. A forma como você se autentica na API Cloud Healthcare depende da interface usada para acessar a API e do ambiente onde seu código está sendo executado.

Para mais informações sobre a autenticação do Google Cloud, consulte a visão geral da autenticação.

Acesso à API

A API Cloud Healthcare oferece suporte ao acesso programático. Você pode acessar a API das seguintes maneiras:

Bibliotecas de cliente

As bibliotecas de cliente das APIs do Google oferecem suporte de linguagem de alto nível para autenticação programática na API Cloud Healthcare. Para autenticar as chamadas feitas às APIs do Google Cloud, as bibliotecas de cliente dão suporte ao Application Default Credentials (ADC). As bibliotecas procuram credenciais em um conjunto de locais definidos e as usam para autenticar as solicitações feitas à API. Com o ADC, é possível disponibilizar credenciais ao aplicativo em uma variedade de ambientes, como de desenvolvimento ou produção local, sem precisar modificar o código do aplicativo.

Google Cloud CLI

Ao usar a CLI gcloud para acessar a API Cloud Healthcare, é preciso fazer login na CLI gcloud com uma Conta do Google, que fornece as credenciais usadas pelos comandos da CLI da gcloud.

Se as políticas de segurança da sua organização impedirem que as contas de usuário tenham as permissões necessárias, use a identidade temporária de conta de serviço.

Para mais informações, consulte Autenticar-se para usar a gcloud CLI. Para mais informações sobre como usar a CLI gcloud com a API Cloud Healthcare, consulte as páginas de referência da CLI gcloud.

REST

É possível autenticar a API Cloud Healthcare usando suas credenciais da CLI gcloud ou o Application Default Credentials. Para mais informações sobre a autenticação para solicitações REST, consulte Autenticar-se usando REST. Para informações sobre os tipos de credenciais, consulte Credenciais da gcloud CLI e credenciais do ADC.

Configurar a autenticação da API Cloud Healthcare

A configuração da autenticação depende do ambiente em que o código está sendo executado.

As opções a seguir para configuração da autenticação são as mais usadas. Para mais opções e informações sobre autenticação, consulte Autenticação no Google.

Para um ambiente de desenvolvimento local

É possível configurar credenciais para um ambiente de desenvolvimento local das seguintes maneiras:

Bibliotecas de cliente ou ferramentas de terceiros

Configure o Application Default Credentials (ADC) no ambiente local:

  1. Instale a Google Cloud CLI e inicialize-a executando o seguinte comando:

    gcloud init
  2. Crie as credenciais de autenticação para sua Conta do Google:

    gcloud auth application-default login

    Uma tela de login será exibida. Após o login, suas credenciais são armazenadas no arquivo de credenciais local usado pelo ADC.

Para mais informações sobre como trabalhar com o ADC em um ambiente local, consulte Ambiente de desenvolvimento local.

Solicitações REST usando a linha de comando

Ao fazer uma solicitação REST usando a linha de comando, use as credenciais da CLI gcloud incluindo gcloud auth print-access-token como parte do comando que envia a solicitação.

No exemplo a seguir, listamos as contas de serviço do projeto especificado. É possível usar o mesmo padrão em qualquer solicitação REST.

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID pelo ID do projeto no Google Cloud.

Para enviar a solicitação, expanda uma destas opções:

 

Para mais informações sobre como autenticar usando REST e gRPC, consulte Autenticar para usar REST. Para mais informações sobre a diferença entre as credenciais locais da ADC e as credenciais da CLI da gcloud, consulte Credenciais da CLI da gcloud e credenciais do ADC.

No Google Cloud

Para autenticar uma carga de trabalho em execução no Google Cloud, use as credenciais da conta de serviço anexada ao recurso de computação em que seu código está sendo executado. Por exemplo, é possível anexar uma conta de serviço a uma instância de máquina virtual (VM) do Compute Engine, a um serviço do Cloud Run ou a um job do Dataflow. Essa abordagem é o método de autenticação preferencial para códigos em execução em um recurso de computação do Google Cloud.

Para a maioria dos serviços, você precisa anexar a conta de serviço ao criar o recurso que executará o código. Não será possível adicionar ou substituir a conta de serviço mais tarde. O Compute Engine é uma exceção. Ele permite anexar uma conta de serviço a uma instância de VM a qualquer momento.

Use a CLI gcloud para criar uma conta de serviço e anexá-la ao recurso:

  1. Instale a Google Cloud CLI e inicialize-a executando o seguinte comando:

    gcloud init
  2. Configure a autenticação:

    1. Crie a conta de serviço:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Substitua SERVICE_ACCOUNT_NAME por um nome para a conta de serviço.

    2. Para conceder acesso ao projeto e aos recursos, conceda um papel à conta de serviço:

      gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

      Substitua:

      • SERVICE_ACCOUNT_NAME: o nome da conta de serviço.
      • PROJECT_ID: o ID do projeto em que você criou a conta de serviço
      • ROLE: o papel a ser concedido
    3. Para conceder outro papel à conta de serviço, execute o comando que você fez na etapa anterior.
    4. Conceda à sua Conta do Google um papel que permita que você use os papéis da conta de serviço e anexe a conta de serviço a outros recursos:

      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

      Substitua:

      • SERVICE_ACCOUNT_NAME: o nome da conta de serviço.
      • PROJECT_ID: o ID do projeto em que você criou a conta de serviço
      • USER_EMAIL: o endereço de e-mail da sua Conta do Google
  3. Crie o recurso que executará o código e anexe a conta de serviço a ele. Por exemplo, se você usar o Compute Engine:

    Crie uma instância do Compute Engine. Configure a instância da seguinte maneira:
    • Substitua INSTANCE_NAME pelo nome de instância de sua preferência.
    • Defina a sinalização --zone com a zona onde será criada a instância.
    • Defina a sinalização --service-account como o endereço de e-mail da conta de serviço que você criou.
    gcloud compute instances create INSTANCE_NAME --zone=ZONE --service-account=SERVICE_ACCOUNT_EMAIL

Para mais informações sobre a autenticação nas APIs do Google, consulte Autenticação no Google.

No local ou em outro provedor de nuvem

O método preferencial para configurar a autenticação de fora do Google Cloud é usar a federação de identidade da carga de trabalho. Para mais informações, consulte No local ou em outro provedor de nuvem na documentação de autenticação.

Controle de acesso para a API Cloud Healthcare

Depois de autenticar na API Cloud Healthcare, você precisa ter autorização para acessar os recursos do Google Cloud. A API Cloud Healthcare usa o Identity and Access Management (IAM) para autorização.

Para mais informações sobre os papéis da API Cloud Healthcare, consulte Controle de acesso com o IAM. Para mais informações sobre o IAM e a autorização, consulte Visão geral do IAM.

Autorização de conta de serviço usando JSON Web Tokens (JWTs)

É possível fazer chamadas autorizadas para a API Cloud Healthcare usando um JSON Web Token (JWT) assinado diretamente como um token do portador, em vez de um token de acesso OAuth 2.0. A API Cloud Healthcare não requer um método específico de geração de token. Há uma coleção de bibliotecas de cliente auxiliares para criar JWTs em JWT.io. Ao usar um JWT assinado, você pode evitar ter que fazer uma solicitação de rede ao servidor de autorização do Google antes de fazer uma chamada de API.

Ao usar um JWT, especifique https://healthcare.googleapis.com/ no campo aud.

Para autorizar chamadas à API Cloud Healthcare usando um JWT em vez de um token de acesso do OAuth 2.0, conclua as instruções em Adendo: autorização de conta de serviço sem OAuth.

O JWT criado deve ser semelhante ao exemplo a seguir:

{
  "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
}

A seguir