Esta página foi traduzida pela API Cloud Translation.

Configurar a API Groups

Esta página explica como configurar a API Cloud Identity Groups.

Antes de começar

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

Instalar as bibliotecas de cliente

Para instalar as bibliotecas de cliente, execute o seguinte comando:

Python

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.

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

Autenticação com a API Groups

Pode autenticar-se com a API Groups como utilizador final, como administrador de um grupo de contas de serviço sem delegação ao nível do domínio ou como conta de serviço com delegação ao nível do domínio. As secções seguintes descrevem cada método.

Autenticação como utilizador final

Se não for administrador ou estiver a criar uma app que atue em nome de utilizadores que não são administradores, consulte o artigo Usar o OAuth 2.0 para aplicações de servidor Web e, de seguida, consulte a secção Instanciar um cliente abaixo.

Autenticação como conta de serviço sem delegação ao nível do domínio

Se estiver a usar uma conta de serviço e quiser usá-la para gerir grupos como administrador de grupos, conclua os passos abaixo. Este método de autenticação deve ser usado quando quiser que as ações da conta de serviço sejam registadas nos registos de auditoria como a conta de serviço.

Atribuir uma função de administrador à conta de serviço

Primeiro, deve atribuir a função de administrador do grupo do Google Workspace (Group Administrator) à conta de serviço à qual quer delegar, através da API Admin SDK Roles and Role Assignments. Este passo concede à conta de serviço acesso aos grupos do domínio, mas a nenhum outro recurso.

Consulte o guia de gestão de funções para obter informações gerais sobre a gestão de funções através da API Admin SDK. Siga os passos abaixo para atribuir a função de administrador do grupo à sua conta de serviço.

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

Aceda a Contas de serviço
Clique no nome da conta de serviço que quer usar com a API Groups.
Copie o ID exclusivo da conta de serviço.
Chame a API Roles do SDK de administrador para identificar o roleId para Group Administrator. Pode usar o API Explorer na documentação do SDK de administrador para o fazer.

Chame a API Role Assignments com o seguinte corpo do pedido:

{
  "assignedTo": "SERVICE_ACCOUNT_UNIQUE_ID"
  "roleId": "ROLE_ID"
  "scopeType": "CUSTOMER"
  "kind": "admin#directory#roleAssignment"
}

Autenticar e autorizar a conta de serviço

Agora, tem uma conta de serviço com a função de administrador do grupo. O segundo passo é concluir o processo de autenticação OAuth para a conta de serviço.

Se estiver a desenvolver uma app no Google Cloud e a conta de serviço for proprietária do projeto, pode usar as credenciais predefinidas da aplicação em alternativa, o que pode simplificar o processo. Consulte o artigo Autenticação como conta de serviço para mais informações.
Se a conta de serviço não for proprietária do projeto, siga as instruções abaixo.

Em qualquer dos casos, o âmbito aplicável para a API Cloud Identity Groups é https://www.googleapis.com/auth/cloud-identity.groups.

Usando a credencial que acabou de criar, gere um token de acesso.

Java

GoogleCredential credential = new GoogleCredential.Builder()
    .setTransport(httpTransport)
    .setJsonFactory(JSON_FACTORY)
    .setServiceAccountId(emailAddress)
    .setServiceAccountPrivateKeyFromP12File(new File("MyProject.p12"))
    .setServiceAccountScopes(ImmutableList.of("https://www.googleapis.com/auth/cloud-identity.groups"))
    .build();

Guarde o token de acesso gerado.

Código completo para gerar um token de acesso para uma conta de serviço

Java

GenerateServiceAccountOauth2Token.java

package com.google.tools;

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.common.collect.ImmutableList;
import java.io.FileInputStream;

/** Command line tool to generate Oauth2 token for a given service account
/** without domain wide delegation. */
public final class GenerateServiceAccountOauth2Token {

  private static final ImmutableList<String> API_SCOPES =
      ImmutableList.of(
          "https://www.googleapis.com/auth/cloud-identity.groups",
          "https://www.googleapis.com/auth/admin.directory.group",
          "https://www.googleapis.com/auth/admin.directory.group.member",
          "https://www.googleapis.com/auth/apps.groups.settings");

  public static void main(final String[] args) throws Exception {
    String accessToken = getTokenFromJsonKey();
    System.out.println("Token: " + accessToken);
  }

  private static String getTokenFromJsonKey() throws Exception {
    GoogleCredential credential =
        GoogleCredential.fromStream(
            new FileInputStream(
                "<path for json file>"),
            new NetHttpTransport(),
            GsonFactory.getDefaultInstance());
    System.out.println("ServiceAccountId=" + credential.getServiceAccountId());

    HttpTransport httpTransport = new NetHttpTransport();
    JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
    GoogleCredential.Builder builder =
        new GoogleCredential.Builder()
            .setServiceAccountPrivateKey(credential.getServiceAccountPrivateKey())
            .setServiceAccountPrivateKeyId(credential.getServiceAccountPrivateKeyId())
            .setServiceAccountId(credential.getServiceAccountId())
            .setTransport(httpTransport)
            .setJsonFactory(jsonFactory)
            .setServiceAccountScopes(API_SCOPES)
            .setClock(credential.getClock());
    credential = builder.build();
    if (!credential.refreshToken()) {
      throw new Exception("Failed to fetch access token.");
    }
    return credential.getAccessToken();
  }
}

Crie uma regra

java_binary(
  name = "generate_oauth2_token",
  srcs = ["GenerateServiceAccountOauth2Token.java"],
  main_class = "com.google.tools.GenerateServiceAccountOauth2Token",
  deps = [
      "//java/com/google/api/client/googleapis/auth/oauth2",
      "//java/com/google/api/client/googleapis/javanet",
      "//java/com/google/api/client/http",
      "//java/com/google/api/client/http/javanet",
      "//java/com/google/common/base",
      "//java/com/google/common/collect",
      "//third_party/java/google_http_java_client:gson",
      "//third_party/java/google_http_java_client:json",
  ],
)

Testar a conta de serviço

Experimente qualquer chamada da API Groups com as credenciais da conta de serviço: crie um grupo, adicione utilizadores, atualize as definições do grupo, etc.
Verifique os registos de auditoria na secção Relatórios da consola do administrador Google. Deve ver a conta de serviço como o ator das alterações relacionadas com o grupo. Consulte o artigo Registe eventos para mais informações.

Em alternativa, pode usar APIs para aceder aos registos de auditoria. Para verificar através do explorador da API Reports, certifique-se de que usa as credenciais do OAuth de administrador.

Autenticação como conta de serviço com delegação ao nível do domínio

Se for um administrador que gere grupos de identidades ou quiser fornecer a uma conta privilégios ao nível do domínio para que possa gerir o Google Groups em nome dos administradores, deve autenticar-se como uma conta de serviço.

Para ver detalhes sobre a configuração da delegação ao nível do domínio, consulte o artigo Controle o acesso à API com a delegação ao nível do domínio.

Para se autenticar como uma conta de serviço, consulte o artigo Usar o OAuth 2.0 para aplicações de servidor a servidor. Quando inicializar 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_FILE, scopes=SCOPES).with_subject(delegated_email)

Instanciar um cliente

O exemplo seguinte mostra como instanciar um cliente através de credenciais da conta de serviço. Em alternativa, para autenticar como utilizador final, substitua o objeto credential da conta de serviço pelo credential que obteve anteriormente em Usar o OAuth 2.0 para aplicações de servidor Web.

Python

from google.oauth2 import service_account
import googleapiclient.discovery

SCOPES = ['https://www.googleapis.com/auth/cloud-identity.groups']
SERVICE_ACCOUNT_FILE = '/path/to/service-account-file.json'

def create_service():
  credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)
  delegated_credentials = credentials.with_subject('user@example.org')

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

  return service

Agora, pode começar a fazer chamadas para a API Groups.