Codelab: automazione della verifica del dominio per Google Workspace

Perché automatizzare la verifica del dominio?

Sebbene l'API Cloud Channel ti consenta di eseguire il provisioning dei diritti di Google Workspace su larga scala, il cliente deve comunque eseguire le seguenti azioni per attivare 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à alla Console di amministrazione (all'indirizzo admin.google.com) per la prima volta.

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é in genere richiedono conoscenze tecniche da parte di un cliente di rivendita.

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 Google Cloud progetto 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 Partner Sales Console di test per questo codelab.

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

Per questo codelab è inoltre necessario aver completato il codelab di provisioning end-to-end di Workspace.

Panoramica

La verifica del dominio per il diritto di 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, Ads e così via). La procedura descritta qui si basa sull'impostazione del super amministratore del dominio del rivenditore come "proprietario" del dominio e sull'impostazione del primo amministratore del cliente come comproprietario. Puoi scoprire di più su questi concetti nella pagina Iniziare a utilizzare l'API Site Verification.

Passaggio 1: preparati per l'API Site Verification

• Vai alla sezione Libreria API nella Google Cloud console e abilita l'API Site Verification.
• Vai alla pagina Delega a livello di dominio utilizzando l'account super amministratore del dominio del rivenditore.
  • Nella riga con il 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: ricevi il token di verifica

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

Per recuperare il token da inserire come record TXT, devi recuperare 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 della chiave JSON generato quando hai creato un account di servizio.
• resellerAdminUser: l'indirizzo email di un super amministratore del dominio di un rivenditore.

• customerDomain: il dominio del cliente finale. Se esegui questo codelab su Partner Sales Console di prova, 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);

Vai

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 è associato all'autore della chiamata dell'API (super amministratore dell'account del rivenditore). Il cliente non può verificare il proprio dominio inserendo questo token nei record DNS.

Passaggio 3: inserisci il token di verifica

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

Per i nuovi domini, è un'ottima occasione per configurare i record MX richiesti per Gmail.

Passaggio 4: attiva la verifica del dominio

Una volta inserito il token come record TXT, puoi chiamare l'API Site Verification per attivare la verifica. Questo viene ottenuto chiamando webResource.insert().

La chiamata non va a buon fine con un errore 400 se non viene trovato il token previsto. Puoi implementare una strategia di ripetizione con backoff esponenziale finché la chiamata non va a buon fine per compensare i ritardi di propagazione del DNS.

Se la chiamata non restituisce errori, l'API Site Verification considera il dominio verificato e le eventuali email nel campo owners di webResource sono un proprietario verificato.

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

Vai

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