Visão geral
Com permissões granulares, os consumidores têm um controle mais refinado sobre quais dados da conta optam por compartilhar com cada app. Eles beneficiam usuários e desenvolvedores, fornecendo maior controle, transparência e segurança. Este guia vai ajudar você a entender as mudanças e etapas necessárias para atualizar seus aplicativos e lidar com permissões granulares.
O que é permissão granular?
Imagine que você desenvolva um app de produtividade que solicite escopos de e-mail e agenda. Talvez os usuários queiram usar o aplicativo apenas para o Google Agenda, mas não para o Gmail. Com permissões do OAuth granulares, os usuários podem optar por conceder permissão apenas ao Google Agenda, não ao Gmail. Ao permitir que os usuários concedam acesso a dados específicos, isso minimiza a exposição de dados, reforça a confiança e oferece aos usuários controle com foco na privacidade sobre a vida digital. É importante projetar seu aplicativo para lidar com esses cenários.
Quando mais de um escopo que não seja de login é solicitado
Escopos de login e não de login
Nos apps que solicitam escopos de login e que não são de login, os usuários primeiro acessam a página de consentimento de escopos de login (email
, profile
e openid
). Depois que os usuários consentirem em compartilhar as informações básicas de identidade (nome, endereço de e-mail e foto do perfil), os usuários verão uma tela de permissão granular para os escopos que não são de login. Nesse caso, o aplicativo precisa verificar quais escopos são concedidos pelos usuários e não pode presumir que os usuários concedem todos os escopos solicitados. No exemplo a seguir, o aplicativo da Web solicita os três escopos de login e um
escopo sem login do Google Drive. Depois que os usuários consentirem com os escopos de login, eles verão a tela de permissão granular para a permissão do Google Drive:
Mais de um escopo que não seja de login
Uma tela de consentimento de permissão granular é mostrada aos usuários quando os aplicativos solicitam mais de um escopo que não seja de login. Os usuários podem selecionar quais permissões eles querem aprovar para compartilhar com o aplicativo. Confira a seguir um exemplo de tela de permissão granular que solicita acesso às mensagens do Gmail e aos dados do Google Agenda do usuário:
Para aplicativos que solicitam apenas escopos de login (email
, profile
e openid
), a tela de consentimento de permissões granulares não é aplicável. Os usuários aprovam ou negam toda a solicitação de
login. Ou seja, se os aplicativos solicitarem apenas escopos de login (um, dois ou todos
os três), a tela de permissão granular não será aplicável.
Para aplicativos que solicitam apenas um escopo que não seja de login, a tela de consentimento de permissão granular não será aplicável. Ou seja, os usuários aprovam ou negam toda a solicitação, e não há caixa de seleção na tela de consentimento. A tabela a seguir resume quando a tela de consentimento de permissões granulares é exibida.
Número de escopos de login | Número de escopos que não são de login | Tela de consentimento de permissões granulares |
---|---|---|
1-3 | 0 | Não relevante |
1-3 | + de 1 | Aplicável |
0 | 1 | Não relevante |
0 | 2+ | Aplicável |
Determine se seus aplicativos serão afetados
Faça uma análise completa de todas as seções do aplicativo em que os endpoints de autorização do Google OAuth 2.0 são utilizados para solicitações de permissão. Preste atenção naqueles que solicitam vários escopos à medida que eles ativam as telas de consentimento de permissão granular apresentadas aos usuários. Nesses casos, verifique se o código consegue lidar com as situações em que os usuários autorizam apenas alguns dos escopos.
Como determinar se seu aplicativo está usando vários escopos
Inspecione o código do app ou a chamada de rede de saída para determinar se as solicitações de autorização do OAuth 2.0 do Google feitas pelo app farão com que a tela de consentimento de permissões granulares seja mostrada.
Inspecionar o código do aplicativo
Revise as seções do código do aplicativo em que você faz chamadas para os endpoints de autorização do Google OAuth para solicitar a permissão dos usuários. Se você usa uma das bibliotecas de cliente das APIs do Google, geralmente descobre quais escopos o aplicativo solicita nas etapas de inicialização do cliente. Confira alguns exemplos na seção a seguir. Consulte a documentação dos SDKs que seu aplicativo usa para lidar com o Google OAuth 2.0 e determine se seu aplicativo será afetado, usando a orientação mostrada nos exemplos a seguir como referência.
Serviços de Identificação do Google
O snippet de código da biblioteca JavaScript dos Serviços de Identificação do Google a seguir inicializa o TokenClient
com vários escopos que não são de login. A tela de consentimento de permissão granular é exibida quando o app da Web solicita a autorização dos usuários.
const client = google.accounts.oauth2.initTokenClient({ client_id: 'YOUR_CLIENT_ID', scope: 'https://www.googleapis.com/auth/calendar.readonly \ https://www.googleapis.com/auth/contacts.readonly', callback: (response) => { ... }, });
Python
O snippet de código a seguir usa o módulo google-auth-oauthlib.flow
para criar a solicitação de autorização. O parâmetro scope
inclui dois escopos que não são de login. A tela de consentimento de permissão granular é exibida quando o aplicativo da Web solicita a autorização dos usuários.
import google.oauth2.credentials import google_auth_oauthlib.flow # Use the client_secret.json file to identify the application requesting # authorization. The client ID (from that file) and access scopes are required. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/calendar.readonly', 'https://www.googleapis.com/auth/contacts.readonly'])
Node.js
O snippet de código a seguir cria um objeto google.auth.OAuth2
, que define os parâmetros na solicitação de autorização em que o parâmetro scope
inclui dois escopos que não são de login. A tela de consentimento de permissão granular será exibida quando o app da Web solicitar a autorização dos usuários.
const {google} = require('googleapis'); /** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI * from the client_secret.json file. To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */ const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for read-only Calendar and Contacts. const scopes = [ 'https://www.googleapis.com/auth/calendar.readonly', 'https://www.googleapis.com/auth/contacts.readonly'] ]; // Generate a url that asks permissions const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as best practices. include_granted_scopes: true });
Inspecionar chamada de rede de saída
- Aplicativo da Web: inspecione a atividade de rede no Chrome
- Android: inspecione o tráfego de rede com o Network Inspector
-
Apps do Chrome
- Acesse a página de Extensões do Chrome.
- Marque a caixa de seleção Modo de desenvolvedor no canto superior direito da página da extensão.
- Selecione a extensão que você quer monitorar.
- Clique no link página de plano de fundo na seção Inspecionar visualizações da página da extensão.
- Será aberto um pop-up de Ferramentas para desenvolvedores, onde você pode monitorar o tráfego de rede na guia "Rede".
- iOS: Como analisar o tráfego HTTP com instrumentos
- Universal Windows Platform (UWP): inspecione o tráfego de rede no Visual Studio
- Apps para computador: use uma ferramenta de captura de rede disponível para o sistema operacional para que o app foi desenvolvido
Ao inspecionar chamadas de rede, procure solicitações enviadas para os endpoints de autorização do Google OAuth e examine o parâmetro scope
.
Esses valores cause a exibição da tela de consentimento granular de permissões.
O parâmetro
scope
contém escopos de login e outros que não.O exemplo de solicitação a seguir contém os três escopos de login e um que não seja de login para visualizar os metadados dos arquivos do usuário no Google Drive:
https://accounts.google.com/o/oauth2/v2/auth? access_type=offline& scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20openid%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly& include_granted_scopes=true& response_type=code& redirect_uri=YOUR_REDIRECT_URL& client_id=YOUR_CLIENT_ID
O parâmetro
scope
contém mais de um escopo que não seja de login.O exemplo de solicitação a seguir contém dois escopos que não são de login para visualizar os metadados do Google Drive do usuário e gerenciar arquivos específicos do Google Drive:
https://accounts.google.com/o/oauth2/v2/auth? access_type=offline& scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file& include_granted_scopes=true& response_type=code& redirect_uri=YOUR_REDIRECT_URL& client_id=YOUR_CLIENT_ID
Práticas recomendadas para lidar com permissões granulares
Se você determine que seu aplicativo precisa ser atualizado para lidar com permissões granulares, faça as atualizações necessárias no código para que ele lide corretamente com o consentimento para vários escopos. Todos os aplicativos precisam obedecer às seguintes práticas recomendadas:
- Revise a política de dados do usuário dos serviços das APIs do Google e verifique se você está em conformidade com elas.
- Solicite escopos específicos necessários para uma tarefa. É preciso estar em conformidade com a política do Google OAuth 2.0 solicitando apenas os escopos necessários. Evite pedir vários escopos no login, a menos que seja essencial para a funcionalidade principal do app. Agrupá-los, especialmente para novos usuários que não conhecem os recursos do aplicativo, pode dificultar a compreensão da necessidade dessas permissões. Isso pode gerar alarmes e impedir que os usuários interajam mais com seu aplicativo.
- Forneça uma justificativa aos usuários antes de fazer a solicitação de autorização. Explique claramente por que seu aplicativo precisa da permissão solicitada, o que você fará com os dados do usuário e como o usuário se beneficiará com a aprovação da solicitação. Nossa pesquisa indica que essas explicações aumentam a confiança e o engajamento do usuário.
- Use a autorização incremental sempre que o aplicativo solicitar escopos para evitar o gerenciamento de vários tokens de acesso.
- Verifique os escopos concedidos aos usuários. Ao solicitar vários escopos de uma só vez, talvez os usuários não concedam todos os escopos solicitados pelo app. É preciso que seu app sempre verifique quais escopos foram concedidos pelo usuário e desative os recursos relevantes para lidar com qualquer negação de escopo. Siga as políticas do Google OAuth 2.0 sobre gerenciamento de consentimento para vários escopos e só solicite o consentimento do usuário depois que ele indicar claramente uma intenção de usar o recurso específico que exige o escopo.
Atualizar o aplicativo para lidar com permissões granulares
Aplicativos Android
Consulte a documentação dos SDKs que você usa para interagir com o Google OAuth 2.0 e atualize seu aplicativo para lidar com permissões granulares com base nas práticas recomendadas.
Se você usar o SDK
auth.api.signin
do Google Play Services para interagir com o Google OAuth 2.0, poderá usar a função
requestPermissions
para solicitar o menor conjunto de escopos necessários
e a função
hasPermissions
para verificar os escopos concedidos pelo usuário ao
solicitar permissões granulares.
Aplicativos de extensão do Chrome
Use a API Identity do Chrome para trabalhar com o Google OAuth 2.0 com base nas práticas recomendadas.
O exemplo a seguir mostra como lidar corretamente com permissões granulares.
manifest.json
O arquivo de manifesto de exemplo declara dois escopos que não são de login para o aplicativo de extensão do Chrome.
{ "name": "Example Chrome extension application", ... "permissions": [ "identity" ], "oauth2" : { "client_id": "YOUR_CLIENT_ID", "scopes":["https://www.googleapis.com/auth/calendar.readonly", "https://www.googleapis.com/auth/contacts.readonly"] } }
Abordagem incorreta
Tudo ou nada
Os usuários clicam no botão para iniciar o processo de autorização. O snippet de código pressupõe que os usuários recebem uma tela de consentimento "tudo ou nada" para os dois escopos especificados no arquivo manifest.json
. Ela deixa de verificar quais escopos os usuários concederam.
oauth.js
... document.querySelector('button').addEventListener('click', function () { chrome.identity.getAuthToken({ interactive: true }, function (token) { if (token === undefined) { // User didn't authorize both scopes. // Updating the UX and application accordingly ... } else { // User authorized both or one of the scopes. // It neglects to check which scopes users granted and assumes users granted all scopes. // Calling the APIs, etc. ... } }); });
Abordagem correta
Menor escopo
Selecione o menor conjunto de escopos necessário
O aplicativo deve solicitar apenas o menor conjunto de escopos necessário. Recomenda-se que seu aplicativo solicite um escopo por vez quando for necessário para concluir uma tarefa.
Neste exemplo, supõe-se que ambos os escopos declarados no arquivo manifest.json
sejam o menor conjunto necessário. O arquivo oauth.js
usa a API Chrome Identity para iniciar o processo de autorização com o Google. É preciso optar por
ativar permissões granulares para que os usuários tenham mais controle sobre a concessão de permissões ao aplicativo. Seu aplicativo deve processar corretamente a resposta dos usuários verificando quais escopos eles autorizam.
oauth.js
... document.querySelector('button').addEventListener('click', function () { chrome.identity.getAuthToken({ interactive: true, enableGranularPermissions: true }, function (token, grantedScopes) { if (token === undefined) { // User didn't authorize any scope. // Updating the UX and application accordingly ... } else { // User authorized the request. Now, check which scopes were granted. if (grantedScopes.includes('https://www.googleapis.com/auth/calendar.readonly')) { // User authorized Calendar read permission. // Calling the APIs, etc. ... } else { // User didn't authorize Calendar read permission. // Update UX and application accordingly ... } if (grantedScopes.includes('https://www.googleapis.com/auth/contacts.readonly')) { // User authorized Contacts read permission. // Calling the APIs, etc. ... } else { // User didn't authorize Contacts read permission. // Update UX and application accordingly ... } } }); });
Aplicativos iOS, iPadOS e macOS
Consulte a documentação dos SDKs que você usa para interagir com o Google OAuth 2.0 e atualize seu aplicativo para lidar com permissões granulares com base nas práticas recomendadas.
Se você usa a biblioteca do Login do Google para iOS e macOS para interagir com o OAuth 2.0 do Google, revise a documentação sobre como lidar com permissões granulares.
Aplicativos da Web
Consulte a documentação dos SDKs que você usa para interagir com o Google OAuth 2.0 e atualize seu aplicativo para lidar com permissões granulares com base nas práticas recomendadas.
Acesso do lado do servidor (off-line)
- Coloque um servidor em execução e defina um endpoint acessível publicamente para receber o código de autorização.
- Configure o URI de redirecionamento do seu endpoint público no Credentials page do console do Google Cloud.
O snippet de código a seguir mostra um exemplo de NodeJS que solicita dois escopos que não são de login. Os usuários vão encontrar a tela de permissão granular.
Abordagem incorreta
Tudo ou nada
Os usuários são redirecionados para o URL de autorização. O snippet de código pressupõe que os usuários recebem uma tela de consentimento "tudo ou nada" para os dois escopos especificados na instrução scopes
. Ela deixa de verificar quais escopos os usuários concederam.
main.js
... const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for two non-Sign-In scopes - Google Calendar and Contacts const scopes = [ 'https://www.googleapis.com/auth/contacts.readonly', 'https://www.googleapis.com/auth/calendar.readonly' ]; // Generate a url that asks permissions for the Google Calendar and Contacts scopes const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', // Pass in the scopes array defined above scope: scopes, // Enable incremental authorization. Recommended as best practices. include_granted_scopes: true }); async function main() { const server = http.createServer(async function (req, res) { // Example on redirecting user to Google OAuth 2.0 server. if (req.url == '/') { res.writeHead(301, { "Location": authorizationUrl }); } // Receive the callback from Google OAuth 2.0 server. if (req.url.startsWith('/oauth2callback')) { // Handle the Google OAuth 2.0 server response let q = url.parse(req.url, true).query; if (q.error) { // User didn't authorize both scopes. // Updating the UX and application accordingly ... } else { // User authorized both or one of the scopes. // It neglects to check which scopes users granted and assumes users granted all scopes. // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); // Calling the APIs, etc. ... } } res.end(); }).listen(80); }
Abordagem correta
Menor escopo
Selecione o menor conjunto de escopos necessário
O aplicativo deve solicitar apenas o menor conjunto de escopos necessário. Recomenda-se que seu aplicativo solicite um escopo por vez quando for necessário para concluir uma tarefa. Sempre que o aplicativo solicitar escopos, ele deverá usar autorização incremental para evitar a necessidade de gerenciar vários tokens de acesso.
Caso seu aplicativo precise solicitar vários escopos que não sejam de login, use sempre a autorização incremental ao solicitar e verificar quais escopos os usuários concederam.
Neste exemplo, supõe-se que os dois escopos declarados são necessários para o funcionamento correto do app. É preciso optar por ativar permissões granulares para que os usuários tenham mais controle sobre a concessão de permissões ao aplicativo. Seu aplicativo deve processar corretamente a resposta dos usuários verificando quais escopos eles autorizaram.
main.js
... const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for two non-Sign-In scopes - Google Calendar and Contacts const scopes = [ 'https://www.googleapis.com/auth/contacts.readonly', 'https://www.googleapis.com/auth/calendar.readonly' ]; // Generate a url that asks permissions for the Google Calendar and Contacts scopes const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', // Pass in the scopes array defined above scope: scopes, // Enable incremental authorization. Recommended as best practices. include_granted_scopes: true, // Set to true to enable more granular permissions for Google OAuth 2.0 client IDs created before 2019. // No effect for newer Google OAuth 2.0 client IDs, since more granular permissions is always enabled for them. enable_granular_consent: true }); async function main() { const server = http.createServer(async function (req, res) { // Redirect users to Google OAuth 2.0 server. if (req.url == '/') { res.writeHead(301, { "Location": authorizationUrl }); } // Receive the callback from Google OAuth 2.0 server. if (req.url.startsWith('/oauth2callback')) { // Handle the Google OAuth 2.0 server response let q = url.parse(req.url, true).query; if (q.error) { // User didn't authorize both scopes. // Updating the UX and application accordingly ... } else { // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); // User authorized the request. Now, check which scopes were granted. if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly')) { // User authorized Calendar read permission. // Calling the APIs, etc. ... } else { // User didn't authorize Calendar read permission. // Calling the APIs, etc. ... } // Check which scopes user granted the permission to application if (tokens.scope.includes('https://www.googleapis.com/auth/contacts.readonly')) { // User authorized Contacts read permission. // Calling the APIs, etc. ... } else { // User didn't authorize Contacts read permission. // Update UX and application accordingly ... } } } res.end(); }).listen(80); }
Consulte o guia de apps da Web do lado do servidor para saber como acessar as APIs do Google em aplicativos baseados em servidor.
Acesso apenas no lado do cliente
- Para que os aplicativos que usam a biblioteca JavaScript dos Serviços de Identificação do Google interajam com o Google OAuth 2.0, confira esta documentação sobre como lidar com permissões granulares.
- No caso de aplicativos que fazem chamadas diretamente usando JavaScript para endpoints de autorização do Google OAuth 2.0, confira esta documentação sobre como lidar com permissões granulares.
Teste o aplicativo atualizado sobre como lidar com permissões granulares
- Descreva todos os casos em que os usuários podem responder a solicitações de permissão e o comportamento esperado do seu aplicativo. Por exemplo, se o usuário autorizar apenas dois dos três escopos solicitados, seu aplicativo deverá se comportar corretamente.
-
Teste seu aplicativo com a permissão granular ativada. Há duas maneiras de ativar
permissões granulares:
- Verifique as telas de consentimento do OAuth 2.0 do seu aplicativo para ver se as permissões granulares já estão ativadas. Também é possível criar um novo ID do cliente OAuth 2.0 para Web, Android ou iOS por meio do console do Google Cloud para fins de teste, já que a permissão granular está sempre ativada para eles.
-
Defina o parâmetro
enable_granular_consent
comotrue
ao chamar os endpoints de autorização do Google OAuth. Alguns SDKs têm suporte explícito para esse parâmetro. Para outros, consulte a documentação para ver como adicionar esse parâmetro e o valor dele manualmente. Se a sua implementação não oferecer suporte à adição do parâmetro, você poderá criar um novo ID do cliente OAuth 2.0 para Web, Android ou iOS por meio do console do Google Cloud para fins de teste, conforme indicado no ponto anterior.
- Ao testar o aplicativo atualizado, use uma Conta do Google pessoal (@gmail.com) em vez de uma conta do Workspace. Isso ocorre porque os apps do Workspace Enterprise com delegação de autoridade em todo o domínio ou marcados como Confiáveis não são afetados pelas mudanças nas permissões granulares no momento. Portanto, os testes com uma conta do Workspace da sua organização podem não mostrar a nova tela de consentimento granular conforme o esperado.