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 gerenciado | Domí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 . | ||
primaryDomain | Nã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 definido | O 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:
Um administrador de TI inicia o processo de criação de uma empresa. Para fazer isso, o administrador de TI:
- Faça login no console de EMM.
- Clica ou seleciona Configurar Android (por exemplo) e é redirecionado para uma interface de inscrição hospedada pelo Google.
- Apresenta detalhes sobre a empresa na interface de inscrição.
- é 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 chamandoEnterprises.getServiceAccount
e processando o gerenciamento de chaves usando as APIsServiceaccountkeys
. 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.
Um administrador de TI inicia uma solicitação de inscrição no console de EMM.
Chame
Enterprises.generateSignupUrl
comcallbackURL
como o único parâmetro. Exemplo:https://localhost:8080/enrollcomplete?session=12345
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.
Extraia o
url
da respostagenerateSignupURL
.Redirecione para o URL extraído na etapa 4.
O administrador de TI segue o fluxo de configuração na IU de inscrição para criar uma vinculação empresarial:
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.
O nome do EMM será exibido ao administrador de TI, e ele confirmará que a organização estará vinculada a esse EMM.
O administrador de TI concorda com os Termos de Serviço do Google.
A interface de inscrição gera um URL de callback com base no URL especificado na etapa 2.
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
Chame
Enterprises.completeSignup
, transmitindocompletionToken
(etapa 3) eenterpriseToken
(etapa 8).A chamada retorna uma instância
Enterprises
no corpo da resposta. Armazene oid
,name
e o e-mail do administrador (se presente) para uso futuro.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.
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:
Chame
Enterprises.getServiceAccount
com oenterpriseId
(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).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 | |
id | Um identificador de string exclusivo opaco para a ServiceAccountKey atribuído pelo servidor. |
kind | Identifica o recurso usando a string fixa
androidenterprise#serviceAccountKey . |
digitar | Formato de arquivo dos dados principais gerados. Valores aceitáveis:
|
dados | Uma string composta pelo corpo do arquivo de credenciais particulares. Preenchido na criação. Não é armazenado pelo Google. |
Métodos | |
excluir | Remova e invalide as credenciais especificadas para a
conta de serviço (especificada com enterpriseId e keyId ).
|
inserir | Gerar novas credenciais para a conta de serviço associada à empresa. |
list | Liste 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
- Um administrador de TI recebe um token de EMM do Google Admin Console.
- O administrador de TI compartilha o token de EMM com você, o que autoriza a gerenciar o Android no domínio dele.
- 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 umenterpriseId
exclusivo, que pode ser recuperado posteriormente (somente para domínios gerenciados do Google) usando o métodolist
. - 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, oprimaryDomain
da organização é a chave exclusiva que a identifica para o EMM e para o Google.
- O método
- 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 oenterpriseId
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:
- Crie um novo objeto
AndroidEnterprise
com os parâmetros fornecidos porbind
, 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. - Especifique o nome de domínio principal do objeto empresarial recém-criado.
- Chame o método de registro fornecendo o objeto empresarial e o token de inscrição.
- Crie um novo objeto EnterpriseAccount com o ID do ESA do cliente
(
serviceAccountEmail
). - Defina a conta fornecendo os campos
enterpriseId
(retornado na etapa 3) eenterpriseAccount
.
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:
- Conclua o fluxo de inscrição:
- Conforme mostrado na etapa 11, use seu MSA para chamar
getServiceAccount
. Isso gera credenciais da ESA. - Conforme mostrado na etapa 12, use
setAccount
na ESA para defini-la como a ESA para a organização.
- Conforme mostrado na etapa 11, use seu MSA para chamar
- Transmita a ESA para o servidor local da organização.
- Siga estas etapas no servidor local:
- 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. - Use as novas credenciais da ESA para chamar
Serviceaccountkeys.list
. Isso retorna as credenciais da conta de serviço ativa. - Chame
Serviceaccountkeys.delete
para excluir todas as credenciais, exceto as da ESA que acabaram de ser criadas no local. - Opcional: chame
Serviceaccountkeys.list
para verificar se as credenciais usadas no local são as únicas válidas para a conta de serviço.
- Chame
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.