Configure a API Devices

Esta página explica como configurar a API Cloud Identity Devices. Pode usar a API Devices para aprovisionar recursos programaticamente, por exemplo, gerir grupos Google, em nome de um administrador.

Ative a API e configure as credenciais

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Identity API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Identity API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Configure o acesso à API através de uma conta de serviço com delegação ao nível do domínio

Esta secção descreve como criar e usar uma conta de serviço para aceder aos recursos do Google Workspace. A autenticação direta na API Devices através de uma conta de serviço não é suportada, pelo que tem de usar este método.

Crie uma conta de serviço e configure-a para a delegação ao nível do domínio

Para criar uma conta de serviço e transferir a chave da conta de serviço, faça o seguinte:

1. Para criar uma conta de serviço, faça o seguinte:

   1. Na Google Cloud consola, aceda à página Contas de serviço do IAM:

      Aceda às contas de serviço

   2. Clique em Criar conta de serviço.

   3. Em Detalhes da conta de serviço, escreva um nome, um ID e uma descrição para a conta de serviço e, de seguida, clique em Criar e continuar.

   4. Opcional: em Conceda a esta conta de serviço acesso ao projeto, selecione as funções do IAM a conceder à conta de serviço.

   5. Clique em Continuar.

   6. Opcional: em Conceder aos utilizadores acesso a esta conta de serviço, adicione os utilizadores ou os grupos que têm autorização para usar e gerir a conta de serviço.

   7. Clique em Concluído.

2. Para permitir que a conta de serviço aceda à API Devices através da delegação ao nível do domínio, siga as instruções em Configure a delegação ao nível do domínio para a conta de serviço.

3. Para criar e transferir uma chave de conta de serviço, faça o seguinte.

   Importante: as chaves de contas de serviço representam um risco de segurança se não forem geridas corretamente. Deve escolher uma alternativa mais segura às chaves de contas de serviço sempre que possível. Se tiver de fazer a autenticação com uma chave de conta de serviço, é responsável pela segurança da chave privada e por outras operações descritas nas Práticas recomendadas de gestão de chaves de contas de serviço. Se não conseguir criar uma chave de conta de serviço, a criação de chaves de contas de serviço pode estar desativada para a sua organização. Para mais informações, consulte o artigo Gerir recursos da organização seguros por predefinição.

   Se adquiriu a chave da conta de serviço a partir de uma fonte externa, tem de a validar antes de a usar. Para mais informações, consulte os Requisitos de segurança para credenciais de origem externa.

   1. Clique no endereço de email da conta de serviço que criou.
   2. Clique no separador Chaves.
   3. Na lista pendente Adicionar chave, selecione Criar nova chave.

   4. Clique em Criar.

      É gerado e transferido para o seu computador um ficheiro de credenciais formatado em JSON, que contém um novo par de chaves públicas e privadas. O ficheiro contém a única cópia das chaves. É responsável por armazená-lo em segurança. Se perder o par de chaves, tem de gerar um novo.

Reveja as entradas do registo

Quando rever as entradas do registo, tenha em atenção que os registos de auditoria mostram as ações de qualquer conta de serviço como tendo sido iniciadas pelo utilizador. Isto acontece porque a delegação ao nível do domínio funciona permitindo que a conta de serviço se faça passar por um utilizador administrador.

Inicialize as credenciais

Quando inicializa a credencial no seu código, especifique o endereço de email no qual a conta de serviço atua chamando with_subject() na credencial. Por exemplo:

Python

credentials = service_account.Credentials.from_service_account_file(
  'SERVICE_ACCOUNT_CREDENTIAL_FILE',
  scopes=SCOPES).with_subject(USER
)

Substitua o seguinte:

• SERVICE_ACCOUNT_CREDENTIAL_FILE: o ficheiro de chave da conta de serviço que criou anteriormente neste documento
• USER: o utilizador cuja identidade a conta de serviço simula

Instanciar um cliente

O exemplo seguinte mostra como instanciar um cliente através de credenciais da conta de serviço.

Python

from google.oauth2 import service_account
import googleapiclient.discovery

SCOPES = ['https://www.googleapis.com/auth/cloud-identity.devices']

def create_service():
  credentials = service_account.Credentials.from_service_account_file(
    'SERVICE_ACCOUNT_CREDENTIAL_FILE',
    scopes=SCOPES
  )

  delegated_credentials = credentials.with_subject('USER')

  service_name = 'cloudidentity'
  api_version = 'v1'
  service = googleapiclient.discovery.build(
    service_name,
    api_version,
    credentials=delegated_credentials)

  return service

Substitua o seguinte:

• SERVICE_ACCOUNT_CREDENTIAL_FILE: o ficheiro de chave da conta de serviço que criou anteriormente neste documento
• USER: o utilizador cuja identidade a conta de serviço simula

Já pode começar a fazer chamadas para a API Devices.

Em alternativa, para autenticar como um utilizador final, substitua o objeto credential da conta de serviço pelo credential que pode obter em Obter tokens OAuth 2.0.

Instalar a biblioteca cliente Python

Para instalar a biblioteca cliente Python, execute o seguinte comando:

  pip install --upgrade google-api-python-client google-auth \
    google-auth-oauthlib google-auth-httplib2

Para mais informações sobre como configurar o seu ambiente de programação Python, consulte o guia de configuração do ambiente de programação Python.