Codelab: automatizar a validação de domínio para o Google Workspace

Por que motivo deve automatizar a validação de domínio?

Embora a Cloud Channel API lhe permita aprovisionar a autorização do Google Workspace em grande escala, o cliente tem de realizar as seguintes ações para ativar os serviços.

1. Aceite os Termos de Utilização
2. Valide a propriedade do domínio
3. Configurar registos MX

Um cliente recém-criado segue um processo de requisitos guiado quando acede à consola do administrador (em admin.google.com) pela primeira vez.

Se tiver acesso programático aos registos DNS do domínio (por exemplo, se revendeu o domínio ao cliente), pode automatizar os passos 2 e 3 para aumentar as taxas de ativação, uma vez que esses passos exigem normalmente conhecimentos técnicos de um cliente de revenda.

Este codelab explica como usar a API Site Verification para implementar esta automatização.

Antes de começar

• Certifique-se de que conclui o codelab de configuração da API para configurar um Google Cloud projeto e criar uma conta de serviço para chamar a API Cloud Channel.

• Leia acerca das operações dos serviços de canais.

• Recomendamos que use a Partner Sales Console de teste para este codelab.

Ponto-chave: este codelab requer que tenha acesso programático aos registos DNS do domínio do cliente.

Este codelab também pressupõe que concluiu o codelab de aprovisionamento ponto a ponto do Workspace.

Vista geral

A validação do domínio para a autorização do Google Workspace envolve várias chamadas de API.

A API Site Verification não é específica para revendedores. A validação de domínio é um sinal usado em vários produtos Google (Search Console, Google Ads, etc.). O processo aqui descrito baseia-se na definição do superadministrador do domínio do revendedor como "proprietário" do domínio e na definição do primeiro administrador do cliente como coproprietário. Pode saber mais acerca destes conceitos na página Introdução à API Site Verification.

Passo 1: prepare-se para a API Site Verification

• Aceda à secção Biblioteca de APIs na Google Cloud consola e ative a API Site Verification.
• Aceda à página Delegação ao nível do domínio com a conta de superadministrador do domínio do revendedor.
  • Na linha com a sua conta de serviço, clique em Editar.
  • Introduza https://www.googleapis.com/auth/siteverification no campo Âmbitos de OAuth.
  • Clique em Autorizar.
• Instale a biblioteca cliente da API Site Verification.

Passo 2: obtenha o token de validação

Este codelab vai focar-se na forma mais comum de validar um domínio: usar TXT registos de DNS. A API Site Verification suporta outros métodos de validação.

Para obter o token que vai colocar como um registo TXT, tem de obter tokens para type=INET_DOMAIN e verificationMethod=DNS_TXT.

No código seguinte, preencha estas variáveis com as suas informações.

• jsonKeyFile: O caminho para o ficheiro de chave JSON gerado quando criou uma conta de serviço.
• resellerAdminUser: O endereço de email de um superadministrador do domínio de revendedor.

• customerDomain: o domínio do cliente final. Se executar este codelab na sua Consola de vendas de parceiros de teste, certifique-se de que o domínio segue as convenções de nomenclatura de domínios.

C#

Usando as seguintes importações:

using Google.Apis.Auth.OAuth2;
using Google.Apis.Services;
using Google.Apis.SiteVerification.v1;
using Google.Apis.SiteVerification.v1.Data;

Crie o cliente da API e obtenha o token:

// Set up credentials with user impersonation
ICredential credential = GoogleCredential.FromFile(jsonKeyFile)
                             .CreateScoped("https://www.googleapis.com/auth/siteverification")
                             .CreateWithUser(resellerAdminUser);

// Create the API service
var verificationService = new SiteVerificationService(new BaseClientService.Initializer{
    HttpClientInitializer = credential,
});

// Fetch the token
var request = new SiteVerificationWebResourceGettokenRequest {
  VerificationMethod = "DNS_TXT",
  Site = new SiteVerificationWebResourceGettokenRequest.SiteData {
    Type = "INET_DOMAIN",
    Identifier = customerDomain
  }
};
var response = verificationService.WebResource.GetToken(request).Execute();
string token = response.Token;
Console.WriteLine("Site Verification token: " + token);

Ir

Usando as seguintes importações:

import (
  "context"
  "fmt"
  "os"

  "golang.org/x/oauth2/google"
  "google.golang.org/api/option"
  "google.golang.org/api/siteverification/v1"
)

Crie o cliente da API e obtenha o token:

ctx := context.Background()

// Set up credentials with user impersonation
jsonKey, _ := os.ReadFile(jsonKeyFile)
jwt, _ := google.JWTConfigFromJSON(jsonKey, "https://www.googleapis.com/auth/siteverification")
jwt.Subject = resellerAdminUser
tokenSource := jwt.TokenSource(ctx)

// Create the API Service
verificationService, _ := siteverification.NewService(ctx, option.WithTokenSource(tokenSource))

// Fetch the token
req := &siteverification.SiteVerificationWebResourceGettokenRequest{
  Site: &siteverification.SiteVerificationWebResourceGettokenRequestSite{
    Type:       "INET_DOMAIN",
    Identifier: customerDomain,
  },
  VerificationMethod: "DNS_TXT",
}
res, _ := verificationService.WebResource.GetToken(req).Do()
token := res.Token
fmt.Println("Site verification token: " + token)

Java

Usando as seguintes importações:

import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.auth.oauth2.ServiceAccountCredentials;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.siteVerification.SiteVerification;
import com.google.api.services.siteVerification.SiteVerificationScopes;
import com.google.api.services.siteVerification.model.SiteVerificationWebResourceGettokenRequest;
import com.google.api.services.siteVerification.model.SiteVerificationWebResourceGettokenResponse;
import com.google.api.services.siteVerification.model.SiteVerificationWebResourceResource;
import java.io.FileInputStream;
import java.util.Arrays;

Crie o cliente da API e obtenha o token:

// Set up credentials with user impersonation
FileInputStream jsonKeyFileSteam = new FileInputStream(JSON_KEY_FILE);
GoogleCredentials credentials = ServiceAccountCredentials.fromStream(jsonKeyFileSteam)
                                    .createScoped("https://www.googleapis.com/auth/siteverification")
                                    .createDelegated(RESELLER_ADMIN_USER);

// Create the API service
SiteVerification verificationService = new SiteVerification.Builder(
    GoogleNetHttpTransport.newTrustedTransport(),
    JacksonFactory.getDefaultInstance(),
    new HttpCredentialsAdapter(credentials)).build();

// Fetch the token
SiteVerificationWebResourceGettokenRequest request =
    new SiteVerificationWebResourceGettokenRequest()
        .setVerificationMethod("DNS_TXT")
        .setSite(new SiteVerificationWebResourceGettokenRequest.Site()
            .setType("INET_DOMAIN")
            .setIdentifier(CUSTOMER_DOMAIN));
SiteVerificationWebResourceGettokenResponse response =
    verificationService.webResource().getToken(request).execute();
String token = response.getToken();
System.out.println("Site Verification token: " + token);

Node.js

Usando a seguinte importação:

const {google} = require('googleapis');

Crie o cliente da API e obtenha o token:

// Set up credentials with user impersonation
const authJWT = new JWT({
  keyFile: jsonKeyFile,
  scopes: ['https://www.googleapis.com/auth/siteverification'],
  subject: resellerAdminUser,
});

// Create the API service
const verificationService = google.siteVerification({version: 'v1', auth: authJWT});

// Fetch the token
const { data } = await verificationService.webResource.getToken({
  requestBody: {
    site: {
      type: 'INET_DOMAIN',
      identifier: customerDomain,
    },
    verificationMethod: 'DNS_TXT',
  }
});
const token = data.token;
console.log(`Site Verification token: ${token}`);

PHP

Crie o cliente da API e obtenha o token:

// Set up credentials with user impersonation
$client = new Google_Client();
$client->setAuthConfig($JSON_KEY_FILE);
$client->setSubject($RESELLER_ADMIN_USER);
$client->setScopes('https://www.googleapis.com/auth/siteverification');

// Create the API service
$verificationService = new Google_Service_SiteVerification($client);

// Fetch the token
$request = new Google_Service_SiteVerification_SiteVerificationWebResourceGettokenRequest([
  'verificationMethod' => 'DNS_TXT',
  'site' => [
    'type' => 'INET_DOMAIN',
    'identifier' => $CUSTOMER_DOMAIN
  ]
]);
$response = $verificationService->webResource->getToken($request);
$token = $response->token;
print 'Site Verification token: ' . $token . PHP_EOL;

Python

Usando as seguintes importações:

from google.oauth2 import service_account
from apiclient.discovery import build

Crie o cliente da API e obtenha o token:

# Set up credentials with user impersonation
credentials = service_account.Credentials.from_service_account_file(
    JSON_KEY_FILE, scopes=["https://www.googleapis.com/auth/siteverification"])
credentials_delegated = credentials.with_subject(RESELLER_ADMIN_USER)

# Create the API service
verification_service = build(serviceName="siteVerification", version="v1",
    credentials=credentials_delegated)

# Fetch the token
response = verification_service.webResource().getToken(
  body={
    "site": {
      "type": "INET_DOMAIN",
      "identifier": CUSTOMER_DOMAIN
    },
    "verificationMethod": "DNS_TXT"
  }).execute()
token = response["token"]
print("Site Verification token: " + token)

Nota: o token gerado está associado ao autor da chamada da API (o superadministrador da conta do revendedor). O seu cliente não pode validar o respetivo domínio ao colocar este token nos respetivos registos de DNS.

Passo 3: coloque o token de validação

Escreva o código para adicionar o token como um registo TXT nos registos de DNS do domínio do cliente.

Para novos domínios, esta é uma excelente altura para configurar os registos MX necessários para o Gmail.

Passo 4: acione a validação do domínio

Assim que o token for colocado como um registo TXT, pode chamar a API Site Verification para acionar a validação. Isto é conseguido através da chamada webResource.insert().

A chamada falha com um erro 400 se o token esperado não for encontrado. Pode implementar uma estratégia de repetição de recuo exponencial até a chamada ser bem-sucedida para compensar os atrasos na propagação de DNS.

Se a chamada for devolvida sem erros, a API Site Verification considera que o domínio foi validado e que todos os emails no campo owners do webResource são proprietários validados.

O estado de validação pode demorar cerca de 3 horas a propagar-se à conta do Google Workspace do seu cliente. Pode forçar a propagação instantânea do estado definindo o administrador do cliente (criado quando chamou provisionCloudIdentity) como um owner do webResource.

C#

// Set the customer's admin user as an owner to make sure the domain
// verification status is instantly propagated to the Workspace account
string[] owners = { "admin@" + customerDomain };

var resource = new SiteVerificationWebResourceResource {
  Site = new SiteVerificationWebResourceResource.SiteData {
    Type = "INET_DOMAIN",
    Identifier = customerDomain
  },
  Owners = owners
};

resource = verificationService.WebResource.Insert(resource, "DNS_TXT").Execute();
Console.WriteLine("=== Domain has been verified");

Ir

// Set the customer's admin user as an owner to make sure the domain
// verification status is instantly propagated to the Workspace account
resource := &siteverification.SiteVerificationWebResourceResource{
  Site: &siteverification.SiteVerificationWebResourceResourceSite{
    Type:       "INET_DOMAIN",
    Identifier: customerDomain,
  },
  Owners: []string{"admin@" + customerDomain},
}
resource, err := verificationService.WebResource.Insert("DNS_TXT", resource).Do()
if err != nil {
  fmt.Println(err)
} else {
  fmt.Println("=== Domain has been verified")
}

Java

// Set the customer's admin user as an owner to make sure the domain
// verification status is instantly propagated to the Workspace account
SiteVerificationWebResourceResource resource =
    new SiteVerificationWebResourceResource()
        .setSite(new SiteVerificationWebResourceResource.Site()
            .setIdentifier(CUSTOMER_DOMAIN)
            .setType("INET_DOMAIN"))
        .setOwners(Arrays.asList("admin@" + CUSTOMER_DOMAIN));

resource = verificationService.webResource().insert("DNS_TXT", resource).execute();
System.out.println("=== Domain has been verified");

Node.js

// Set the customer's admin user as an owner to make sure the domain
// verification status is instantly propagated to the Workspace account
await verificationService.webResource.insert({
  verificationMethod: 'DNS_TXT',
  requestBody: {
    site: {
      type: 'INET_DOMAIN',
      identifier: customerDomain,
    },
    owners: [`admin@${customerDomain}`],
  }
});
console.log('=== Domain has been verified');

PHP

// Set the customer's admin user as an owner to make sure the domain
// verification status is instantly propagated to the Workspace account
$resource = new Google_Service_SiteVerification_SiteVerificationWebResourceResource([
  'site' => [
    'type' => 'INET_DOMAIN',
    'identifier' => $CUSTOMER_DOMAIN,
  ],
  'owners' => ['admin@' . $CUSTOMER_DOMAIN]
]);

$resource = $verificationService->webResource->insert('DNS_TXT', $resource);
print '=== Domain has been verified' . PHP_EOL;

Python

# Set the customer's admin user as an owner to make sure the domain
# verification status is instantly propagated to the Workspace account
resource = verification_service.webResource().insert(
  verificationMethod="DNS_TXT",
  body={
    "site": {
      "type": "INET_DOMAIN",
      "identifier": CUSTOMER_DOMAIN
    },
    "owners": ["admin@" + CUSTOMER_DOMAIN]
  }).execute()
print("=== Domain has been verified")