Ayrıntılı izinleri yönetme

Genel bakış

Ayrıntılı izinler sayesinde tüketiciler her bir uygulamayla paylaşacakları hesap verileri üzerinde daha hassas bir kontrol sahibi olurlar. Daha fazla kontrol, şeffaflık ve güvenlik sunarak hem kullanıcılara hem de geliştiricilere fayda sağlarlar. Bu kılavuz, uygulamalarınızı ayrıntılı izinleri işleyecek şekilde başarıyla güncellemek için gerekli değişiklikleri ve adımları anlamanıza yardımcı olur.

Ayrıntılı izin nedir?

Hem e-posta hem de takvim kapsamları isteyen bir üretkenlik uygulaması geliştirdiğinizi düşünün. Kullanıcılarınız, uygulamanızı yalnızca Google Takvim'de kullanmak isteyebilir, Gmail'de kullanmak istemeyebilir. Ayrıntılı OAuth izinleri sayesinde kullanıcılar yalnızca Google Takvim'e izin vermeyi (Gmail'e izin vermeyi değil) tercih edebilir. Kullanıcıların belirli verilere erişmesine izin vererek verilerin açığa çıkmasını en aza indirir, güveni artırır ve kullanıcıların dijital yaşamları üzerinde gizliliğe öncelik veren kontrol sahibi olmalarını sağlar. Uygulamanızı bu tür senaryolara uygun şekilde tasarlamanız önemlidir.

Birden fazla Oturum Açma dışı kapsam istendiğinde

Oturum açma ve oturum açma dışı kapsamlar

Hem Oturum Açma hem de Oturum Açma dışı kapsamları isteyen uygulamalarda, kullanıcılar önce Oturum Açma kapsamları (email, profile ve openid) için izin sayfasını görürler. Kullanıcılar temel kimlik bilgilerini (ad, e-posta adresi ve profil fotoğrafı) paylaşmayı kabul ettikten sonra, kullanıcılar Oturum Açma kapsamları için ayrıntılı bir izin izin ekranı görür. Bu durumda uygulama, kullanıcılar tarafından hangi kapsamların verildiğini kontrol etmelidir ve kullanıcıların istenen tüm kapsamları verdiğini varsayamaz. Aşağıdaki örnekte, web uygulaması üç Oturum Açma kapsamının tamamını ve bir Google Drive oturum açma dışı kapsamını ister. Kullanıcılar Oturum Açma kapsamlarına izin verdikten sonra, kullanıcılar Google Drive izni için ayrıntılı izinler onay ekranını görür:

Birden fazla oturum açma dışı kapsam

Uygulamalar birden fazla Oturum Açma dışı kapsam istediğinde kullanıcılara ayrıntılı bir izin ekranı gösterilir. Kullanıcılar, uygulamayla paylaşmak için onaylamak istedikleri izinleri seçebilir. Aşağıda, kullanıcının Gmail iletilerine ve Google Takvim verilerine erişim isteyen bir ayrıntılı izin ekranı örneği verilmiştir:

Yalnızca Oturum Açma kapsamları (email, profile ve openid) isteyen uygulamalar için #inspect-your-application-codegranular izinler izin ekranı geçerli değildir. Kullanıcılar oturum açma isteğinin tamamını onaylar veya reddeder. Başka bir deyişle, uygulamalar yalnızca Oturum Açma kapsamlarını (bir, iki veya üçü) istiyorsa ayrıntılı izin izin ekranı geçerli olmaz.

Yalnızca bir oturum açma dışı kapsam isteyen uygulamalar için ayrıntılı izin izin ekranı geçerli değildir. Başka bir deyişle, kullanıcılar isteğin tamamını onaylar veya reddeder ve izin ekranında onay kutusu bulunmaz. Aşağıdaki tabloda, ayrıntılı izinler izin ekranının ne zaman gösterildiği özetlenmiştir.

Uygulamalarınızın etkilenip etkilenmediğini belirleyin

Uygulamanızda, izin istekleri için Google OAuth 2.0 yetkilendirme uç noktalarının kullanıldığı tüm bölümleri kapsamlı bir şekilde inceleyin. Kullanıcılara sunulan ayrıntılı izin ekranlarını etkinleştirdiklerinden birden fazla kapsam isteyenlere dikkat edin. Böyle durumlarda kodunuzun, kullanıcıların yalnızca bazı kapsamları yetkilendirdiği durumları işleyebildiğinden emin olun.

Uygulamanızın birden fazla kapsam kullanıp kullanmadığını belirleme

Uygulamanızın yaptığı Google OAuth 2.0 yetkilendirme isteklerinin, ayrıntılı izinler izin ekranının gösterilmesine neden olup olmayacağını belirlemek için uygulama kodunuzu veya giden ağ çağrısını inceleyin.

Uygulama kodunuzu inceleyin

Uygulama kodunuzun, kullanıcılardan izin istemek için Google OAuth yetkilendirme uç noktalarına çağrı yaptığınız bölümlerini inceleyin. Google API İstemci Kitaplıklarından birini kullanıyorsanız uygulama isteklerinizin kapsamlarını genellikle istemci başlatma adımlarında bulabilirsiniz. Bazı örnekler aşağıdaki bölümde gösterilmiştir. Uygulamanızın etkilenip etkilenmediğini belirlemek için, aşağıdaki örneklerde gösterilen kılavuzu referans olarak kullanıp Google OAuth 2.0'ı işlerken uygulamanızın kullandığı SDK'ların belgelerini incelemeniz gerekir.

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
});

Giden ağ çağrısını denetle

Ağ çağrılarını denetlerken Google OAuth yetkilendirme uç noktalarına gönderilen istekleri arayın ve scope parametresini inceleyin.

Bu değerler, ayrıntılı izinler izin ekranının gösterilmesine cause.

• scope parametresi, Oturum Açma kapsamlarını ve Oturum Açma dışı kapsamları içerir.

  Aşağıdaki örnek istek, kullanıcının Google Drive dosyalarının meta verilerinin görüntülenmesi için üç Oturum Açma kapsamının tamamını ve bir adet Oturum Açma dışı kapsamı içerir:

  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

• scope parametresi birden fazla oturum açma dışı kapsam içeriyor.

  Aşağıdaki örnek istek, kullanıcının Google Drive meta verilerini görüntülemek ve belirli Google Drive dosyalarını yönetmek için kullanılan iki oturum açma dışı kapsam içerir:

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

Ayrıntılı izinleri yönetmeyle ilgili en iyi uygulamalar

Ayrıntılı izinleri işleyebilmek için uygulamanızın güncellenmesi gerektiğini determine birden fazla kapsam izninin düzgün şekilde işlenmesi için kodunuzda gerekli güncellemeleri yapmanız gerekir. Tüm uygulamalar, aşağıdaki en iyi uygulamalara uymalıdır:

1. Google API Hizmetleri: Kullanıcı Verileri Politikası'nı inceleyin ve bunlara uyduğunuzdan emin olun.
2. Bir görev için gerekli olan belirli kapsamları isteyin. Yalnızca ihtiyacınız olan kapsamları istediğiniz Google OAuth 2.0 politikasına uymalısınız. Uygulamanızın temel işlevi için gerekli olmadığı sürece oturum açarken birden fazla kapsam istemekten kaçınmalısınız. Birden fazla kapsamı birlikte paketlemek, özellikle uygulamanızın özelliklerine aşina olmayan ilk kullanıcılar için bu izinlere olan ihtiyacı anlamalarını zorlaştırabilir. Bu durum, alarmların çalmasına ve kullanıcıların uygulamanızla daha fazla etkileşimde bulunmasını engelleyebilir.
3. Yetkilendirme isteği sormadan önce kullanıcılara gerekçe sağlayın. Uygulamanızın istenen izne neden ihtiyaç duyduğunu, kullanıcı verileriyle ne yapacağınızı ve kullanıcının isteğin onaylanmasından nasıl yararlanacağını net bir şekilde açıklayın. Araştırmamız, bu açıklamaların kullanıcıların güvenini ve etkileşimini artırdığını göstermektedir.
4. Uygulamanız birden fazla erişim jetonu yönetmek zorunda kalmamak için kapsam istediğinde, artımlı yetkilendirme kullanın.
5. Kullanıcıların hangi kapsamlara izin verdiğini kontrol edin. Kullanıcılar bir seferde birden çok kapsam isteğinde bulunurken, uygulamanızın isteklerindeki tüm kapsamları vermeyebilir. Uygulamanız her zaman kullanıcı tarafından hangi kapsamların verildiğini kontrol etmeli ve ilgili özellikleri devre dışı bırakarak kapsam reddetme işlemlerini gerçekleştirmelidir. Birden fazla kapsam için izni işleme ile ilgili Google OAuth 2.0 politikalarına uyun ve yalnızca kullanıcının, kapsamı gerektiren belirli özelliği kullanma niyetini açıkça belirttiğinde tekrar izin vermesini isteyin.

Ayrıntılı izinleri işlemek için uygulamanızı güncelleyin

Android uygulamaları

Google OAuth 2.0 ile etkileşim kurmak için kullandığınız SDK'ların belgelerine bakmanız ve uygulamanızı, en iyi uygulamalara dayalı ayrıntılı izinleri işleyecek şekilde güncellemeniz gerekir.

Google OAuth 2.0 ile etkileşimde bulunmak için Play Hizmetleri'ndeki auth.api.signin SDK'sını kullanıyorsanız gereken en küçük kapsam grubunu istemek için requestPermissions işlevini, ayrıntılı izinler istediğinde kullanıcının verdiği kapsamları kontrol etmek için hasPermissions işlevini kullanabilirsiniz.

Chrome uzantısı uygulamaları

En iyi uygulamaları temel alarak Google OAuth 2.0 ile çalışmak için Chrome Identity API'yi kullanmalısınız.

Aşağıdaki örnekte, ayrıntılı izinlerin nasıl düzgün şekilde yönetileceği gösterilmektedir.

manifest.json

Örnek manifest dosyası, Chrome uzantı uygulaması için iki oturum açma dışı kapsam bildirmektedir.

{
  "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"]
  }
}

Yanlış Yaklaşım

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

Doğru Yaklaşım

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

iOS, iPadOS ve macOS uygulamaları

Google OAuth 2.0 ile etkileşim kurmak için kullandığınız SDK'ların belgelerine bakmanız ve uygulamanızı, en iyi uygulamalara dayalı ayrıntılı izinleri işleyecek şekilde güncellemeniz gerekir.

Google OAuth 2.0 ile etkileşimde bulunmak için iOS ve macOS için Google ile Oturum Açma kitaplığını kullanıyorsanız ayrıntılı izinlerin işlenmesiyle ilgili dokümanları gözden geçirmeniz gerekir.

Web uygulamaları

Google OAuth 2.0 ile etkileşim kurmak için kullandığınız SDK'ların belgelerine bakmanız ve uygulamanızı, en iyi uygulamalara dayalı ayrıntılı izinleri işleyecek şekilde güncellemeniz gerekir.

Sunucu tarafı (çevrimdışı) erişim

Aşağıdaki kod snippet'i, iki oturum açma olmayan kapsam isteğinde bulunan bir NodeJS örneğini göstermektedir. Kullanıcılar, ayrıntılı izin kullanıcı rızası ekranını görür.

Yanlış Yaklaşım

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

Doğru Yaklaşım

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

Sunucu tabanlı uygulamalardan Google API'lerine nasıl erişeceğinizi öğrenmek için sunucu tarafı web uygulaması kılavuzunu inceleyin.

Yalnızca istemci tarafı erişim

• Google OAuth 2.0 ile etkileşim kurmak amacıyla Google Kimlik Hizmetleri JavaScript kitaplığını kullanan uygulamalar için ayrıntılı izinlerin işlenmesiyle ilgili bu belgeleri incelemeniz gerekir.
• JavaScript kullanarak Google OAuth 2.0 yetkilendirme uç noktalarına doğrudan çağrı yapan uygulamalar için ayrıntılı izinlerin işlenmesiyle ilgili bu belgeleri incelemelisiniz.

Güncellenen uygulamanızı ayrıntılı izinleri işleme konusunda test etme

1. Kullanıcıların izin isteklerine yanıt verebileceği tüm durumları ve uygulamanızın beklenen davranışını ana hatlarıyla belirtin. Örneğin, kullanıcı istenen üç kapsamdan yalnızca ikisini yetkilendiriyorsa uygulamanız buna uygun davranmalıdır.
2. Ayrıntılı izin etkinken uygulamanızı test edin. Ayrıntılı izinleri etkinleştirmenin iki yolu vardır:
   1. Uygulamanızın OAuth 2.0 izin ekranlarını kontrol ederek uygulamanız için ayrıntılı izinlerin zaten etkinleştirilip etkinleştirilmediğini kontrol edin. Ayrıca, ayrıntılı izinler her zaman etkinleştirildiğinden, test amacıyla Google Cloud Console üzerinden yeni bir Web, Android veya iOS Google OAuth 2.0 istemci kimliği de oluşturabilirsiniz.
   2. Google OAuth yetkilendirme uç noktalarını çağırırken enable_granular_consent parametresini true olarak ayarlayın. Bazı SDK'lar bu parametreyi açık bir şekilde destekler. Diğerleri için bu parametreyi ve değerini manuel olarak nasıl ekleyebileceğinizi görmek üzere belgelere göz atın. Uygulamanız, parametrenin eklenmesini desteklemiyorsa yalnızca önceki bölümde belirtildiği gibi test amacıyla Google Cloud Console üzerinden yeni bir Web, Android veya iOS Google OAuth 2.0 istemci kimliği oluşturabilirsiniz.