Crea un'associazione aziendale

Per registrare una nuova organizzazione tramite la console EMM, devi creare un'associazione aziendale. Una risorsa Enterprises rappresenta l'associazione tra un EMM e un'organizzazione. Puoi utilizzarne un'istanza per richiamare le operazioni per conto dell'organizzazione.

L'API Play EMM offre tre modi per creare un'istanza di associazione aziendale:

  • Registrazione dei domini Google gestiti: questo metodo può essere utilizzato al posto di entrambi gli altri metodi. Le organizzazioni con un dominio e un'organizzazione Google gestiti esistenti e che non hanno mai utilizzato Google utilizzeranno la stessa UI di registrazione. Il percorso che gli utenti compiono nell'interfaccia utente varia a seconda della situazione e delle esigenze. L'organizzazione non ha bisogno di ottenere un token EMM in anticipo.

  • Creazione di account della versione gestita di Google Play: un'organizzazione vuole utilizzare gli account della versione gestita di Google Play. Puoi integrare l'interfaccia utente di registrazione di Android di Google con la tua console EMM e fornire alle organizzazioni un modo rapido per creare un'istanza di associazione aziendale che le leghi al tuo provider EMM. Questa operazione abilita gli account della versione gestita di Google Play per utenti e dispositivi. Questo approccio è talvolta indicato come avviato da EMM nella documentazione dell'API. Questo metodo è deprecato a favore del metodo di registrazione del dominio Google gestito precedente.

  • Registrazione dei domini Google gestiti: un'organizzazione ha già un dominio Google gestito. Gli amministratori IT completano diverse attività manuali, come la verifica della proprietà del dominio con Google, l'ottenimento di un token EMM e la creazione di un account di servizio aziendale. Questo approccio è a volte indicato come avviato da Google nella documentazione dell'API.

Puoi supportare entrambi gli approcci nella console EMM utilizzando la risorsa Enterprises. La tabella 1 mostra i campi e le operazioni pertinenti di questa risorsa per associare le organizzazioni ai provider EMM.

Tabella 1: API Enterprise e processi di associazione alternativi

 Account Google Play gestiti per l'aziendaDominio Google gestito Descrizione
Campo
id Identificatore univoco per l'organizzazione, restituito dalle chiamate enroll e completeSignup.
kind Identifica il tipo di risorsa utilizzando un valore stringa fisso, androidenterprise#enterprise"/>.
nome Organizzazione associata all'oggetto enterprise.
primaryDomainNon impostato Poiché le aziende con account Google Play gestiti non sono legate al modello di dominio Google, questo campo è pertinente solo per i domini Google gestiti.
amministratore[]Non impostatoL'amministratore IT che si registra ad Android utilizzando la procedura di registrazione avviata tramite EMM diventa l'amministratore (proprietario) dell'associazione aziendale. Utilizzando la versione gestita di Google Play Console, l'amministratore IT può invitare altri utenti dell'organizzazione a partecipare alle attività di amministrazione. Consulta il Centro assistenza della versione gestita di Google Play.
amministratore[].email Non impostato
Metodi
completeSignup Dati completionToken e enterpriseToken, restituisce una risorsa Enterprise nel corpo della risposta.
generateSignupUrl Specificato un valore callbackUrl, restituisce un URL e un completionToken.
Registra Registra il chiamante con l'EMM il cui token viene inviato con la richiesta.
getServiceAccount Restituisce un account di servizio e le credenziali.
setAccount Imposta l'account che verrà utilizzato per l'autenticazione nell'API come azienda.
annullare registrazione I provider EMM possono scollegare l'associazione a entrambi i tipi di azienda utilizzando l'annullamento della registrazione. Deve essere richiamato utilizzando le credenziali dell'EMM per l'MSA, non le credenziali dell'ESA.

Registrazione agli account della versione gestita di Google Play

Questo metodo di registrazione è obsoleto. Utilizza il metodo di registrazione del dominio Google gestito.

Registrazione ai domini Google gestiti

Puoi integrare la procedura di registrazione nella tua console EMM:

Registrazione come amministratore degli account della versione gestita di Google Play
Figura 1. Flusso di lavoro di registrazione dei domini Google gestiti

Un amministratore IT avvia il processo di creazione di un'azienda. Per farlo, l'amministratore IT:

  1. Accede alla console EMM.
  2. Fa clic o seleziona Configura Android (ad esempio) e viene reindirizzato a un'interfaccia utente di registrazione ospitata da Google.
  3. Fornisce i dettagli sull'azienda nell'interfaccia utente di registrazione.
  4. Viene reindirizzato alla console EMM.

L'indirizzo email dell'amministratore IT è ora collegato a un Account Google, che è un account amministratore di un dominio Google gestito.

Best practice: segui le linee guida per la sicurezza di Google per contribuire alla sicurezza dell'account amministratore.

Prerequisiti

Per gli amministratori IT

  • Accesso alla console EMM e autorizzazioni necessarie per effettuare la selezione appropriata nella console (ad esempio Gestisci Android come opzione di menu).

  • Un indirizzo email di lavoro. Deve far parte di un dominio di proprietà dell'organizzazione, non di un dominio condiviso come Gmail.com

Per la console EMM

Per implementare il flusso di registrazione gestito di Google Documenti, la tua console EMM deve essere in grado di:

  • Utilizza le tue credenziali MSA quando richiami le chiamate sulle API EMM di Google Play. L'MSA viene utilizzato per richiamare molte delle operazioni per conto di un amministratore IT finché non viene impostato l'account di servizio aziendale (ESA) dell'organizzazione.

  • Gestisci il reindirizzamento tramite un URL sicuro a un sito esterno fornito da Google per avviare la procedura di registrazione e completare la procedura di registrazione.

  • Essere configurabile con credenziali ESA dopo la registrazione. Poiché la console EMM può essere utilizzata per creare molte aziende all'interno del sito di una determinata organizzazione, avrai bisogno di un modo per associare ogni enterpriseId al proprio account di servizio e alle relative credenziali. Valuta la possibilità di creare account di servizio per l'organizzazione chiamando Enterprises.getServiceAccount e gestendo la gestione delle chiavi con le API Serviceaccountkeys. Per ulteriori dettagli, consulta Creare account di servizio aziendali in modo programmatico.

Il processo di registrazione di Android richiede che tu fornisca un servizio sicuro (https) per l'utilizzo da parte della console in fase di runtime. L'URL che rimanda a questo servizio sicuro può essere un URL locale e può includere una sessione o altre informazioni di identificazione univoche, purché sia nel formato corretto in modo che il sistema possa analizzarlo. Ad esempio:

https://localhost:8080/enrollmentcomplete?session=12345

Procedura di registrazione

La procedura di registrazione richiede meno di cinque minuti. I passaggi riportati di seguito presuppongono che il server che ospita callbackUrl sia attivo e in esecuzione. Questi passaggi presuppongono inoltre che la console includa un componente dell'interfaccia utente, ad esempio una selezione di menu con l'opzione Gestisci Android, che avvia il processo di registrazione quando un amministratore IT autenticato seleziona l'opzione.

Procedura in 12 passaggi per la registrazione di un account Google Play gestito per l'azienda
Figura 2. Procedura in 12 passaggi per creare un'associazione a un dominio Google gestito

  1. Un amministratore IT avvia una richiesta di registrazione nella console EMM.

  2. Chiama Enterprises.generateSignupUrl con callbackURL come unico parametro. Esempio: 

    https://localhost:8080/enrollcomplete?session=12345

  3. La risposta conterrà un URL di registrazione (valido per 30 minuti) e un token di completamento. Estrai e salva il token di completamento.

    Best practice: associa il token di completamento all'amministratore IT che ha avviato la registrazione.

  4. Estrai url dalla risposta generateSignupURL.

  5. Reindirizza all'URL estratto nel passaggio 4.

  6. L'amministratore IT segue il flusso di configurazione nell'interfaccia utente di registrazione per creare un'associazione aziendale:

    1. L'amministratore IT inserisce i propri dati personali e quelli della propria organizzazione e imposta una password, se non ha già un Account Google.

    2. All'amministratore IT viene mostrato il nome EMM e conferma che l'organizzazione sarà vincolata a questo EMM.

    3. L'amministratore IT accetta i Termini di servizio di Google.

  7. L'interfaccia utente di registrazione genera un URL di callback in base all'URL specificato nel passaggio 2.

  8. L'interfaccia utente di registrazione reindirizza l'amministratore IT all'URL di callback. Estrai e salva il token Enterprise nell'URL. Esempio: 

    https://localhost:8080/enrollcomplete?session=12345&enterpriseToken=5h3jCC903lop1

  9. Chiama Enterprises.completeSignup, superando completionToken (passaggio 3) e enterpriseToken (passaggio 8).

  10. La chiamata restituisce un'istanza Enterprises nel corpo della risposta. Archivia id, name e l'indirizzo email dell'amministratore (se presente) per un uso futuro.

  11. Crea un account di servizio aziendale (ESA). Le credenziali ESA assumono la forma di indirizzo email e chiave privata. Esistono due modi per creare un'ESA:

    • Best practice: crea l'ESA in modo programmatico utilizzando l'API EMM di Play.
    • Visualizza una pagina che indica all'amministratore IT di creare un'ESA nella console API di Google. Per informazioni più dettagliate, consulta Creazione di un account di servizio (chiedi all'amministratore di selezionare progetto > Editor come ruolo e seleziona la casella di download della chiave privata). Dopo che l'amministratore IT ha creato un'ESA, configura la console con le credenziali della chiave privata dell'ESA

  12. Utilizzando le tue credenziali MSA, chiama setAccount per impostare l'ESA per questa organizzazione.

La procedura di registrazione è stata completata

  • Il nuovo dominio Google gestito è associato al tuo provider EMM.
  • L'Account Google dell'amministratore IT è configurato come amministratore del dominio e può accedere al sito https://play.google.com/work per gestire le app dell'organizzazione.
  • La console EMM può utilizzare l'ESA per gestire i dati dell'organizzazione tramite l'API EMM di Google Play.

Crea ESA in modo programmatico

Per semplificare la gestione delle chiavi per le ESA, utilizza l'API EMM di Google Play per generare account di servizio per le organizzazioni anziché la console Google Cloud. Account di servizio generati tramite l'API Play EMM:

  • Non sono visibili in nessun progetto della console Cloud che appartiene a te o all'organizzazione; devono essere gestiti in modo programmatico.
  • Vengono eliminati quando annulli la registrazione per l'organizzazione.

Per generare un account di servizio in modo programmatico:

  1. Chiama Enterprises.getServiceAccount con enterpriseId (vedi il passaggio 10 della procedura di registrazione) e specifica il tipo di chiave (keyType) che preferisci (googleCredentials, pkcs12). Il sistema restituisce il nome di un account di servizio e una chiave privata per l'account di servizio (negli stessi formati restituiti dalla console API di Google).

  2. Chiama il numero Enterprises.setAccount e imposta l'account di servizio per l'organizzazione.

Best practice:supporta la modifica delle credenziali dell'ESA all'amministratore IT. Per eseguire questa operazione nella console EMM, utilizza l'ESA esistente per chiamare setAccount.

Gestisci chiavi account di servizio

Gli account di servizio restituiti da Enterprises.getServiceAccount vengono creati in modo trasparente da Google. In qualità di EMM, non hai accesso a questi account. Tuttavia, puoi integrare l'API Serviceaccountkeys nella tua console per consentire alle organizzazioni di gestire le proprie chiavi e ESA generate in modo programmatico.

L'API Serviceaccountkeys consente a un'organizzazione di inserire, eliminare ed elencare le credenziali attive per i propri account di servizio. Queste API devono essere richiamate mentre sono autorizzate come ESA impostata per l'organizzazione e l'ESA deve essere stata generata da getServiceAccount. In altre parole, dopo che un'organizzazione chiama Enterprises.setAccount (utilizzando l'account di servizio generato da Enterprises.getServiceAccount), solo quell'organizzazione è autorizzata a richiamare le chiamate sull'API Serviceaccountkeys per gestire l'account.

Tabella 2. API Serviceaccountkeys

Campi
idUn identificatore di stringa univoco opaco per il ServiceAccountKey assegnato dal server.
kindIdentifica la risorsa utilizzando la stringa fissa androidenterprise#serviceAccountKey.
tipoFormato file dei dati della chiave generati. Valori accettati:
  • googleCredentials
  • pkcs12
datiUna stringa che comprende il corpo del file delle credenziali private. Il campo viene compilato al momento della creazione. Non vengono memorizzate da Google.
Metodi
eliminaRimuovi e invalida le credenziali specificate per l'account di servizio (specificato con enterpriseId e keyId).
insertGenera nuove credenziali per l'account di servizio associato all'azienda.
listElenca tutte le credenziali attive per l'account di servizio associato all'azienda. Restituisce solo l'ID e il tipo di chiave.

Notifiche

Puoi ricevere notifiche dagli ESA generati in modo programmatico chiamando il numero Enterprises.pullNotificationSet. Per ulteriori informazioni, vedi Configurare le notifiche EMM.

Registrazione dei domini Google gestiti

Per gestire i dispositivi che appartengono a un dominio Google gestito, devi stabilire una connessione (nota come associazione) tra la console EMM, l'organizzazione e Google.

Prerequisiti

L'organizzazione deve avere un dominio Google gestito, un token di registrazione EMM e un account di servizio aziendale (ESA). Le istruzioni per gli amministratori IT su come ottenere questi dettagli sono disponibili nel Centro assistenza Android Enterprise.

Dominio Google gestito

Se l'amministratore IT dell'organizzazione ha rivendicato un dominio gestito al momento della registrazione a Google Workspace, può abilitare la gestione di Android dalla Console di amministrazione Google. Se l'organizzazione non ha un dominio Google gestito, l'amministratore IT deve eseguire un processo di registrazione web una tantum con Google.

Token EMM

Gli amministratori IT possono ottenere un token EMM dalla Console di amministrazione Google (in Dispositivi > Dispositivi mobili ed endpoint > Impostazioni > Integrazioni di terze parti).

ESA

L'amministratore IT della tua organizzazione può creare l'ESA, in genere tramite la console Google Cloud su un progetto associato alla console EMM. Gli ESA hanno un nome, un ID e una chiave che autentica l'account per le azioni intraprese per loro conto. L'ID è formattato in modo simile a un indirizzo email, con il nome dell'account di servizio che precede il simbolo @ e il nome del progetto che segue, insieme alle informazioni sui servizi Google (ad esempio,some-orgs-esa@myemmconsole313302.iam.gserviceaccount.com).

Procedura di registrazione

  1. Un amministratore IT riceve un token EMM dalla Console di amministrazione Google.
  2. L'amministratore IT condivide con te il token EMM, il che ti autorizza a gestire Android nel suo dominio.
  3. Tramite la console EMM, utilizza il token EMM per chiamare Enterprises.enroll. Ciò associa la soluzione Android dell'organizzazione al suo dominio Google.
    • Il metodo enroll restituisce un enterpriseId univoco, che puoi recuperare in seguito (solo per i domini Google gestiti) utilizzando il metodo list.
    • Se vuoi, puoi archiviare le informazioni sull'associazione (enterpriseId, primaryDomain) in un datastore per evitare di effettuare chiamate API per ottenere questi dettagli. In uno scenario di Account Google, primaryDomain dell'organizzazione è la chiave univoca che identifica l'organizzazione per l'EMM e per Google.
  4. Per effettuare chiamate specifiche dell'organizzazione all'API EMM di Google Play:
    • Puoi creare un'ESA per conto dell'organizzazione o un amministratore crea l'ESA e poi la condivide con te.
    • Tramite la console EMM, chiama setAccount utilizzando il enterpriseId e l'indirizzo email dell'ESA. Ciò consente all'ESA di autenticarsi nell'API come azienda.

Esempio

Ecco un esempio in cui viene registrata un'organizzazione con i seguenti valori primaryDomainName, serviceAccountEmail e authenticationToken:

    public void bind(String primaryDomainName, String serviceAccountEmail,
        String authenticationToken) throws IOException {

      Enterprise enterprise = new Enterprise();
      enterprise.setPrimaryDomain(primaryDomainName);

      Enterprise result = androidEnterprise.enterprises()
          .enroll(authenticationToken, enterprise)
          .execute();

      EnterpriseAccount enterpriseAccount = new EnterpriseAccount();
      enterpriseAccount.setAccountEmail(serviceAccountEmail);
      androidEnterprise.enterprises()
          .setAccount(result.getId(), enterpriseAccount)
          .execute();
    }

Questo esempio utilizza la libreria client per Java e la classe di servizio AndroidEnterprise del pacchetto com.google.api.services.androidenterprise.model. La procedura mostrata nell'esempio può essere riassunta nei seguenti passaggi:

  1. Crea un nuovo oggetto AndroidEnterprise con i parametri forniti da bind, una classe di modello contenente il nome di dominio principale, l'indirizzo email dell'account di servizio e il token di registrazione EMM.
  2. Specifica il nome di dominio principale dell'oggetto aziendale appena creato.
  3. Chiama il metodo di registrazione, fornendo l'oggetto Enterprise e il token di registrazione.
  4. Crea un nuovo oggetto EnterpriseAccount con l'ID ESA del cliente (serviceAccountEmail).
  5. Imposta l'account fornendo sia il campo enterpriseId (restituito nel passaggio 3) sia il campo enterpriseAccount.

Se vuoi, puoi archiviare le informazioni sull'associazione (enterpriseId, primaryDomain) in un datastore per evitare di effettuare chiamate API per ottenere questi dettagli. In uno scenario di Account Google, primaryDomain dell'organizzazione è la chiave univoca che identifica l'organizzazione per l'EMM e per Google.

Configura un deployment on-premise

Se un'organizzazione richiede che i propri dati rimangano sul sito e inaccessibili a te, devi assicurarti che i tuoi server non vedano mai un set di credenziali attivo per l'ESA. Per farlo, genera e memorizza un set di credenziali dell'ESA sul sito:

  1. Completa il flusso di registrazione:
    1. Come mostrato nel passaggio 11, utilizza il tuo MSA per chiamare getServiceAccount. In questo modo vengono generate le credenziali ESA.
    2. Come mostrato nel passaggio 12, utilizza setAccount sull'ESA per impostarlo come ESA per questa organizzazione.
  2. Passare l'ESA al server on-premise dell'organizzazione.
  3. Segui questi passaggi sul server on-premise:
    1. Chiama Serviceaccountkeys.insert per creare una nuova chiave per l'ESA. Questa chiave privata non viene archiviata sui server di Google e viene restituita solo una volta, al momento della creazione dell'account. Non è accessibile in nessun altro modo.
    2. Utilizza le nuove credenziali dell'ESA per chiamare Serviceaccountkeys.list. Questa operazione restituisce le credenziali dell'account di servizio attivo.
    3. Chiama Serviceaccountkeys.delete per eliminare tutte le credenziali tranne quelle dell'ESA appena create on-premise.
    4. (Facoltativo) Chiama Serviceaccountkeys.list per verificare che le credenziali attualmente in uso on-premise siano le uniche credenziali valide per l'account di servizio.

Il server on-premise è ora l'unico server con le credenziali dell'ESA. Solo un ESA generato tramite getServiceAccount può accedere ServiceAccountKeys, mentre il tuo MSA non è autorizzato a chiamarlo.

Best practice: non archiviare le credenziali dell'account di servizio principale (MSA) on-premise. Utilizza un'ESA separata per ogni deployment on-premise.

Annullare la registrazione, registrarsi di nuovo o eliminare un'associazione aziendale

Annulla registrazione

Per svincolare un'organizzazione dalla soluzione EMM, utilizza unenroll. Un'associazione aziendale non viene eliminata all'annullamento della registrazione, ma gli utenti gestiti da EMM e tutti i dati utente correlati vengono eliminati dopo 30 giorni. Ecco un esempio di implementazione:

    public void unbind(String enterpriseId) throws IOException {
      androidEnterprise.enterprises().unenroll(enterpriseId).execute();
    }

Best practice: se disponi di un datastore per le mappature dei nomi delle organizzazioni e degli ID di associazione aziendale, elimina le informazioni dal datastore dopo aver chiamato unenroll.

Nuova registrazione

Un amministratore IT può registrare di nuovo un'azienda utilizzando il suo enterpriseId esistente. Per farlo, devono accedere con un account a livello di proprietario e seguire la procedura di registrazione.

Il flusso di nuova registrazione è trasparente dal tuo punto di vista: non è possibile determinare se il token aziendale restituito nell'URL di reindirizzamento (passaggio 8) proviene da una nuova organizzazione o da un'organizzazione precedentemente registrata con un'altra EMM.

Se un'organizzazione è stata precedentemente registrata con la tua soluzione EMM, potresti essere in grado di riconoscere l'ID di associazione aziendale. Puoi ripristinare gli utenti gestiti da EMM e i relativi dati utente se un amministratore IT registra di nuovo un'organizzazione non più di 30 giorni dopo l'annullamento della registrazione alla tua organizzazione. Se un'organizzazione è stata precedentemente registrata con un altro EMM, gli ID utente degli utenti gestiti da EMM creati dall'altro EMM non saranno accessibili. Questo perché questi ID utente sono specifici di EMM.

Elimina

Un amministratore IT può eliminare la propria organizzazione dalla versione gestita di Google Play. Entro 24 ore i dati, gli account, l'assegnazione delle licenze e altre risorse dell'organizzazione vengono resi inaccessibili a te, all'amministratore e agli utenti finali. Di conseguenza, le tue chiamate API restituiranno un codice di stato della risposta HTTP 404 Not Found per il parametro enterpriseId. Per gestire questo errore nella console EMM, chiedi conferma all'amministratore IT prima di rimuovere qualsiasi associazione con l'organizzazione.