Autorizzazione

Le app autorizzano le chiamate all'API del cliente della registrazione zero-touch utilizzando OAuth. Questo documento illustra l'autorizzazione dell'API per i fornitori di gestione della mobilità aziendale (EMM) e gli sviluppatori IT aziendali. Dopo aver letto questo documento, saprai come autorizzare le richieste API nella tua app e spiegare i requisiti dell'account agli utenti dell'app.

Guida rapida alle autorizzazioni

• Per configurare un progetto Google Cloud Platform con l'API di registrazione zero-touch e i client secret OAuth, esegui questa procedura guidata.
• Crea il codice campione della guida rapida per Java, .NET o Python. Utilizza le librerie client delle API di Google per supportare altri linguaggi.

Panoramica

1. Uno o più amministratori IT sono utenti di un account cliente con registrazione zero-touch.
2. Gli amministratori IT utilizzano un Account Google per autenticarsi.
3. Le richieste API trasmettono un token OAuth2 per autorizzare le richieste API per conto di un amministratore IT.

Account cliente

Le configurazioni, i dispositivi e gli utenti (amministratori IT) di un'organizzazione appartengono a un account del cliente. Un account cliente è simile a un gruppo e non è un singolo utente. Un rivenditore configura un cliente quando l'organizzazione acquista per la prima volta i dispositivi per la registrazione zero-touch. Gli amministratori IT gestiscono altri utenti nella propria organizzazione utilizzando il portale della registrazione zero-touch.

L'API utilizza ID cliente numerici per identificare gli account. Devi passare l'ID cliente come parte del percorso dell'URL quando chiami i metodi API. Prima di chiamare qualsiasi metodo API, la tua app deve ottenere l'ID cliente di un utente.

L'esempio seguente mostra come ottenere gli account cliente per l'utente che autorizza la chiamata API:

Java

AndroidProvisioningPartner.Customers.List accountRequest = service.customers().list();
accountRequest.setPageSize(100);
CustomerListCustomersResponse accountResponse = accountRequest.execute();

List<Company> customers = accountResponse.getCustomers();
if (customers == null || customers.isEmpty()) {
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    System.out.println("No zero-touch enrollment account found.");
} else {
    // Print the customers in this page.
    for (Company customer : customers) {
        System.out.format("%s\tcustomers/%d\n",
              customer.getCompanyName(), customer.getCompanyId());
    }
}

.NET

CustomersResource.ListRequest accountRequest = service.Customers.List();
accountRequest.PageSize = 100;
CustomerListCustomersResponse accountResponse = accountRequest.Execute();
IList<Company> customers = accountResponse.Customers ?? new List<Company>();
if (customers.Count == 0)
{
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    Console.WriteLine("No zero-touch enrollment account found.");
}
foreach (Company customer in customers)
{
    Console.WriteLine("{0}\tcustomers/{1}",
                      customer.CompanyName,
                      customer.CompanyId);
}

Python

response = service.customers().list(pageSize=100).execute()
if 'customers' not in response:
  # No accounts found for the user. Confirm the Google Account
  # that authorizes the request can access the zero-touch portal.
  print('No zero-touch enrollment account found.')
  response['customers'] = []

for customer in response['customers']:
  print('{0}\tcustomers/{1}'.format(
      customer['companyName'], customer['companyId']))

Poiché l'esempio precedente stampa solo i primi 100 account nell'app, devi navigare nelle pagine dei risultati dell'account. Per informazioni su come eseguire questa operazione, consulta Risultati impaginati.

Un'organizzazione di solito ha un account cliente, ma le organizzazioni più grandi possono utilizzare account cliente separati per ogni divisione. Poiché un amministratore IT può essere membro di diversi account cliente, la tua app dovrebbe aiutare gli utenti a trovare e utilizzare nuovi account cliente. Nell'app, etichetta ogni account cliente utilizzando il valore companyName.

Utenti

Gli amministratori IT autorizzano le richieste API inviate dalla tua app per loro conto. Per autorizzare le richieste API, l'utente dell'app deve:

1. Associare un Account Google al loro indirizzo email.
2. Entra a far parte dell'account di un cliente utilizzando lo stesso indirizzo email.
3. Accetta i Termini di servizio (TdS) per i clienti della registrazione zero-touch.

Per facilitare la configurazione degli utenti della tua app, riutilizza le indicazioni per gli amministratori IT disponibili in Inizia e Associare un Account Google nella tua documentazione.

Gestione utenti

Gli amministratori IT gestiscono gli utenti dei propri account cliente nel portale della registrazione zero-touch. Gli utenti di un account cliente hanno un ruolo Proprietario o Amministratore. Entrambi i ruoli hanno lo stesso accesso all'API del cliente, ma un proprietario può gestire altri utenti.

Accettazione dei TdS

Prima che gli utenti dell'app possano autorizzare le chiamate API, devono accettare i TdS più recenti. Questo accade quando gli amministratori IT utilizzano per la prima volta la registrazione zero-touch o quando aggiorniamo i TdS. Se un utente non ha accettato i TdS più recenti, l'API restituisce un codice di stato HTTP 403 Forbidden e il corpo della risposta contiene TosError.

Il portale richiede automaticamente agli utenti di accettare i TdS più recenti quando accedono. Per conoscere gli approcci suggeriti che la tua app potrebbe includere, leggi Gestire i Termini di servizio nella guida all'integrazione EMM.

Aggiungi l'autorizzazione all'app

Ogni richiesta che la tua app invia all'API del cliente deve includere un token di autorizzazione. Il token, inoltre, identifica l'applicazione per Google. Poiché l'API del cliente accede ai dati utente, l'autorizzazione deve provenire dal proprietario dei dati. L'app delega l'autorizzazione API agli amministratori IT utilizzando il protocollo OAuth 2.0.

Punto chiave: per semplificare la configurazione dell'autorizzazione e dell'autenticazione, Google fornisce librerie client in grado di ridurre la quantità di codice da scrivere e rendere il codice più solido. Consigliamo di utilizzare una libreria client per chiamare l'API del cliente: consulta le guide rapide per Java, .NET e Python.

Istruzioni

Forniamo guide rapide per le app Java, .NET e Python. Se utilizzi una lingua diversa, segui i due passaggi riportati di seguito per configurare l'autorizzazione per la tua app.

Passaggio 1: attiva l'API zero-touch registration

1. Utilizza questa procedura guidata per creare o selezionare un progetto in Google Developers Console e attivare automaticamente l'API. Fai clic su Continua, quindi su Vai alle credenziali .
2. Fai clic su Annulla nella sezione Crea credenziali.
3. Nella parte superiore della pagina, seleziona la scheda Schermata consenso OAuth. Seleziona un Indirizzo email, inserisci un Nome prodotto, se non è già impostato, e fai clic sul pulsante Salva.
4. Seleziona la scheda Credenziali, fai clic sul pulsante Crea credenziali e seleziona ID client OAuth.
5. Seleziona un Tipo di applicazione in base al tipo di applicazione che stai creando.
6. Imposta Nome sul nome dell'app.
7. Fai clic su Crea.
8. Fai clic su Scarica JSON.
9. Sposta il file nella directory di lavoro e rinominalo client_secret.json.

Passaggio 2: installa la libreria client

Per installare la libreria client per la tua lingua:

1. Vai alle librerie client delle API di Google e seleziona la tua lingua dall'elenco delle lingue supportate.
2. Segui le indicazioni per installare la libreria client.

Per ulteriori informazioni sull'autorizzazione, consulta Utilizzo di OAuth 2.0 per accedere alle API di Google.

Ambiti di autorizzazione

Utilizza l'ambito di autorizzazione API https://www.googleapis.com/auth/androidworkzerotouchemm nella tua app per richiedere un token di accesso per OAuth 2.0.

Un parametro di ambito controlla l'insieme di risorse e operazioni a cui un token di accesso consente le chiamate. I token di accesso sono validi solo per l'insieme di operazioni e risorse descritte nell'ambito della richiesta del token. L'API copre tutti i metodi e le risorse con l'ambito della registrazione zero-touch singolo mostrato sopra.

Per un esempio dell'ambito della registrazione zero-touch utilizzato con la libreria client dell'API di Google, consulta le guide rapide per Java, .NET e Python. Per ulteriori informazioni sull'utilizzo degli ambiti API di Google, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

Best practice per le chiavi API

Quando utilizzi le chiavi API nelle tue applicazioni, assicurati di proteggerle. L'esposizione pubblica delle tue credenziali può comportare la compromissione del tuo account, il che potrebbe comportare addebiti imprevisti. Per proteggere le chiavi API, segui queste best practice:

Non incorporare le chiavi API direttamente nel codice

Le chiavi API incorporate nel codice possono essere esposte per errore al pubblico, ad esempio se dimentichi di rimuovere le chiavi dal codice che condividi. Anziché incorporare le chiavi API nelle tue applicazioni, archiviale in variabili di ambiente o in file esterni alla struttura di origine dell'applicazione.

Non archiviare le chiavi API nei file all'interno della struttura di origine dell'applicazione

Se archivi le chiavi API nei file, mantienili al di fuori della struttura di origine dell'applicazione per assicurarti che le chiavi non finiscano nel tuo sistema di controllo del codice sorgente. Ciò è particolarmente importante se utilizzi un sistema di gestione del codice sorgente pubblico come GitHub.

Limita l'utilizzo delle chiavi API solo da parte di indirizzi IP, URL referrer e app per dispositivi mobili che ne hanno bisogno

Limitando gli indirizzi IP, gli URL referrer e le app mobile che possono utilizzare ciascuna chiave, puoi ridurre l'impatto di una chiave API compromessa. Puoi specificare gli host e le app che possono utilizzare ciascuna chiave dalla console API di Google aprendo la pagina Credenziali e quindi creando una nuova chiave API con le impostazioni che preferisci oppure modificando le impostazioni di una chiave API.

Elimina le chiavi API non necessarie

Per ridurre al minimo l'esposizione agli attacchi, elimina le chiavi API che non ti servono più.

Rigenera periodicamente le tue chiavi API

Puoi rigenerare le chiavi API dalla console API di Google aprendo la pagina Credenziali, selezionando una chiave API e facendo clic su Rigenera chiave per ogni chiave. Quindi aggiorna le applicazioni in modo da utilizzare le chiavi appena generate. Le chiavi precedenti continueranno a funzionare per 24 ore dopo la generazione di chiavi sostitutive.

Esamina il codice prima di rilasciarlo pubblicamente

Prima di rendere il codice disponibile pubblicamente, assicurati che il codice non contenga chiavi API o altre informazioni private.