Como configurar a API Groups

Nesta página, você aprende a configurar a API Cloud Identity Groups.

Observação: para usar a API Groups, o Grupos do Google para empresas precisa estar ativado no seu domínio e permitir que os usuários finais criem grupos. Veja mais informações em Ativar ou desativar grupos para empresas e Definir opções de compartilhamento do Grupos para empresas. Estas etapas exigem acesso de administrador do espaço de trabalho do Google ao seu domínio.

Antes de começar

Enable the Cloud Identity API.

Enable the API

Como instalar bibliotecas de cliente

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

Python

Para mais informações sobre a configuração do ambiente de desenvolvimento do Python, consulte o Guia de configuração do ambiente de desenvolvimento do Python.

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

Como autenticar com a API Groups

É possível se autenticar na API Groups como usuário final, como administrador de grupo de contas de serviço sem delegação em todo o domínio ou como conta de serviço com delegação em todo o domínio. As seções a seguir descrevem cada método.

Como autenticar como um usuário final

Se você não for um administrador ou estiver criando um app que atua em nome dos usuários que não são administradores, consulte Como usar o OAuth 2.0 para aplicativos de servidor da Web e consulte a seção Como instanciar um cliente abaixo.

Como autenticar como uma conta de serviço sem delegação em todo o domínio

Se você estiver usando uma conta de serviço e quiser usá-la para gerenciar grupos como um administrador de grupo, conclua as etapas abaixo. Use esse método de autenticação quando quiser que as ações da conta de serviço sejam registradas nos registros de auditoria como a conta de serviço.

Como atribuir um papel de administrador à conta de serviço

Dica :se a conta de serviço não precisar de acesso a todos os grupos, considere tornando-o um proprietário dos grupos de interesse. Você não precisa atribuir o de administrador de grupo nesse caso.

Primeiro, atribua o papel de administrador do grupo do espaço de trabalho do Google (administrador de grupo) à conta de serviço a que você quer delegar usando os papéis do SDK Admin e a Role Assignments API. Nesta etapa, a conta de serviço tem acesso aos grupos do domínio, mas não a outro recurso.

Observação: é necessário ter acesso de superadministrador do espaço de trabalho do Google para seu domínio para tornar a conta de serviço um administrador delegado.

Consulte o guia Como gerenciar papéis para informações gerais sobre como gerenciar papéis usando a API Admin SDK. Siga as etapas abaixo para atribuir o papel de Administrador de grupo à conta de serviço.

1. No console do Google Cloud, acesse a página Contas de serviço:

   Acessar a página "Contas de serviço"

2. Clique no nome da conta de serviço que você quer usar com o API Groups.

3. Copie o ID exclusivo da conta de serviço.

4. Chame a API Admin SDK Roles para identificar o roleId para o administrador do grupo. Para fazer isso, use o API Explorer na documentação do SDK Admin.

5. Chame a API Role Assignments com o corpo da solicitação a seguir:

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

Como autenticar e autorizar a conta de serviço

Agora você tem uma conta de serviço com o papel de administrador de grupo. A segunda etapa é concluir o processo de autenticação OAuth para a conta de serviço.

• Se você estiver desenvolvendo um aplicativo no Google Cloud e a conta de serviço for proprietária do projeto, use Application Default Credentials, o que pode simplificar o processo. Consulte Autenticação como uma conta de serviço para mais informações.

• Se a conta de serviço não for a proprietária do projeto, siga as instruções abaixo.

Em ambos os casos, o escopo aplicável para a API Cloud Identity Groups é https://www.googleapis.com/auth/cloud-identity.groups.

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

   Observação: não assuma a identidade de um usuário ao gerar credenciais. Pular campos como with_subject, createDelegated ou setServiceAccountUser.

   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();
   

   Mantenha 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();
  }
}

Regra da versão

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",
  ],
)

Como testar a conta de serviço

1. Tente qualquer chamada da API Groups com as credenciais da conta de serviço: criar um grupo, adicionar usuários, atualizar configurações do grupo etc.

2. Verifique os registros de auditoria na seção "Relatórios" do Google Admin Console. Você verá a conta de serviço como o ator das alterações relacionadas ao grupo. Consulte Registrar eventos para ver mais informações.

   Também é possível usar APIs para acessar registros de auditoria. Para verificar usando o Explorador da API Reports, use suas credenciais do OAuth de administrador.

Como autenticar como uma conta de serviço com delegação em todo o domínio

Se você for um administrador que gerencia grupos de identidade ou quiser fornecer uma conta com privilégios para todo o domínio para que ele possa gerenciar Grupos do Google em nome de administradores, faça a autenticação como conta de serviço.

Observação: como a delegação em todo o domínio funciona permitindo que a conta de serviço personifique um usuário administrador, os registros de auditoria mostrarão todas as ações da conta de serviço como o usuário. Se você quer que as ações apareçam como a conta de serviço, consulte Como autenticar como uma conta de serviço sem delegação em todo o domínio acima.

Para saber mais sobre como configurar a delegação em todo o domínio, consulte Controlar o acesso à API com a delegação em todo o domínio.

Para autenticar como conta de serviço. Consulte Como usar o OAuth 2.0 para aplicativos de servidor para servidor. Em seguida, ao inicializar a credencial no código, especifique o endereço de e-mail em que a conta de serviço atua chamando with_subject() na credencial. Exemplo:

Python

credentials = service_account.Credentials.from_service_account_file(
  SERVICE_ACCOUNT_FILE, scopes=SCOPES).with_subject(delegated_email)

Instanciação de um cliente

O exemplo a seguir mostra como instanciar um cliente usando as credenciais da conta de serviço. Para autenticar como um usuário final, substitua o objeto credential da conta de serviço com o credential que você recebeu antes em Como usar o OAuth 2.0 em aplicativos de servidor da 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('[e-mail]')

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

  return service

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