Ayrıntılı izinleri yönetme

Genel Bakış

Ayrıntılı izinler sayesinde tüketiciler, her uygulamayla paylaşmayı seçtikleri hesap verileri üzerinde daha ayrıntılı kontrol sahibi olur. Bu izinler, daha fazla kontrol, şeffaflık ve güvenlik sağlayarak hem kullanıcılara hem de geliştiricilere fayda sağlar. 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ı olacaktır.

Ayrıntılı izin nedir?

Hem e-posta hem de takvim kapsamlarını isteyen bir üretkenlik uygulaması geliştirdiğinizi varsayalım. Kullanıcılarınız uygulamanızı Gmail için değil, yalnızca Google Takvim için kullanmak isteyebilir. Ayrıntılı OAuth izinleri sayesinde kullanıcılar, Gmail'e değil yalnızca Google Takvim'e izin vermeyi seçebilir. Kullanıcıların belirli verilere erişim izni vermesini sağlayarak veri ifşasını en aza indirir, güveni artırır ve kullanıcılara dijital yaşamları üzerinde gizlilik öncelikli kontrol imkanı sunar. Uygulamanızı bu tür senaryoları işleyecek şekilde tasarlamanız önemlidir.

Oturum açma dışı birden fazla 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ür. Kullanıcılar temel kimlik bilgilerini (ad, e-posta adresi ve profil fotoğrafı) paylaşmayı kabul ettikten sonra oturum açma dışı kapsamlar için ayrıntılı izin rıza ekranını görür. Bu durumda uygulama, kullanıcılar tarafından hangi kapsamların verildiğini kontrol etmeli ve kullanıcıların istenen tüm kapsamları verdiğini varsaymamalıdır. Aşağıdaki örnekte web uygulaması, üç oturum açma kapsamının tümünü ve Google Drive'ın oturum açma dışı kapsamını istiyor. Kullanıcılar, oturum açma kapsamlarına izin verdikten sonra Google Drive izni için ayrıntılı izin rızası 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ı kullanıcı rızası ekranı gösterilir. Kullanıcılar, uygulamayla paylaşmak için hangi izinleri onaylamak istediklerini seçebilir. Aşağıda, kullanıcının Gmail mesajlarına ve Google Takvim verilerine erişim isteyen ayrıntılı izin kullanıcı rızası ekranı örneği verilmiştir:

Yalnızca oturum açma kapsamları (email, profile ve openid) isteyen uygulamalar için ayrıntılı izinler kullanıcı rızası 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 üçü birden) isterse ayrıntılı izin kullanıcı rızası ekranı geçerli değil.

Yalnızca bir Oturum Açma dışı kapsam isteyen uygulamalar için ayrıntılı izin kullanıcı rızası ekranı geçerli değildir. Diğer bir deyişle, kullanıcılar isteğin tamamını onaylar veya reddeder. Kullanıcı rızası ekranında onay kutusu yoktur. Aşağıdaki tabloda, ayrıntılı izinler için kullanıcı rızası ekranının ne zaman gösterildiği özetlenmektedir.

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

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 kullanıcı rızası ekranlarını etkinleştirdikleri için birden fazla kapsam isteyenlere dikkat edin. Bu gibi durumlarda, kodunuzun kullanıcıların yalnızca bazı kapsamlara yetki verdiği durumu 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 kullanıcı rızası ekranının gösterilmesine neden olup olmayacağını belirlemek için uygulama kodunuzu veya giden ağ çağrısını inceleyin.

Uygulama kodunuzu inceleme

Uygulama kodunuzda, kullanıcılardan izin istemek için Google OAuth yetkilendirme uç noktalarına çağrı yaptığınız bölümleri inceleyin. Google API istemci kitaplıklarından birini kullanıyorsanız uygulamanızın hangi kapsamları istediğini genellikle istemci başlatma adımlarında bulabilirsiniz. Aşağıdaki bölümde bazı örnekler gösterilmiştir. Uygulamanızın etkilenip etkilenmediğini belirlemek için uygulamanızın Google OAuth 2.0'ı işlemek üzere kullandığı SDK'ların belgelerine bakmanız gerekir. Aşağıdaki örneklerde gösterilen kılavuzu referans olarak kullanabilirsiniz.

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

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

Ağ çağrılarını inceleme yöntemi, uygulama türünüze bağlı olarak değişir.

• Web uygulaması: Chrome'da ağ etkinliğini inceleyin.
• Android: Ağ Denetleyici ile ağ trafiğini inceleme
• Chrome uygulamaları
  • Chrome uzantıları sayfasına gidin.
  • Uzantı sayfasının sağ üst köşesindeki Geliştirici modu onay kutusunu işaretleyin.
  • İzlemek istediğiniz uzantıyı seçin
  • Uzantı sayfasının Görünümleri incele bölümündeki arka plan sayfası bağlantısını tıklayın.
  • Ağ sekmesinde ağ trafiğini izleyebileceğiniz bir Geliştirici Araçları iletişim kutusu açılır.
• iOS - Instruments ile HTTP trafiğini analiz etme
• Masaüstü uygulamaları: Uygulamanın geliştirildiği işletim sistemi için kullanılabilen bir ağ yakalama aracı kullanın.

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

Bu değerler, ayrıntılı izinler kullanıcı rızası ekranının gösterilmesine neden olur.

• scope parametresi, oturum açma kapsamları ve oturum açma dışı kapsamlar içeriyor.

  Aşağıdaki örnek istek, kullanıcının Google Drive dosyalarının meta verilerini görüntülemek için üç Oturum Açma kapsamının tümünü ve bir 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, oturum açma dışı birden fazla 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 Oturum Açma dışı iki 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

Uygulamanızın ayrıntılı izinleri işlemek için güncellenmesi gerektiğini belirlerseniz birden fazla kapsam için izni doğru şekilde işlemek üzere 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 bu politikaya uyduğunuzdan emin olun.
2. Bir görev için gereken belirli kapsamları isteyin. Yalnızca ihtiyacınız olan kapsamları istemeniz gerektiğini belirten Google OAuth 2.0 politikasına uymanız gerekir. Uygulamanızın temel işlevi için gerekli olmadığı sürece oturum açma sırasında birden fazla kapsam istemekten kaçınmalısınız. Özellikle uygulamanızın özelliklerini bilmeyen ilk kez kullanan kullanıcılar için birden fazla kapsamı bir araya getirmek, bu izinlerin neden gerekli olduğunu anlamalarını zorlaştırabilir. Bu durum, kullanıcıların endişelenmesine ve uygulamanızla daha fazla etkileşim kurmaktan vazgeçmesine neden olabilir.
3. Yetkilendirme isteğinde bulunmadan önce kullanıcılara gerekçe sunun. Uygulamanızın istenen izne neden ihtiyaç duyduğunu, kullanıcının verileriyle ne yapacağınızı ve isteği onaylamanın kullanıcıya nasıl fayda sağlayacağını net bir şekilde açıklayın. Araştırmalarımız, bu açıklamaların kullanıcı güvenini ve etkileşimini artırdığını gösteriyor.
4. Uygulamanız kapsam istediğinde birden fazla erişim jetonunu yönetmek zorunda kalmamak için artımlı yetkilendirme kullanın.
5. Kullanıcıların hangi kapsamlara izin verdiğini kontrol edin. Aynı anda birden fazla kapsam istendiğinde kullanıcılar uygulamanızın istediği tüm kapsamları vermeyebilir. Uygulamanız her zaman kullanıcı tarafından hangi kapsamların verildiğini kontrol etmeli ve reddedilen kapsamları ilgili özellikleri devre dışı bırakarak işlemelidir. Birden fazla kapsam için rıza alma ile ilgili Google OAuth 2.0 politikalarına uyun ve yalnızca kullanıcı, kapsamı gerektiren belirli özelliği kullanma niyetini açıkça belirttikten sonra kullanıcıdan tekrar rıza isteyin.

Uygulamanızı ayrıntılı izinleri işleyecek şekilde güncelleme

Android uygulamaları

Google OAuth 2.0 ile etkileşimde bulunmak için kullandığınız SDK'ların belgelerini incelemeniz ve uygulamanızı, ayrıntılı izinleri en iyi uygulamalara göre 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 gerekli en küçük kapsam grubunu istemek için requestPermissions işlevini, ayrıntılı izinler istenirken kullanıcının hangi kapsamları verdiğini kontrol etmek için de hasPermissions işlevini kullanabilirsiniz.

Chrome uzantısı uygulamaları

En iyi uygulamalara göre Google OAuth 2.0 ile çalışmak için Chrome Identity API'yi kullanmanız gerekir.

Aşağıdaki örnekte, ayrıntılı izinlerin nasıl doğru şekilde işleneceği gösterilmektedir.

manifest.json

Örnek manifesto dosyası, Chrome uzantısı uygulaması için oturum açma dışı iki kapsam bildirir.

{
  "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şimde bulunmak için kullandığınız SDK'ların belgelerini incelemeniz ve uygulamanızı, ayrıntılı izinleri en iyi uygulamalara göre 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ı izinleri işlemeyle ilgili belgeleri incelemeniz gerekir.

Web uygulamaları

Google OAuth 2.0 ile etkileşimde bulunmak için kullandığınız SDK'ların belgelerini incelemeniz ve uygulamanızı, ayrıntılı izinleri en iyi uygulamalara göre işleyecek şekilde güncellemeniz gerekir.

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

Sunucu tarafı (çevrimdışı) erişim modu, aşağıdakileri yapmanızı gerektirir:

• Bir sunucu oluşturun ve yetkilendirme kodunu almak için herkese açık bir uç nokta tanımlayın.
• Google Cloud Console'un Clients (İstemciler) sayfasında herkese açık uç noktanızın yönlendirme URI'sini yapılandırın.

Aşağıdaki kod snippet'inde, oturum açma dışı iki kapsam isteyen bir NodeJS örneği gösterilmektedir. Kullanıcılar ayrıntılı 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 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);
}

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

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

Yalnızca istemci tarafı erişimi

• Google OAuth 2.0 ile etkileşimde bulunmak için Google Kimlik Hizmetleri JavaScript kitaplığını kullanan uygulamalar için ayrıntılı izinleri işlemeyle ilgili bu dokümanı incelemeniz gerekir.
• JavaScript kullanarak doğrudan Google OAuth 2.0 yetkilendirme uç noktalarına çağrı yapan uygulamalar için ayrıntılı izinleri işlemeyle ilgili bu dokümanı incelemeniz gerekir.

Güncellenmiş uygulamanızın ayrıntılı izinleri nasıl işlediğini test etme

1. Kullanıcıların izin isteklerine yanıt verebileceği tüm durumları ve uygulamanızdan beklenen davranışı özetleyin. Örneğin, kullanıcı istenen üç kapsamdan yalnızca ikisine izin verirse uygulamanız buna göre davranmalıdır.

2. Ayrıntılı izin etkinleştirilmiş olarak uygulamanızı test edin. Ayrıntılı izinleri etkinleştirmenin iki yolu vardır:

   1. Uygulamanızda ayrıntılı izinlerin etkin olup olmadığını görmek için uygulamanızın OAuth 2.0 kullanıcı rızası ekranlarını kontrol edin. Ayrıca, ayrıntılı izinler her zaman etkinleştirildiği için test amacıyla Google Cloud Console üzerinden yeni bir web, Android veya iOS Google OAuth 2.0 istemci kimliği 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ça destekler. Diğerleri için bu parametreyi ve değerini manuel olarak nasıl ekleyebileceğinizi öğrenmek üzere belgelere bakın. Uygulamanız parametre eklemeyi desteklemiyorsa önceki maddede belirtildiği gibi yalnızca test amacıyla Google Cloud Console üzerinden yeni bir web, Android veya iOS Google OAuth 2.0 istemci kimliği oluşturabilirsiniz.

3. Güncellenen uygulamanızı test ederken Workspace hesabı yerine kişisel bir Google Hesabı (@gmail.com) kullanın. Bunun nedeni, alan genelinde yetki devri olan veya Güvenilir olarak işaretlenen Workspace Enterprise uygulamalarının şu anda ayrıntılı izinlerdeki değişikliklerden etkilenmemesidir. Bu nedenle, kuruluşunuzdaki bir Workspace hesabıyla test yapıldığında yeni ayrıntılı kullanıcı rızası ekranı beklendiği gibi gösterilmeyebilir.