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 özellik, 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ılı bir şekilde 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ı isteyen bir üretkenlik uygulaması geliştirdiğinizi düşünün. Kullanıcılarınız uygulamanızı yalnızca Google Takvim için kullanmak isteyebilir ancak Gmail için kullanmak istemeyebilir. Ayrıntılı OAuth izinleri sayesinde kullanıcılar, yalnızca Google Takvim'e izin vermeyi seçebilir ancak Gmail'e izin vermeyebilir. Kullanıcıların belirli verilere erişim izni vermesine olanak tanıyarak veri maruziyetini en aza indirir, güveni artırır ve kullanıcılara dijital yaşamları üzerinde gizliliğe öncelik veren bir kontrol imkanı sunar. Uygulamanızı bu tür senaryoları işleyecek şekilde tasarlamanız önemlidir.

Birden fazla oturum açma kapsamı dışı istekte bulunulduğunda

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ına yönlendirilir. 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 onay ekranı gösterilir. 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 tamamını ve bir Google Drive 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ı izinler izin 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ı izin onay 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 onay ekranı örneği verilmiştir:

Yalnızca oturum açma kapsamları (email, profile ve openid) isteyen uygulamalar için ayrıntılı izin 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ı (bir, iki veya üç kapsamın tamamı) isterse ayrıntılı izin onay ekranı geçerli olmaz.

Yalnızca bir oturum açma dışı kapsam isteyen uygulamalar için ayrıntılı izin onay ekranı geçerli değildir. Diğer bir deyişle, kullanıcılar isteğin tamamını onaylar veya reddeder ve izin ekranında onay kutusu yoktur. Aşağıdaki tabloda, ayrıntılı izinler için kullanıcı rızası alma 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 ayrıntılı bir şekilde inceleyin. Kullanıcılara sunulan ayrıntılı izin onay ekranlarını etkinleştirirken birden fazla kapsam isteyenlere dikkat edin. Bu gibi durumlarda, kodunuzun yalnızca bazı kapsamları yetkilendiren kullanıcıları 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 onay 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

Kullanıcılardan izin istemek için Google OAuth yetkilendirme uç noktalarına çağrı yaptığınız uygulama kodu bölümlerini inceleyin. Google API istemci kitaplıklarından birini kullanıyorsanız uygulamanızın istediği kapsamları genellikle istemci başlatma adımlarında bulabilirsiniz. Bazı örnekler aşağıdaki bölümde gösterilmektedir. Uygulamanızın etkilenip etkilenmediğini belirlemek için Google OAuth 2.0'ı işlemek üzere uygulamanızın kullandığı SDK'ların belgelerine başvurmalı ve aşağıdaki örneklerde gösterilen yönergeleri referans olarak kullanmalısınız.

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ı inceleme

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

Bu değerler, ayrıntılı izinler için izin ekranının gösterilmesine neden olur.

• scope parametresi, oturum açma kapsamları ve oturum açma kapsamı olmayanlar 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ı ve bir oturum açma kapsamı içermez:

  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 kapsamı içermiyor.

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

Uygulamanızın ayrıntılı izinleri işlemek için güncellenmesi gerektiğine karar verirseniz birden fazla kapsam için izni düzgün şekilde işlemek üzere kodunuzda gerekli güncellemeleri yapmanız gerekir. Tüm uygulamalar aşağıdaki en iyi uygulamalara uygun olmalıdır:

1. Google API Hizmetleri: Kullanıcı Verileri Politikası'nı inceleyin ve bu politikalara uyduğunuzdan emin olun.
2. Bir görev için gereken belirli kapsamları isteyin. Google OAuth 2.0 politikasına uymanız ve yalnızca ihtiyacınız olan kapsamları istemeniz 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 özelliklerine aşina olmayan ilk kez kullananlar için birkaç kapsamı bir araya getirmek, bu izinlerin neden gerekli olduğunu anlamalarını zorlaştırabilir. Bu durum, alarm verilmesine ve kullanıcıların uygulamanızla daha fazla etkileşim kurmaktan vazgeçmesine neden olabilir.
3. Yetkilendirme isteğinde bulunmadan önce kullanıcılara gerekçeyi bildirin. Uygulamanızın neden istenen izne ihtiyacı olduğunu, kullanıcı verileriyle ne yapacağınızı ve kullanıcının isteği onaylamaktan nasıl fayda sağlayacağını net bir şekilde açıklayın. Araştırmamı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ı yetkilendirmeyi kullanın.
5. Kullanıcıların hangi kapsamları verdiğini kontrol edin. Kullanıcılar, tek seferde birden çok kapsam isteğinde bulunurken uygulamanızın istediği tüm kapsamları vermeyebilir. Uygulamanız her zaman kullanıcının hangi kapsamları verdiğini kontrol etmeli ve kapsamların reddedilmesi durumunda ilgili özellikleri devre dışı bırakarak bu durumu ele almalıdır. Birden fazla kapsam için izin işleme konusunda Google OAuth 2.0 politikalarına uyun ve kullanıcıdan yalnızca kapsam gerektiren belirli bir özelliği kullanma niyetini açıkça belirttikten sonra tekrar izin isteyin.

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

Android uygulamaları

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

Google OAuth 2.0 ile etkileşim kurmak için Play Hizmetleri'nden 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 ise hasPermissions işlevini kullanabilirsiniz.

Chrome uzantısı uygulamaları

Google OAuth 2.0 ile en iyi uygulamalara göre ç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 manifest dosyası, Chrome uzantısı uygulaması için iki oturum açma dışı kapsam bildiriyor.

{
  "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 göz atmanız ve uygulamanızı en iyi uygulamalara göre ayrıntılı izinleri işleyecek şekilde güncellemeniz gerekir.

Google OAuth 2.0 ile etkileşim kurmak için iOS ve macOS için Google ile Oturum Açma kitaplığını kullanıyorsanız ayrıntılı izinlerin işlenmesiyle ilgili belgeleri incelemeniz gerekir.

Web uygulamaları

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

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

Aşağıdaki kod snippet'inde, NodeJS örneğinin oturum açma kapsamı dışındaki iki kapsamı istediği gösterilmektedir. Kullanıcılar ayrıntılı izin 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şileceği hakkında sunucu tarafı web uygulaması kılavuzunu inceleyin.

Yalnızca istemci tarafı erişimi

• Google OAuth 2.0 ile etkileşim kurmak için Google Identity Services JavaScript kitaplığını kullanan uygulamalarda ayrıntılı izinlerin nasıl işleneceğiyle ilgili bu dokümanı incelemeniz gerekir.
• Google OAuth 2.0 yetkilendirme uç noktalarına doğrudan JavaScript kullanarak çağrı yapan uygulamalar için ayrıntılı izinlerin işlenmesiyle ilgili bu dokümanı incelemeniz gerekir.

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 açıklayın. Örneğin, kullanıcı istenen üç kapsamdan yalnızca ikisini yetkilendirirse uygulamanız buna göre davranmalıdır.
2. Ayrıntılı izin etkinleştirilmişken 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ızda ayrıntılı izinlerin etkin olup olmadığını görün. Test amacıyla Google Cloud Console üzerinden yeni bir Web, Android veya iOS Google OAuth 2.0 istemci kimliği de oluşturabilirsiniz. Bu istemci kimlikleri için her zaman ayrıntılı izin etkinleştirilir.
   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 dokümanları inceleyin. Uygulamanız parametre eklemeyi desteklemiyorsa 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 yapılan testlerde yeni ayrıntılı izin ekranı beklendiği gibi gösterilmeyebilir.