Como lidar com permissões granulares

Visão geral

Com as permissões detalhadas, os consumidores têm um controle mais preciso sobre quais dados da conta eles querem compartilhar com cada app. Elas beneficiam tanto os usuários quanto os desenvolvedores, oferecendo mais controle, transparência e segurança. Este guia ajuda a entender as mudanças necessárias e as etapas para atualizar seus aplicativos para lidar com permissões granulares.

O que é permissão granular?

Imagine que você desenvolve um app de produtividade que solicita 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 optar por 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 seja de login é solicitado

Escopos de login e não 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 detalhada 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 todos os três escopos de login e um escopo do Google Drive que não é de 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 que não é de login

Uma tela 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 querem aprovar para compartilhar com o aplicativo. Veja a seguir um exemplo de tela 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 permissão granular 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 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 permissão granular 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 permissão. A tabela a seguir resume quando a tela de permissão granular é exibida.

Determinar se os 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 aos que solicitam vários escopos, porque eles ativam telas de permissão granular apresentadas aos usuários. Nesses casos, verifique se o código pode lidar com o caso em que os usuários autorizam apenas alguns dos escopos.

Como determinar se o 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 vão fazer com que a tela de permissão granular 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 OAuth do Google para solicitar permissão dos 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. Alguns exemplos são mostrados na seção a seguir. Consulte a documentação dos SDKs que seu aplicativo usa para processar o OAuth 2.0 do Google e determinar se ele é afetado, usando 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 earlier.
    * 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

O método para inspecionar chamadas de rede varia de acordo com o tipo de aplicativo.

• Aplicativo da Web: inspecione a atividade da rede no Chrome.
• Android: inspecionar 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 de extensões.
  • 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.
  • Uma caixa de diálogo Ferramentas para desenvolvedores será aberta, onde você poderá monitorar o tráfego de rede na guia Rede.
• iOS: como analisar o tráfego HTTP com o Instruments
• Apps para computador: use uma ferramenta de captura de rede disponível para o sistema operacional em que o app foi desenvolvido.

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 de não login.

  O exemplo de solicitação a seguir contém os três escopos de login e um escopo que não é de login para visualizar 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.

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

1. Leia a Política de dados do usuário dos serviços de 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 necessários. Evite pedir vários escopos no login, a menos que seja essencial para a funcionalidade principal do app. Agrupar vários escopos, especialmente para usuários iniciantes 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 o aplicativo.
3. Forneça uma justificativa 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 o usuário vai se beneficiar ao aprovar a solicitação. Nossa pesquisa indica que essas explicações aumentam a confiança e o engajamento do usuário.
4. Use a autorização incremental sempre que o aplicativo solicitar escopos para evitar o gerenciamento de vários tokens de acesso.
5. Verifique quais escopos os usuários concederam. Ao solicitar vários escopos de uma vez, os usuários podem não conceder todos os escopos que seu app solicita. O app precisa sempre verificar quais escopos foram concedidos pelo usuário e lidar com qualquer negação de escopos desativando os recursos relevantes. Siga as políticas do OAuth 2.0 do Google sobre como lidar com 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

Apps 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ários 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 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

...
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 Login do Google para iOS e macOS para interagir com o OAuth 2.0 do Google, consulte 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 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 modo de acesso do lado do servidor (off-line) exige que você faça o seguinte:

• Configure um servidor e defina um endpoint acessível publicamente para receber o código de autorização.
• Configure o URI de redirecionamento do endpoint público na página Clientes do console do Google Cloud.

O snippet de código a seguir mostra um exemplo em NodeJS que solicita dois escopos que não são de login. Os usuários vão ver a tela 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 earlier
  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 the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization 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 earlier
  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 the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization 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 somente do lado do cliente

• Para aplicativos que usam a biblioteca JavaScript dos Serviços de Identificação do Google para interagir com o OAuth 2.0 do Google, consulte esta documentação sobre como lidar com 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 lidar com permissões granulares.

Testar o aplicativo atualizado para lidar com 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 aplicativo. Por exemplo, se o usuário autorizar apenas dois dos três escopos solicitados, o aplicativo precisará se comportar de acordo.

2. Teste o aplicativo com a permissão granular ativada. Há duas maneiras de ativar as 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 do cliente do OAuth 2.0 do Google 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 OAuth do Google. 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 implementação não permitir a adição do parâmetro, crie um novo ID do cliente do OAuth 2.0 do Google 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 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, testar com uma conta do Workspace da sua organização pode não mostrar a nova tela de permissão granular como esperado.