A autenticação e a autorização são mecanismos usados para verificar a identidade e o acesso aos recursos, respectivamente. Este documento identifica os principais termos que você precisa conhecer antes de implementar a autenticação e a autorização no seu app.
A autenticação identifica quem está fazendo a solicitação. A autorização identifica a quais recursos o solicitante pode acessar e qual é o nível de acesso dele. A autenticação é um pré-requisito para a autorização. Não é possível determinar quais recursos acessar sem primeiro estabelecer a identidade do solicitante. Para uma definição mais detalhada, consulte a seção Terminologia importante.
Considere o exemplo simplificado a seguir de uma reserva de hotel. Ao chegar ao hotel, o recepcionista pede seu documento de identificação para verificar sua reserva. Seu documento de identidade autentica você no hotel. O atendente da recepção entrega uma chave do hotel. Essa chave dá acesso a determinados recursos do hotel, como o quarto, a academia e o centro de reuniões. A chave do hotel autoriza você a acessar esses recursos.
Visão geral do processo
O diagrama a seguir mostra as etapas de alto nível de autenticação e autorização para APIs do Google Workspace:
Configure seu projeto e app do Google Cloud:durante o desenvolvimento, registre o app no console do Google Cloud, definindo escopos de autorização e credenciais de acesso para autenticar o app com uma chave de API, credencial de usuário final ou credencial de conta de serviço.
Autentique seu app para acesso:quando o app é executado, as credenciais de acesso registradas são avaliadas. Se o app estiver autenticando como um usuário final, um prompt de login poderá ser exibido.
Solicitar recursos:quando seu app precisa de acesso a recursos do Google, ele faz uma solicitação usando os escopos de acesso relevantes que você registrou anteriormente.
Peça o consentimento do usuário:se o app estiver se autenticando como um usuário final, o Google vai mostrar a tela de permissão do OAuth para que o usuário decida se quer conceder acesso aos dados solicitados.
Envie uma solicitação aprovada de recursos:se o usuário consentir com os escopos de acesso, o app vai agrupar as credenciais e os escopos de acesso aprovados pelo usuário em uma solicitação. A solicitação é enviada ao servidor de autorização do Google para receber um token de acesso.
O Google retorna um token de acesso:o token de acesso contém uma lista de escopos de acesso concedidos. Se a lista de escopos retornada for mais limitada do que os escopos de acesso solicitados, o app vai desativar todos os recursos limitados pelo token.
Acessar os recursos solicitados:seu app usa o token de acesso do Google para invocar as APIs relevantes e acessar os recursos.
Receber um token de atualização (opcional): se o app precisar de acesso a uma API do Google além do ciclo de vida de um único token de acesso, ele poderá receber um token de atualização.
Solicitar mais recursos:se for necessário mais acesso, o app pede ao usuário para conceder novos escopos de acesso, resultando em uma nova solicitação para receber um token de acesso (etapas 3 a 6).
Terminologia importante
Confira a seguir uma lista de termos relacionados à autenticação e autorização:
- Authentication
O ato de garantir que um principal, que pode ser um usuário ou um app agindo em nome de um usuário, é quem ele diz ser. Ao escrever apps do Google Workspace, você precisa conhecer estes tipos de autenticação:
- Autenticação de usuários
- O ato de um usuário se autenticar (fazer login) no seu app. A autenticação de usuário geralmente é realizada por um processo de login em que o usuário usa uma combinação de nome de usuário e senha para verificar a identidade no app. A autenticação de usuário pode ser incorporada a um app usando o Fazer login com o Google.
- Autenticação de apps
- O ato de um app se autenticar diretamente nos serviços do Google em nome do usuário que está executando o app. A autenticação do app geralmente é realizada usando credenciais pré-criadas no código do app.
- Autorização
As permissões ou "autoridade" que o principal tem para acessar dados ou realizar operações. A autorização é feita por um código que você escreve no app. Esse código informa ao usuário que o app quer agir em nome dele e, se permitido, usa as credenciais exclusivas do app para receber um token de acesso do Google usado para acessar dados ou realizar operações.
- Credential
Uma forma de identificação usada na segurança de software. Em termos de autenticação, uma credencial geralmente é uma combinação de nome de usuário e senha. Em termos de autorização para APIs do Google Workspace, uma credencial geralmente é alguma forma de identificação, como uma string secreta exclusiva, conhecida apenas entre o desenvolvedor do app e o servidor de autenticação. O Google aceita estas credenciais de autenticação: chave de API, ID do cliente OAuth 2.0 e contas de serviço.
- Chave de API
- A credencial usada para solicitar acesso a dados públicos, como dados fornecidos usando a API Maps ou arquivos do Google Workspace compartilhados com a configuração "Qualquer pessoa na Internet com este link" nas configurações de compartilhamento do Google Workspace.
- ID do cliente OAuth 2
- A credencial usada para solicitar acesso a dados de propriedade do usuário. Essa é a credencial principal usada ao solicitar acesso a dados usando as APIs do Google Workspace. Essa credencial exige consentimento do usuário.
- Chave secreta do cliente
- Uma string de caracteres que só deve ser conhecida pelo seu aplicativo e pelo servidor de autorização. O segredo do cliente protege os dados do usuário concedendo tokens apenas a solicitantes autorizados. Nunca inclua a chave secreta do cliente não criptografada no seu app. Recomendamos armazenar a chave secreta com segurança. Para mais informações, consulte Processar credenciais do cliente com segurança.
- Chaves da conta de serviço
- Usado por contas de serviço para receber autorização de um serviço do Google.
- Conta de serviço
- Uma credencial usada para interações entre servidores, como um app sem interface que é executado como um processo para acessar alguns dados ou realizar alguma operação. As contas de serviço geralmente são usadas para acessar dados e operações baseados na nuvem. No entanto, quando usadas com a delegação de autoridade em todo o domínio, elas podem ser usadas para acessar dados do usuário.
- Escopo
Uma string URI do OAuth 2.0 que define um nível de acesso a recursos ou ações concedido a um app. Para o Google Workspace, os URIs de escopo de autorização contêm o nome do app do Google Workspace, o tipo de dados acessados e o nível de acesso. Os usuários do seu app podem analisar os escopos solicitados e escolher o acesso a ser concedido. Em seguida, o servidor de autenticação do Google retorna os escopos permitidos ao seu app em um token de acesso. Para mais detalhes, consulte Como escolher escopos para seu app.
- Servidor de autorização
Servidor do Google para conceder acesso, usando um token de acesso, aos dados e operações solicitados de um app.
- Código de autorização
Um código enviado pelo servidor de autorização usado para receber um token de acesso. Um código só é necessário quando o tipo de aplicativo é um app de servidor da Web ou um app instalado.
- Token de acesso
Um token que concede acesso a uma API do Google Workspace. Um único token de acesso pode conceder vários graus de acesso, conhecidos como escopos, a várias APIs. O código de autorização do app solicita tokens de acesso e os usa para invocar APIs do Google Workspace.
- Servidor de recursos
O servidor que hospeda a API que seu app quer chamar.
- Framework OAuth 2.0
Um padrão que seu app pode usar para fornecer a ele "acesso delegado seguro" ou acesso a dados e operações em nome do usuário do app. Os mecanismos de autenticação e autorização usados no app representam a implementação do framework OAuth 2.0.
- Principal
Uma entidade, também conhecida como identidade, que pode receber acesso a um recurso. As APIs do Google Workspace são compatíveis com dois tipos de principais: contas de usuário e contas de serviço. Para mais detalhes, consulte Principais.
- Tipo de dado
No contexto de autenticação e autorização, o tipo de dados se refere à entidade proprietária dos dados que o app está tentando acessar. Há três tipos de dados:
- Dados de domínio público
- Dados acessíveis a qualquer pessoa, como alguns dados do Google Maps. Esses dados geralmente são acessados usando uma chave de API.
- Dados do usuário final
- Dados pertencentes a um usuário final ou grupo específico, como os arquivos do Google Drive de um usuário específico. Em geral, esse tipo de dados é acessado usando um ID de cliente ou uma conta de serviço do OAuth 2.
- Dados na nuvem
- Dados pertencentes a um projeto do Google Cloud. Esse tipo de dados geralmente é acessado por uma conta de serviço.
- Consentimento do usuário
Uma etapa de autorização que exige que o usuário do app autorize o acesso a dados e a realização de operações em nome dele.
- Tipo de aplicativo
O tipo de app que você vai criar. Ao criar credenciais usando o console do Google Cloud, você precisa selecionar o tipo de aplicativo. Os tipos de aplicativos são: aplicativo da Web (JavaScript), Android, app Chrome, iOS, TVs e dispositivos de entrada limitada, app para computador (também chamado de "app instalado") e Plataforma Universal do Windows (UWP).
- Conta de serviço
Um tipo especial de Conta do Google destinada a representar um usuário não humano que precisa ser autenticado e autorizado a acessar dados. Seu aplicativo assume a identidade da conta de serviço para chamar as APIs do Google, evitando o envolvimento direto dos usuários. Sozinhas, as contas de serviço não podem ser usadas para acessar dados do usuário, que geralmente são acessados usando APIs do Workspace. No entanto, uma conta de serviço pode acessar dados do usuário implementando a delegação de autoridade em todo o domínio. Para mais detalhes, consulte Noções básicas sobre contas de serviço.
- Delegação de autoridade em todo o domínio
Um recurso de administração que pode autorizar um aplicativo a acessar dados do usuário em nome dos usuários na organização do Google Workspace. A delegação em todo o domínio pode ser usada para realizar tarefas relacionadas ao administrador nos dados do usuário. Para delegar autoridade dessa forma, os administradores do Google Workspace usam contas de serviço com o OAuth 2.0. Devido ao poder desse recurso, apenas os superadministradores podem ativar a delegação de autoridade em todo o domínio. Para mais detalhes, consulte Delegar autoridade em todo o domínio a uma conta de serviço.
Próxima etapa
Configure a tela de consentimento do OAuth do seu app para garantir que os usuários entendam e aprovem o acesso do app aos dados deles.