Jeton modelini kullanma

google.accounts.oauth2 JavaScript kitaplığı, kullanıcı izni istemenize ve kullanıcı verileriyle çalışmak için erişim jetonu almanıza yardımcı olur. OAuth 2.0 örtülü izin akışına dayalıdır ve Google API'lerini REST ve CORS kullanarak doğrudan çağırmanıza ya da daha karmaşık API'lerimize basit ve esnek erişim için Google API'leri JavaScript istemci kitaplığımızı (gapi.client olarak da bilinir) kullanmanıza olanak tanır.

Sitenizdeki kullanıcılar, tarayıcıdan korumalı kullanıcı verilerine erişmeden önce Google'ın web tabanlı hesap seçici, oturum açma ve izin işlemlerini tetikler. Son olarak Google'ın OAuth sunucuları, web uygulamanıza bir erişim jetonu verip döndürür.

Jeton tabanlı yetkilendirme modelinde, arka uç sunucunuzda kullanıcı başına yenileme jetonları depolamanız gerekmez.

Eski İstemci Tarafı Web Uygulamaları İçin OAuth 2.0 kılavuzunda ele alınan teknikler yerine burada açıklanan yaklaşımı uygulamanız önerilir.

Ön koşullar

OAuth izin ekranınızı yapılandırmak, istemci kimliği almak ve istemci kitaplığını yüklemek için Kurulum bölümünde açıklanan adımları uygulayın.

Jeton istemcisini başlatma

Web uygulamanızın istemci kimliğiyle yeni bir jeton istemcisini başlatmak için initTokenClient() işlevini çağırın. Kullanıcının erişmesi gereken bir veya daha fazla kapsam listesini eklemeniz gerekir:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (response) => {
    ...
  },
});

OAuth 2.0 jeton akışını tetikleme

Jeton kullanıcı deneyimi akışını tetiklemek ve erişim jetonu almak için requestAccessToken() yöntemini kullanın. Google, kullanıcıya şunları yapmasını ister:

  • Çocuğunuzun hesabını seçin.
  • Henüz oturum açmadıysanız Google Hesabı'nda oturum açın.
  • Web uygulamanızın istenen her kapsamda erişim izni vermelisiniz.

Kullanıcı hareketi, jeton akışını tetikler: <button onclick="client.requestAccessToken();">Authorize me</button>

Ardından Google, geri çağırma işleyicinize erişim jetonu ve kullanıcının erişim izni verdiği kapsamların listesini içeren bir TokenResponse veya bir hata döndürür.

Kullanıcılar hesap seçiciyi veya oturum açma pencerelerini kapatabilir. Bu durumda geri çağırma işleviniz çağrılmaz.

Uygulamanızın tasarımı ve kullanıcı deneyimi, Google'ın OAuth 2.0 Politikaları'nın kapsamlı bir şekilde incelenmesinden sonra uygulanmalıdır. Bu politikalar; birden fazla kapsamla çalışma, kullanıcı rızasının ne zaman ve nasıl alınacağı gibi konuları kapsar.

Artımlı yetkilendirme, kaynaklara erişim isteğinde bulunmak için kullanılan bir politika ve uygulama tasarımı metodolojisidir. Bu metodolojide, kapsamlar kullanılarak kaynaklara yalnızca gerektiğinde erişim isteğinde bulunulur. Kaynaklara erişim isteğinde bulunmak için önceden ve tek seferde istekte bulunulmaz. Kullanıcılar, uygulamanızın istediği kaynakların paylaşımını onaylayabilir veya reddedebilir. Bu işleme ayrıntılı izinler adı verilir.

Bu süreçte Google, kullanıcı izni ister. İstenen her kapsamı ayrı ayrı listeler. Kullanıcılar, uygulamanızla paylaşılacak kaynakları seçer. Son olarak Google, erişim jetonu ve kullanıcı tarafından onaylanan kapsamları döndürmek için geri çağırma işlevinizi çağırır. Uygulamanız daha sonra ayrıntılı izinlerle mümkün olan çeşitli farklı sonuçları güvenli bir şekilde işler.

Ancak istisnalar bulunmaktadır. Alan genelinde yetki devri olan Google Workspace Enterprise uygulamaları veya Güvenilir olarak işaretlenen uygulamalar, ayrıntılı izinler kullanıcı rızası ekranını atlar. Bu uygulamalarda kullanıcılar ayrıntılı izin kullanıcı rızası ekranını görmez. Bunun yerine, uygulamanız ya istenen tüm kapsamları ya da hiçbirini almaz.

Daha ayrıntılı bilgi için Ayrıntılı izinleri yönetme başlıklı makaleyi inceleyin.

Aşamalı yetkilendirme

Web uygulamaları için aşağıdaki iki üst düzey senaryoda, aşağıdakiler kullanılarak artımlı yetkilendirme gösterilmektedir:

  • Genellikle kaynaklara dinamik erişim için XMLHttpRequest kullanılan tek sayfalık bir Ajax uygulaması.
  • Birden çok web sayfası, kaynaklar sayfa bazında ayrılır ve yönetilir.

Bu iki senaryo, tasarım hususlarını ve metodolojilerini göstermek için sunulmuştur ancak uygulamanıza izin işlevini nasıl ekleyeceğinizle ilgili kapsamlı öneriler sunmayı amaçlamaz. Gerçek dünyadaki uygulamalar, bu tekniklerin bir varyasyonunu veya kombinasyonunu kullanabilir.

Ajax

requestAccessToken() için birden fazla çağrı yaparak ve OverridableTokenClientConfig nesnesinin scope parametresini kullanarak uygulamanıza artımlı yetkilendirme desteği ekleyin. Bu sayede, kapsamları gerektiğinde ve yalnızca gerekli olduğunda tek tek isteyebilirsiniz. Bu örnekte kaynaklar yalnızca kullanıcı hareketiyle daraltılmış bir içerik bölümü genişletildikten sonra istenir ve görünür hale gelir.

Ajax uygulaması
Sayfa yüklemede jeton istemcisini başlatın: 
        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
Kullanıcı hareketleriyle izin isteyin ve erişim jetonları alın, açmak için `+` işaretini tıklayın:

Okunacak dokümanlar

Son dokümanları göster

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );

Yaklaşan etkinlikler

Takvim bilgilerini göster

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );

Fotoğrafları görüntüleme

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );

requestAccessToken'a yapılan her çağrı, kullanıcı izni anını tetikler. Uygulamanız yalnızca kullanıcının genişletmeyi seçtiği bölüm için gereken kaynaklara erişebilir. Böylece, kaynak paylaşımı kullanıcı tercihiyle sınırlanır.

Birden fazla web sayfası

Artımlı yetkilendirme için tasarım yaparken, yalnızca bir sayfayı yüklemek için gereken kapsamları istemek üzere birden fazla sayfa kullanılır. Bu sayede, kullanıcı izni almak ve erişim jetonu almak için birden fazla çağrı yapma ihtiyacı ve karmaşıklık azaltılır.

Çok sayfalı uygulama
Web sayfası Kod
1. Sayfa. Okunacak dokümanlar 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
2. Sayfa. Yaklaşan etkinlikler 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
Sayfa 3. Fotoğraf bandı 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();

Her sayfa, gerekli kapsamı ister ve yükleme sırasında initTokenClient() ile requestAccessToken()'yi çağırarak erişim jetonu alır. Bu senaryoda, kullanıcı işlevselliğini ve kaynaklarını kapsamına göre net bir şekilde ayırmak için ayrı web sayfaları kullanılır. Gerçek hayattaki bir durumda, tek tek sayfalar birden fazla ilgili kapsam isteyebilir.

Ayrıntılı izinler

Ayrıntılı izinler tüm senaryolarda aynı şekilde işlenir. requestAccessToken() geri çağırma işlevinizi çağırdıktan ve bir erişim jetonu döndürüldükten sonra, kullanıcının hasGrantedAllScopes() veya hasGrantedAnyScope() kullanarak istenen kapsamları onayladığını kontrol edin. Örneğin:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
          https://www.googleapis.com/auth/documents.readonly \
          https://www.googleapis.com/auth/photoslibrary.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
          'https://www.googleapis.com/auth/photoslibrary.readonly')) {
        // Look at pictures
        ...
      }
      if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
          'https://www.googleapis.com/auth/calendar.readonly',
          'https://www.googleapis.com/auth/documents.readonly')) {
        // Meeting planning and review documents
        ...
      }
    }
  },
});

Önceki oturumlardan veya isteklerden daha önce kabul edilen tüm hibeler de yanıta dahil edilir. Kullanıcı izni kaydı, kullanıcı ve istemci kimliği başına tutulur ve initTokenClient() veya requestAccessToken() için yapılan birden fazla çağrıda kalıcı olur. Varsayılan olarak, kullanıcı izni yalnızca kullanıcı web sitenizi ilk kez ziyaret edip yeni bir kapsam istediğinde gereklidir. Ancak, Token Client yapılandırma nesnelerinde prompt=consent kullanılarak her sayfa yüklemesinde istenebilir.

Jetonlarla çalışma

Jeton modelinde, erişim jetonu işletim sistemi veya tarayıcı tarafından depolanmaz. Bunun yerine, sayfa yükleme sırasında ilk olarak yeni bir jeton alınır ya da daha sonra bir düğmeye basma gibi kullanıcı hareketiyle requestAccessToken() çağrısı tetiklenerek jeton alınır.

Google API'leriyle REST ve CORS kullanma

Erişim jetonu, REST ve CORS kullanılarak Google API'lerine kimliği doğrulanmış istekler göndermek için kullanılabilir. Bu sayede kullanıcılar oturum açabilir, izin verebilir, Google erişim jetonu verebilir ve siteniz kullanıcının verileriyle çalışabilir.

Bu örnekte, tokenRequest() tarafından döndürülen erişim jetonunu kullanarak oturum açmış kullanıcıların yaklaşan takvim etkinliklerini görüntüleyin:

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();

Daha fazla bilgi için Google API'lerine erişmek için CORS nasıl kullanılır? başlıklı makaleyi inceleyin.

Sonraki bölümde, daha karmaşık API'lerle kolayca entegrasyon yapma konusu ele alınmaktadır.

Google API'leri JavaScript kitaplığıyla çalışma

Jeton istemcisi, JavaScript için Google API İstemci Kitaplığı ile çalışır. Aşağıdaki kod snippet'ine bakın.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      gapi.client.setApiKey('YOUR_API_KEY');
      gapi.client.load('calendar', 'v3', listUpcomingEvents);
    }
  },
});

function listUpcomingEvents() {
  gapi.client.calendar.events.list(...);
}

Jetonun son kullanma tarihi

Erişim jetonları, tasarım gereği kısa bir geçerlilik süresine sahiptir. Erişim jetonunun süresi kullanıcının oturumu sona ermeden önce dolarsa requestAccessToken() işlevini çağırarak yeni bir jeton alın. Bu işlev, düğmeye basma gibi kullanıcı tarafından tetiklenen bir etkinlikten çağrılmalıdır.

Kullanıcı iznini ve uygulamanıza verilen tüm kapsamlar için kaynaklara erişimi kaldırmak üzere google.accounts.oauth2.revoke yöntemini çağırın. Bu izni iptal etmek için geçerli bir erişim jetonu gerekir:

google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
    console.log(done);
    console.log(done.successful);
    console.log(done.error);
    console.log(done.error_description);
  });