Como lidar com permissões granulares

Visão geral

Com as permissões detalhadas, os consumidores têm um controle mais refinado sobre quais dados da conta eles compartilham com cada app. Isso beneficia usuários e desenvolvedores, oferecendo mais controle, transparência e segurança. Este guia ajuda a entender as mudanças e etapas necessárias para atualizar seus aplicativos e processar permissões granulares.

O que é permissão granular?

Imagine que você desenvolva um app de produtividade que solicite escopos de e-mail e agenda. Seus usuários podem querer usar seu aplicativo apenas para o Google Agenda, mas não para o Gmail. Com as permissões granulares do OAuth, os usuários podem conceder permissão apenas ao Google Agenda, mas não ao Gmail. Ao permitir que os usuários concedam acesso a dados específicos, isso minimiza a exposição de dados, aumenta a confiança e capacita os usuários com controle de privacidade em primeiro lugar sobre a vida digital deles. É importante projetar o aplicativo para lidar com esses cenários.

Quando mais de um escopo que não é de login é solicitado

Escopos de login e sem login

Para aplicativos que solicitam escopos de login e não login, os usuários primeiro veem a página de consentimento para escopos de login (email, profile e openid). Depois que os usuários consentem em compartilhar as informações básicas de identidade (nome, endereço de e-mail e foto do perfil), eles veem uma tela de consentimento de permissão granular para os escopos de não login. Nesse caso, o aplicativo precisa verificar quais escopos são concedidos pelos usuários e não pode presumir que eles concedem todos os escopos solicitados. No exemplo a seguir, o aplicativo da Web solicita todos os três escopos de login e um escopo do Google Drive que não exige login. Depois que os usuários consentirem com os escopos de login, eles vão ver a tela de consentimento de permissões granulares para a permissão do Google Drive:

Mais de um escopo sem login

Uma tela granular de consentimento de permissão será mostrada aos usuários quando os aplicativos solicitarem mais de um escopo que não seja de login. Os usuários podem selecionar as permissões que querem aprovar para compartilhar com o aplicativo. Confira abaixo um exemplo de tela de consentimento de permissão granular solicitando 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. Em outras palavras, se os aplicativos solicitarem apenas escopos de login (um, dois ou todos os três), a tela granular de consentimento de permissão não será aplicável.

Para aplicativos que solicitam apenas um escopo que não seja de login, a tela granular de consentimento de permissão não é aplicável. Em outras palavras, os usuários aprovam ou negam toda a solicitação, e não há uma caixa de seleção na tela de consentimento. A tabela a seguir resume quando a tela de consentimento para permissões granulares é exibida.

Determinar se seus aplicativos foram afetados

Faça uma análise completa de todas as seções do aplicativo em que os endpoints de autorização do OAuth 2.0 do Google são usados para solicitações de permissão. Preste atenção naqueles que solicitam vários escopos, já que eles ativam telas de consentimento de permissão granular apresentadas aos usuários. Nesses casos, verifique se o código pode processar a situação 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 Google OAuth 2.0 que o app faz vão causar a exibição da tela de consentimento de permissões granulares.

Inspecionar o código do aplicativo

Revise as seções do código do aplicativo em que você está fazendo chamadas aos endpoints de autorização do Google OAuth para pedir permissão aos usuários. Se você usa uma das bibliotecas de cliente das APIs do Google, geralmente é possível encontrar os escopos que seu aplicativo solicita nas etapas de inicialização do cliente. Confira alguns exemplos na seção a seguir. Consulte a documentação dos SDKs usados pelo aplicativo para processar o OAuth 2.0 do Google e determinar se o aplicativo é afetado. Use as orientações mostradas nos exemplos a seguir como referência.

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) => {
    ...
  },
});

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'])

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 uma chamada de rede de saída

Ao inspecionar as chamadas de rede, procure solicitações enviadas aos endpoints de autorização do OAuth do Google e examine o parâmetro scope.

Esses valores fazem com que a tela de permissão granular seja mostrada.

• O parâmetro scope contém escopos de login e não de login.

  Uma solicitação de amostra a seguir contém todos os três escopos de login e um escopo que não é de login para ver os metadados dos arquivos do Google Drive do usuário:

  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 é de login.

  Uma solicitação de amostra 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ê determinar que seu aplicativo precisa ser atualizado para processar permissões granulares, faça as atualizações necessárias no código para processar corretamente o consentimento para vários escopos. Todos os aplicativos precisam obedecer às seguintes práticas recomendadas:

1. Leia a Política de dados do usuário dos serviços da API do Google e verifique se você está em conformidade com ela.
2. Solicite escopos específicos necessários para uma tarefa. Você precisa obedecer à política do OAuth 2.0 do Google, que determina que você solicite apenas os escopos de que precisa. Evite pedir vários escopos no momento do login, a menos que seja essencial para a funcionalidade principal do app. Agrupar vários escopos, principalmente para usuários novos que não conhecem os recursos do aplicativo, pode dificultar a compreensão da necessidade dessas permissões. Isso pode gerar alertas e impedir que os usuários continuem interagindo com seu aplicativo.
3. Justifique aos usuários antes de pedir a autorização. Explique claramente por que o aplicativo precisa da permissão solicitada, o que você vai fazer com os dados do usuário e como ele vai se beneficiar ao aprovar a solicitação. Nossa pesquisa indica que essas explicações aumentam a confiança e o engajamento dos usuários.
4. Use autorização incremental sempre que o aplicativo solicitar escopos para evitar ter que gerenciar vários tokens de acesso.
5. Verifique quais escopos os usuários concederam. Ao solicitar vários escopos de uma só vez, os usuários podem não conceder todos os escopos que o app pede. O app precisa sempre verificar quais escopos foram concedidos pelo usuário e processar qualquer negação de escopos desativando os recursos relevantes. Siga as políticas do OAuth 2.0 do Google sobre como processar o consentimento para vários escopos e só peça o consentimento do usuário novamente quando ele indicar claramente a intenção de usar o recurso específico que exige o escopo.

Atualizar o aplicativo para processar permissões granulares

Aplicativos Android

Consulte a documentação dos SDKs que você usa para interagir com o OAuth 2.0 do Google e atualize seu aplicativo para processar permissões granulares com base nas práticas recomendadas.

Se você usa o SDK auth.api.signin do Google Play Services para interagir com o OAuth 2.0 do Google, use a função requestPermissions para solicitar o menor conjunto de escopos necessário e a função hasPermissions para verificar quais escopos o usuário concedeu ao solicitar permissões granulares.

Aplicativos de extensão do Chrome

Use a API Chrome Identity para trabalhar com o OAuth 2.0 do Google com base nas práticas recomendadas.

O exemplo a seguir mostra como processar corretamente as permissões granulares.

manifest.json

O exemplo de arquivo de manifesto 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

...
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

...
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 OAuth 2.0 do Google e atualize seu aplicativo para processar permissões granulares com base nas práticas recomendadas.

Se você usa a biblioteca Google Sign-In para iOS e macOS para interagir com o Google OAuth 2.0, consulte a documentação sobre como processar permissões granulares.

Aplicativos da Web

Consulte a documentação dos SDKs que você usa para interagir com o OAuth 2.0 do Google e atualize seu aplicativo para processar permissões granulares com base nas práticas recomendadas.

Acesso do lado do servidor (off-line)

O snippet de código a seguir mostra um exemplo do NodeJS que solicita dois escopos que não são de login. Os usuários vão ver a tela de consentimento de permissão granular.

Abordagem incorreta

...
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

...
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 web apps do lado do servidor para saber como acessar as APIs do Google em aplicativos baseados em servidor.

Acesso somente do lado do cliente

• Para aplicativos que usam a biblioteca JavaScript dos Serviços de identidade do Google para interagir com o OAuth 2.0 do Google, consulte esta documentação sobre como processar permissões granulares.
• Para aplicativos que fazem chamadas diretamente usando JavaScript para endpoints de autorização do OAuth 2.0 do Google, consulte esta documentação sobre como processar permissões granulares.

Teste o aplicativo atualizado no processamento de permissões granulares

1. 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 precisará se comportar de acordo.
2. Teste seu aplicativo com a permissão granular ativada. Há duas maneiras de ativar permissões granulares:
   1. Verifique as telas de permissão do OAuth 2.0 do seu aplicativo para conferir se as permissões granulares já estão ativadas para ele. Também é possível criar um novo ID de cliente do Google OAuth 2.0 para Web, Android ou iOS no console do Google Cloud para fins de teste, já que a permissão granular está sempre ativada para eles.
   2. Defina o parâmetro enable_granular_consent como true 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 saber como adicionar esse parâmetro e o valor dele manualmente. Se a sua implementação não aceitar a adição do parâmetro, crie um novo ID do cliente Google OAuth 2.0 para Web, Android ou iOS no console do Google Cloud apenas para fins de teste, conforme indicado no ponto anterior.
3. Ao testar o aplicativo atualizado, use uma Conta do Google pessoal (@gmail.com) em vez de uma conta do Workspace. Isso acontece 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, testar com uma conta do Workspace da sua organização pode não mostrar a nova tela de consentimento granular como esperado.