Autorização

Os apps autorizam chamadas para a API de cliente de registro sem toque usando o OAuth. Este documento explica a autorização da API para provedores de gerenciamento de mobilidade empresarial (EMM) e desenvolvedores de TI corporativos. Depois de ler este documento, você saberá como autorizar solicitações de API no app e explicará os requisitos da conta para os usuários.

Guia de início rápido de autorização

• Para configurar um projeto do Google Cloud Platform com a API de registro sem toque e as chaves secretas do cliente OAuth, execute este assistente.
• Crie o código de amostra do guia de início rápido para Java, .NET ou Python. Use as bibliotecas de cliente das APIs do Google para oferecer suporte a outras linguagens.

Informações gerais

1. Um ou mais administradores de TI são usuários em uma conta de cliente com registro sem toque.
2. Os administradores de TI usam uma Conta do Google para fazer a autenticação.
3. As solicitações de API transmitem um token OAuth2 para autorizar as solicitações em nome de um administrador de TI.

Contas de clientes

As configurações, os dispositivos e os usuários (administrador de TI) de uma organização pertencem a uma conta de cliente. Uma conta de cliente é semelhante a um grupo e não é um usuário individual. Um revendedor configura um cliente quando a organização compra dispositivos para o registro sem toque pela primeira vez. Os administradores de TI gerenciam outros usuários na organização usando o portal de registro sem toque.

A API usa IDs numéricos de clientes para identificar as contas. Você transmite o ID de cliente como parte do caminho do URL ao chamar métodos da API. Seu app precisa ter o ID de cliente do usuário antes de chamar qualquer método de API.

Veja no exemplo abaixo como conseguir as contas de cliente do usuário que autoriza a chamada de 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']))

No seu app, você precisará navegar pelas páginas de resultados da conta, porque o exemplo acima mostra apenas as primeiras 100 contas. Para saber como fazer isso, leia Resultados paginados.

Uma organização geralmente tem uma conta de cliente, mas organizações maiores podem usar contas de cliente separadas para cada divisão. Como um administrador de TI pode ser membro de diferentes contas de clientes, seu app deve ajudar os usuários a encontrar e usar novas contas de clientes. No seu aplicativo, rotule cada conta de cliente usando o valor companyName.

comerciais

Os administradores de TI autorizam as solicitações de API que o app envia em nome deles. Para autorizar solicitações de API, o usuário do app precisa fazer o seguinte:

1. associar uma Conta do Google ao endereço de e-mail;
2. Participe de uma conta de cliente usando o mesmo endereço de e-mail.
3. Aceite os Termos de Serviço do cliente com registro sem toque.

Para ajudar os usuários do app na configuração, reutilize nossas orientações para administradores de TI em Primeiros passos e Associar uma Conta do Google na sua própria documentação.

Gerenciamento de usuários

Os administradores de TI gerenciam os usuários das contas dos clientes no portal de registro sem toque. Os usuários em uma conta de cliente têm um papel de proprietário ou administrador. Os dois papéis têm o mesmo acesso à API do cliente, mas um proprietário pode gerenciar outros usuários.

Aceitação dos Termos de Serviço

Antes que os usuários do seu app possam autorizar chamadas de API, eles precisam aceitar os Termos de Serviço mais recentes. Isso acontece quando os administradores de TI usam o registro sem toque pela primeira vez ou quando atualizamos os TOS. Quando um usuário não aceita os TOS mais recentes, a API retorna um código de status HTTP 403 Forbidden e o corpo da resposta contém TosError.

O portal solicita automaticamente que os usuários aceitem os Termos de Serviço mais recentes ao fazer login. Para conferir as abordagens sugeridas que seu app pode incluir, leia Gerenciar os Termos de Serviço no guia de integração do EMM.

Adicionar autorização ao app

Todas as solicitações que o app envia para a API do cliente precisam incluir um token de autorização. O token também identifica o aplicativo para o Google. Como a API do cliente acessa os dados do usuário, a autorização precisa vir do proprietário desses dados. O app delega a autorização da API aos administradores de TI usando o protocolo OAuth 2.0.

Importante :para simplificar a configuração de autorização e autenticação, o Google fornece bibliotecas de cliente que podem reduzir a quantidade de código que você precisa escrever e tornar seu código mais robusto. Recomendamos usar uma biblioteca de cliente para chamar a API do cliente. Consulte os guias de início rápido para Java, .NET e Python.

Instruções

Fornecemos guias de início rápido para apps Java, .NET e Python. Se você estiver usando uma linguagem diferente, siga as duas etapas abaixo para configurar a autorização do seu app.

Etapa 1: ativar a API de registro sem toque

1. Use este assistente para criar ou selecionar um projeto no Google Developers Console e ativar a API automaticamente. Clique em Continuar e em Acessar credenciais .
2. Clique em Cancelar em "Criar credenciais".
3. Na parte superior da página, selecione a guia OAuth consent screen. Selecione um Endereço de e-mail, insira o Nome do produto, caso ainda não tenha sido definido, e clique no botão Salvar.
4. Selecione a guia Credenciais, clique no botão Criar credenciais e selecione ID do cliente OAuth.
5. Selecione um Tipo de aplicativo com base no tipo de app que você está criando.
6. Defina o Nome como o nome do seu app.
7. Clique em Criar.
8. Clique em Fazer o download do JSON.
9. Mova o arquivo para o diretório de trabalho e renomeie-o como client_secret.json.

Etapa 2: instalar a biblioteca de cliente

Para instalar a biblioteca de cliente para sua linguagem:

1. Acesse Bibliotecas de cliente das APIs do Google e selecione sua linguagem na lista de linguagens compatíveis.
2. Siga as orientações para instalar a biblioteca de cliente.

Para saber mais sobre a autorização, leia Como usar o OAuth 2.0 para acessar as APIs do Google.

Escopos de autorização

Use o escopo de autorização da API https://www.googleapis.com/auth/androidworkzerotouchemm no seu app para solicitar um token de acesso do OAuth 2.0.

Um parâmetro de escopo controla o conjunto de recursos e operações para os quais um token de acesso permite chamadas. Os tokens de acesso são válidos somente para o conjunto de operações e recursos descritos no escopo da solicitação de token. A API abrange todos os métodos e recursos com o escopo de registro sem toque único mostrado acima.

Veja um exemplo do escopo do registro sem toque usado com a biblioteca de cliente da API do Google nos guias de início rápido para Java, .NET e Python. Para saber mais sobre como usar os escopos da API do Google, leia Como usar o OAuth 2.0 para acessar as APIs do Google.

Práticas recomendadas para chaves de API

Ao usar as chaves de API nos aplicativos, tome cuidado para mantê-las em segurança. A exposição pública das credenciais pode resultar no comprometimento da sua conta, o que pode resultar em cobranças inesperadas. Para manter as chaves de API seguras, siga estas práticas recomendadas:

Não incorpore chaves de API diretamente no código

As chaves de API incorporadas no código podem ser expostas acidentalmente ao público, por exemplo, se você se esquecer de remover as chaves do código compartilhado. Em vez de incorporá-las nos aplicativos, armazene-as em variáveis de ambiente ou em arquivos fora da árvore de origem do aplicativo.

Não armazene chaves de API em arquivos dentro da árvore de origem do aplicativo.

Se você armazenar chaves de API em arquivos, mantenha esses arquivos fora da árvore de origem do aplicativo para garantir que elas não fiquem no sistema de controle do código-fonte. Isso é especialmente importante se você usa um sistema de gerenciamento de código-fonte público, como o GitHub.

Restrinja o uso das suas chaves de API apenas aos endereços IP, URLs referenciadores e apps para dispositivos móveis que precisam delas.

Ao restringir os endereços IP, URLs referenciadores e apps para dispositivos móveis que podem usar cada chave, você pode reduzir o impacto de uma chave de API comprometida. Para especificar os hosts e apps que podem usar cada chave no Console de APIs do Google, abra a página "Credenciais" e crie uma nova chave de API com as configurações que quiser ou edite as configurações de uma chave de API.

Excluir chaves de API desnecessárias

Para minimizar sua exposição a ataques, exclua todas as chaves de API de que você não precisa mais.

Gere novamente as chaves de API periodicamente

Você pode usar o Console de APIs do Google para gerar novamente as chaves de API. Para isso, abra a página "Credenciais", selecione uma chave de API e clique em Gerar chave novamente para cada chave. Em seguida, atualize seus aplicativos para usar as chaves recém-geradas. As chaves antigas continuarão funcionando por 24 horas após a geração das chaves de substituição.

Revise o código antes de liberá-lo publicamente

Verifique se o código não contém chaves de API ou outras informações particulares antes de disponibilizá-lo publicamente.