Codelab: automatizzazione della verifica del dominio per Google Workspace

Perché automatizzare la verifica del dominio?

Sebbene l'API Cloud Channel consenta di eseguire il provisioning del diritto Google Workspace su larga scala, il cliente deve comunque eseguire le seguenti azioni per abilitare i servizi.

1. Accetta i Termini di servizio
2. Verifica la proprietà del dominio
3. Configura i record MX

Un cliente appena creato seguirà una procedura guidata per i requisiti quando accederà per la prima volta alla Console di amministrazione (su admin.google.com).

Se hai accesso programmatico ai record DNS del dominio (ad esempio, se hai rivenduto il dominio al cliente), puoi automatizzare i passaggi 2 e 3 per aumentare i tassi di attivazione, poiché questi passaggi in genere richiedono conoscenze tecniche da parte del cliente del rivenditore.

Questo codelab spiega come utilizzare l'API Site Verification per implementare questa automazione.

Prima di iniziare

• Assicurati di completare il codelab di configurazione dell'API per configurare un progetto Google Cloud e creare un account di servizio per chiamare l'API Cloud Channel.

• Scopri di più sulle operazioni di Channel Services.

• Ti consigliamo di utilizzare la Test Partner Sales Console per questo codelab.

Punto chiave: questo codelab richiede l'accesso programmatico ai record DNS del dominio del cliente.

Questo codelab prevede anche che tu abbia completato il codelab sul provisioning end-to-end di Workspace.

Panoramica

La verifica del dominio per la presenza di diritti Google Workspace prevede diverse chiamate API.

L'API Site Verification non è specifica per i rivenditori. La verifica del dominio è un indicatore utilizzato in vari prodotti Google (Search Console, Google Ads e così via). Il processo descritto qui si basa sull'impostazione del super amministratore del dominio rivenditore come "proprietario" del dominio e sull'impostazione del primo amministratore del cliente come comproprietario. Puoi trovare ulteriori informazioni su questi concetti nella pagina Introduzione all'API Site Verification.

Passaggio 1: preparati per l'API Site Verification

• Vai alla sezione Libreria API nella console Google Cloud e abilita l'API Site Verification.
• Vai alla pagina della delega a livello di dominio utilizzando l'account super amministratore del tuo dominio rivenditore.
  • Nella riga corrispondente al tuo account di servizio, fai clic su Modifica.
  • Inserisci https://www.googleapis.com/auth/siteverification nel campo Ambiti OAuth.
  • Fai clic su Autorizza.
• Installa la libreria client dell'API Site Verification.

Passaggio 2: recupera il token di verifica

Questo codelab è incentrato sul modo più comune per verificare un dominio: l'utilizzo dei record DNS TXT. L'API Site Verification supporta altri metodi di verifica.

Per recuperare il token che inserirai come record TXT, devi ottenere i token per type=INET_DOMAIN e verificationMethod=DNS_TXT.

Nel codice seguente, compila queste variabili utilizzando le tue informazioni.

• jsonKeyFile: il percorso del file di chiavi JSON generato quando hai creato un account di servizio.
• resellerAdminUser: l'indirizzo email del super amministratore del dominio di un rivenditore.

• customerDomain: il dominio del cliente finale. Se esegui questo codelab sulla Test Partner Sales Console, assicurati che il dominio segua le convenzioni di denominazione dei domini.

C#

Utilizzando le seguenti importazioni:

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

Crea il client API e recupera il 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);

Go

Utilizzando le seguenti importazioni:

import (
  "context"
  "fmt"
  "os"

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

Crea il client API e recupera il 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

Utilizzando le seguenti importazioni:

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;

Crea il client API e recupera il 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

Utilizzando la seguente importazione:

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

Crea il client API e recupera il 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

Crea il client API e recupera il 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

Utilizzando le seguenti importazioni:

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

Crea il client API e recupera il 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: il token generato è legato al chiamante dell'API (il super amministratore del tuo account rivenditore). Il cliente non può verificare il dominio inserendo questo token nei propri record DNS.

Passaggio 3: inserisci il token di verifica

Scrivi il codice per aggiungere il token come record TXT nei record DNS del dominio del cliente.

Per i nuovi domini, questo è il momento ideale per configurare i record MX richiesti per Gmail.

Passaggio 4: attiva la verifica del dominio

Dopo aver inserito il token come record TXT, puoi chiamare l'API Site Verification per attivare la verifica. A tale scopo, chiama webResource.insert().

Se il token previsto non è stato trovato, la chiamata ha esito negativo con un errore 400. Puoi implementare una strategia di ripetizione di backoff esponenziale finché la chiamata non riesce a compensare i ritardi di propagazione del DNS.

Se la chiamata viene restituita senza errori, l'API Site Verification considera il dominio da verificare e tutte le email nel campo owners dell'webResource sono un proprietario verificato.

Potrebbero essere necessarie circa tre ore prima che lo stato della verifica venga applicato all'account Google Workspace del tuo cliente. Puoi forzare la propagazione immediata dello stato impostando l'amministratore del cliente (creato quando hai chiamato provisionCloudIdentity) come owner di 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");

Go

// 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")