Criar uma vinculação empresarial

Para inscrever uma nova organização por meio do console de EMM, é necessário criar uma vinculação empresarial. Um recurso Enterprises representa a vinculação entre um EMM e uma organização. Você usa uma instância dele para invocar operações em nome da organização.

A API Play EMM oferece três maneiras de criar uma instância de vinculação empresarial:

  • Inscrição de domínio gerenciado do Google: esse método pode ser usado no lugar dos outros métodos. Organizações com um domínio gerenciado do Google e organizações que são novas no trabalho com o Google usarão a mesma IU de inscrição. A jornada que eles fazem pela IU varia de acordo com a situação e as necessidades. A organização não precisa receber um token de EMM com antecedência.

  • Inscrição em contas do Google Play gerenciado: Uma organização quer usar contas do Google Play gerenciado. É possível integrar a interface de inscrição do Android do Google ao console de EMM e fornecer às organizações uma maneira rápida de criar uma instância de vinculação empresarial que as vincule ao EMM. Isso ativa as contas do Google Play gerenciado para usuários e dispositivos. Essa abordagem às vezes é chamada de iniciada pelo EMM na documentação da API. Esse método foi descontinuado e substituído pelo método de inscrição de domínio gerenciado do Google que foi usado anteriormente.

  • Inscrição de domínio do Google gerenciado : uma organização tem um domínio gerenciado do Google. Eles concluem várias tarefas manuais, como verificar a propriedade do domínio com o Google, conseguir um token de EMM e criar uma conta de serviço empresarial. Essa abordagem às vezes é chamada de iniciada pelo Google na documentação da API.

Você pode oferecer suporte a qualquer uma dessas abordagens no console de EMM usando o recurso Enterprises. A Tabela 1 mostra os campos e as operações relevantes desse recurso para vincular organizações a EMMs.

Tabela 1: APIs Enterprise e os processos de vinculação alternativos

 Pacote de contas do Google Play gerenciadoDomínio do Google gerenciado Descrição
Campo
id Identificador exclusivo da organização, retornado das chamadas enroll e completeSignup.
kind Identifica o tipo de recurso usando um valor fixo de string, •androidenterprise#enterpriseros.
name Organização associada ao objeto enterprise.
primaryDomainNão definido Como os pacotes de contas do Google Play gerenciado não estão vinculados ao modelo de domínio do Google, esse campo é relevante somente para domínios gerenciados do Google.
administrador[]Não definidoO administrador de TI que se inscrever no Android usando o processo de inscrição iniciado pelo EMM se tornará o administrador (proprietário) da vinculação empresarial. Com o Google Play Console gerenciado, o administrador de TI pode convidar outros usuários na organização para participar das tarefas de administração. Consulte a Central de Ajuda do Google Play gerenciado.
administrador[].email Não definido
Métodos
completeSignup Com um completionToken e um enterpriseToken, retorna um recurso Enterprises no corpo da resposta.
generateSignupUrl Retorna um URL e um completionToken com um callbackUrl.
Inscrever Registra o autor da chamada no EMM cujo token é enviado com a solicitação.
getServiceAccount Retorna uma conta de serviço e credenciais.
setAccount Define a conta que será usada para autenticar a API como a empresa.
Cancelar inscrição Os EMMs podem separar a vinculação a qualquer tipo de empresa usando o cancelamento da inscrição. Precisa ser invocado usando as credenciais do EMM para o MSA, não as credenciais da ESA.

Inscrição em contas do Google Play gerenciado

O uso desse método de inscrição foi descontinuado. Use o método de inscrição de domínios gerenciados do Google.

Inscrição em domínios do Google gerenciados

Você pode integrar o processo de inscrição no console de EMM da seguinte forma:

Inscrição de administrador de contas do Google Play gerenciado
Figura 1. Fluxo de trabalho de inscrição de domínios gerenciados do Google

Um administrador de TI inicia o processo de criação de uma empresa. Para fazer isso, o administrador de TI:

  1. Faça login no console de EMM.
  2. Clica ou seleciona Configurar Android (por exemplo) e é redirecionado para uma interface de inscrição hospedada pelo Google.
  3. Apresenta detalhes sobre a empresa na interface de inscrição.
  4. é redirecionado para o console de EMM.

O endereço de e-mail do administrador de TI agora está vinculado a uma Conta do Google que é uma conta de administrador de um domínio gerenciado do Google.

Prática recomendada: siga as diretrizes de segurança do Google para ajudar a manter a conta de administrador segura.

Pré-requisitos

Para administradores de TI

  • Acesso ao console de EMM e às permissões necessárias para fazer a seleção adequada no console (por exemplo, Gerenciar o Android, como uma opção de menu).

  • Um endereço de e-mail do trabalho. Deve fazer parte de um domínio de propriedade da organização e não um domínio compartilhado, como Gmail.com

No console de EMM

Para implementar o fluxo de inscrição gerenciado do Google Doomain, o console de EMM precisa ser capaz de:

  • Use suas credenciais de MSA ao invocar chamadas nas APIs de EMM do Google Play. O MSA é usado para invocar muitas das operações em nome de um administrador de TI até que a conta de serviço empresarial (ESA, na sigla em inglês) da organização seja definida.

  • Processe o redirecionamento por meio de um URL seguro para um site externo fornecido pelo Google para iniciar o fluxo de inscrição e concluir o processo de inscrição.

  • Ser configurável com as credenciais da ESA após a inscrição. Como o console de EMM pode ser usado para criar muitas empresas no site de qualquer organização, você precisa de uma maneira de associar cada enterpriseId à própria conta de serviço e credenciais. Considere criar contas de serviço para a organização chamando Enterprises.getServiceAccount e processando o gerenciamento de chaves usando as APIs Serviceaccountkeys. Consulte Criar contas de serviço empresarial de maneira programática para mais detalhes.

O processo de inscrição do Android exige que você forneça um serviço seguro (https) para uso do console no momento da execução. O URL para esse serviço seguro pode ser um URL local e pode incluir sessões ou outras informações de identificação exclusivas, desde que estejam bem formadas para que o sistema possa analisá-las. Exemplo:

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

Processo de inscrição

O processo de inscrição foi projetado para levar menos de cinco minutos. Nas etapas abaixo, supomos que o servidor que hospeda o callbackUrl está em execução. Essas etapas também pressupõem que o console inclua um componente de IU, como uma seleção de menu com a opção Gerenciar Android, que inicia o processo de inscrição quando um administrador de TI autenticado seleciona a opção.

Processo de 12 etapas para inscrever um negócio de contas do Google Play gerenciado
Figura 2. Processo de 12 etapas para criar uma vinculação com um domínio gerenciado do Google.
  1. Um administrador de TI inicia uma solicitação de inscrição no console de EMM.

  2. Chame Enterprises.generateSignupUrl com callbackURL como o único parâmetro. Exemplo:

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

  3. A resposta conterá um URL de inscrição (válido por 30 minutos) e um token de conclusão. Extraia e salve o token de conclusão.

    Prática recomendada:associe o token de conclusão ao administrador de TI que iniciou a inscrição.

  4. Extraia o url da resposta generateSignupURL.

  5. Redirecione para o URL extraído na etapa 4.

  6. O administrador de TI segue o fluxo de configuração na IU de inscrição para criar uma vinculação empresarial:

    1. O administrador de TI insere detalhes sobre ele e a organização dele e define uma senha, caso ainda não tenha uma Conta do Google.

    2. O nome do EMM será exibido ao administrador de TI, e ele confirmará que a organização estará vinculada a esse EMM.

    3. O administrador de TI concorda com os Termos de Serviço do Google.

  7. A interface de inscrição gera um URL de callback com base no URL especificado na etapa 2.

  8. A interface de inscrição redireciona o administrador de TI ao URL de callback. Extraia e salve o token corporativo no URL. Exemplo:

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

  9. Chame Enterprises.completeSignup, transmitindo completionToken (etapa 3) e enterpriseToken (etapa 8).

  10. A chamada retorna uma instância Enterprises no corpo da resposta. Armazene o id, name e o e-mail do administrador (se presente) para uso futuro.

  11. Crie uma conta de serviço empresarial (ESA). As credenciais da ESA assumem a forma de um endereço de e-mail e uma chave privada. Há duas maneiras de criar uma ESA:

    • Prática recomendada:crie o ESA de maneira programática usando a API Play EMM.
    • Mostre uma página que instrui o administrador de TI a criar um ESA no Console de APIs do Google. Para informações mais detalhadas, consulte Como criar uma conta de serviço. Instrua o administrador a selecionar projeto > Editor como o papel e marque a caixa de download da chave privada. Depois que o administrador de TI criar uma ESA, configure o console com as credenciais de chave privada dela.
  12. Usando suas credenciais do MSA, chame setAccount para definir o ESA para essa organização.

O processo de inscrição foi concluído

  • O novo domínio gerenciado do Google está vinculado ao EMM.
  • A Conta do Google do administrador de TI está configurada como um administrador do domínio e pode acessar https://play.google.com/work para gerenciar os apps da organização.
  • Seu console de EMM pode usar a ESA para gerenciar os dados da organização usando a API Google Play EMM.

Criar ESAs de forma programática

Para simplificar o gerenciamento de chaves para ESAs, gere contas de serviço para organizações em vez de usar o Console do Google Cloud usando a API EMM do Google Play. Contas de serviço geradas pela API Play EMM:

  • Não são visíveis em nenhum projeto do Console do Cloud que pertence a você ou à organização. Eles precisam ser gerenciados de forma programática.
  • São excluídos quando você cancela a inscrição da organização.

Para gerar uma conta de serviço de maneira programática:

  1. Chame Enterprises.getServiceAccount com o enterpriseId (consulte a etapa 10 no Processo de inscrição) e especifique o tipo de chave (keyType) que você quer (googleCredentials, pkcs12). O sistema retorna um nome de conta de serviço e uma chave privada para a conta de serviço (nos mesmos formatos retornados pelo Console de APIs do Google).

  2. Chame Enterprises.setAccount e defina a conta de serviço da organização.

Prática recomendada:peça para o administrador de TI alterar as credenciais da ESA. Para fazer isso no console de EMM, use o ESA atual para chamar setAccount.

Gerenciar chaves da conta de serviço

As contas de serviço retornadas de Enterprises.getServiceAccount são criadas de forma transparente pelo Google. Como EMM, você não tem acesso a essas contas. No entanto, é possível integrar a API Serviceaccountkeys ao console para permitir que as organizações gerenciem os próprios ESAs e chaves gerados programaticamente.

Com a API Serviceaccountkeys, a organização pode inserir, excluir e listar as credenciais ativas das respectivas contas de serviço. Essas APIs precisam ser invocadas enquanto estiverem autorizadas como a ESA definida para a organização, e esse ESA precisa ter sido gerado em getServiceAccount. Em outras palavras, depois que uma organização chama Enterprises.setAccount (usando a conta de serviço gerada por Enterprises.getServiceAccount), somente ela é autorizada a invocar chamadas na API Serviceaccountkeys para gerenciar a conta.

Tabela 2: API Serviceaccountkeys

Campos
idUm identificador de string exclusivo opaco para a ServiceAccountKey atribuído pelo servidor.
kindIdentifica o recurso usando a string fixa androidenterprise#serviceAccountKey.
digitarFormato de arquivo dos dados principais gerados. Valores aceitáveis:
  • googleCredentials
  • pkcs12
dadosUma string composta pelo corpo do arquivo de credenciais particulares. Preenchido na criação. Não é armazenado pelo Google.
Métodos
excluirRemova e invalide as credenciais especificadas para a conta de serviço (especificada com enterpriseId e keyId).
inserirGerar novas credenciais para a conta de serviço associada à empresa.
listListe todas as credenciais ativas da conta de serviço associada à empresa. Retorna apenas o ID e o tipo de chave.

Notificações

É possível receber notificações de ESAs gerados programaticamente chamando Enterprises.pullNotificationSet. Consulte Configurar notificações de EMM para mais informações.

Inscrição de domínio do Google gerenciado

Para gerenciar dispositivos que pertençam a um domínio gerenciado do Google, você precisa estabelecer uma conexão (conhecida como vinculação) entre o console de EMM, a organização e o Google.

Pré-requisitos

A organização precisa ter um domínio gerenciado do Google, um token de registro de EMM e uma conta de serviço empresarial (ESA, na sigla em inglês). As instruções para administradores de TI sobre como acessar esses detalhes estão disponíveis na Central de Ajuda do Android Enterprise.

Domínio do Google gerenciado

Se o administrador de TI da organização tiver reivindicado um domínio gerenciado quando se inscreveu no Google Workspace, ele poderá ativar o gerenciamento do Android no Google Admin Console. Se a organização não tiver um domínio gerenciado do Google, o administrador de TI precisará passar por um processo de registro da Web único com o Google.

Token do EMM

Os administradores de TI podem receber um token de EMM no Google Admin Console (em Dispositivos > Dispositivos móveis e endpoints > Configurações > Integrações de terceiros).

Espanha

O administrador de TI da sua organização pode criar a ESA, normalmente por meio do Console do Google Cloud em um projeto associado ao console de EMM. Os ESAs têm um nome, um ID e uma chave que autentica a conta para ações realizadas em nome dele. O ID é formatado de maneira semelhante a um endereço de e-mail, com o nome da conta de serviço antes do símbolo @ e o nome do projeto seguido, junto com as informações dos serviços do Google (por exemplo, some-orgs-esa@myemmconsole313302.iam.gserviceaccount.com).

Processo de inscrição

  1. Um administrador de TI recebe um token de EMM do Google Admin Console.
  2. O administrador de TI compartilha o token de EMM com você, o que autoriza a gerenciar o Android no domínio dele.
  3. No console de EMM, use o token para chamar Enterprises.enroll. Isso vincula a solução do Android da organização ao domínio do Google.
    • O método enroll retorna um enterpriseId exclusivo, que pode ser recuperado posteriormente (somente para domínios gerenciados do Google) usando o método list.
    • Você também pode armazenar informações sobre a vinculação (enterpriseId, primaryDomain) em um repositório de dados para evitar chamadas de API e receber esses detalhes. No cenário de Contas do Google, o primaryDomain da organização é a chave exclusiva que a identifica para o EMM e para o Google.
  4. Para fazer chamadas específicas da organização para a API Google Play EMM, faça o seguinte:
    • Você cria um ESA em nome da organização ou um administrador o cria e o compartilha com você.
    • No console de EMM, chame setAccount usando o enterpriseId e o endereço de e-mail da ESA. Isso permite que a ESA faça a autenticação na API como a empresa.

Exemplo

Confira um exemplo que registra uma organização com base em 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();
    }

Esse exemplo usa a biblioteca de cliente para Java e a classe de serviço AndroidEnterprise do pacote com.google.api.services.androidenterprise.model. O procedimento mostrado na amostra pode ser resumido nestes passos:

  1. Crie um novo objeto AndroidEnterprise com os parâmetros fornecidos por bind, uma classe de modelo que contenha o nome de domínio principal, o endereço de e-mail da conta de serviço e o token de registro do EMM.
  2. Especifique o nome de domínio principal do objeto empresarial recém-criado.
  3. Chame o método de registro fornecendo o objeto empresarial e o token de inscrição.
  4. Crie um novo objeto EnterpriseAccount com o ID do ESA do cliente (serviceAccountEmail).
  5. Defina a conta fornecendo os campos enterpriseId (retornado na etapa 3) e enterpriseAccount.

Você também pode armazenar informações sobre a vinculação (enterpriseId, primaryDomain) em um repositório de dados para evitar chamadas de API e receber esses detalhes. Em um cenário de Contas do Google, o primaryDomain da organização é a chave exclusiva que a identifica para o EMM e para o Google.

Configurar uma implantação no local

Se uma organização exigir que os dados permaneçam no local, inacessíveis para você, será necessário garantir que os servidores nunca vejam um conjunto ativo de credenciais para a ESA. Para isso, gere e armazene um conjunto de credenciais da ESA no site:

  1. Conclua o fluxo de inscrição:
    1. Conforme mostrado na etapa 11, use seu MSA para chamar getServiceAccount. Isso gera credenciais da ESA.
    2. Conforme mostrado na etapa 12, use setAccount na ESA para defini-la como a ESA para a organização.
  2. Transmita a ESA para o servidor local da organização.
  3. Siga estas etapas no servidor local:
    1. Chame Serviceaccountkeys.insert para criar uma nova chave para a ESA. Essa chave privada não é armazenada nos servidores do Google e é retornada apenas uma vez, quando a conta é criada. Ele não é acessível de outra forma.
    2. Use as novas credenciais da ESA para chamar Serviceaccountkeys.list. Isso retorna as credenciais da conta de serviço ativa.
    3. Chame Serviceaccountkeys.delete para excluir todas as credenciais, exceto as da ESA que acabaram de ser criadas no local.
    4. Opcional: chame Serviceaccountkeys.list para verificar se as credenciais usadas no local são as únicas válidas para a conta de serviço.

O servidor local agora é o único com as credenciais da ESA. Somente um ESA gerado por getServiceAccount pode acessar ServiceAccountKeys. Seu MSA não tem permissão para chamá-lo.

Prática recomendada: não armazene as credenciais da conta de serviço principal (MSA) no local. Use um ESA separado para cada implantação local.

Cancelar a inscrição, reinscrever ou excluir uma vinculação empresarial

Cancelar inscrição

Para desvincular uma organização da sua solução de EMM, use unenroll. Uma vinculação empresarial não é excluída quando o registro é cancelado, mas os usuários gerenciados por EMM e todos os dados do usuário relacionados são excluídos após 30 dias. Confira um exemplo de implementação:

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

Prática recomendada:se você tiver um armazenamento de dados para mapeamentos de nomes de organizações e IDs de vinculação empresarial, exclua as informações do repositório de dados depois de chamar unenroll.

Refazer a inscrição

Um administrador de TI pode reinscrever uma empresa usando a enterpriseId. Para isso, ele faz login com uma conta de proprietário e segue o processo de registro.

O fluxo de reinscrição é transparente na sua perspectiva: não há como determinar se o token corporativo retornado no URL de redirecionamento (etapa 8) é de uma nova organização ou de uma organização que tenha sido registrada anteriormente com outro EMM.

Se uma organização já tiver sido inscrita na solução de EMM, talvez seja possível reconhecer o ID de vinculação empresarial. Você poderá restaurar os usuários gerenciados por EMM e os dados dos usuários relacionados se um administrador de TI reinscrever uma organização no máximo 30 dias após o cancelamento da inscrição. Se uma organização já tiver sido inscrita com um EMM diferente, os IDs de usuário dos usuários gerenciados por EMM criados pelo outro EMM não poderão ser acessados por você. Isso ocorre porque esses IDs do usuário são específicos do EMM.

Excluir

Um administrador de TI pode excluir a organização dele no Google Play gerenciado. Em 24 horas, os dados, as contas, as atribuições de licenças e outros recursos da organização ficam inacessíveis para o administrador, os usuários finais e você. Como resultado, suas chamadas de API retornarão um código de status de resposta HTTP 404 Not Found para o parâmetro enterpriseId. Para lidar com esse erro no console de EMM, solicite a confirmação do administrador de TI antes de remover qualquer associação com a organização.