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 veya 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ımak üzere tasarlanmıştı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ı iç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.
Kullanıcı rızası yönetiminin işleyişi
Uygulamanızın tasarımı ve kullanıcı deneyimi, Google'ın OAuth 2.0 Politikaları kapsamlı bir şekilde incelendikten sonra uygulanmalıdır. Bu politikalar; birden fazla kapsamla çalışma, kullanıcı rızasının ne zaman ve nasıl ele 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 istenen tüm kapsamları veya 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
XMLHttpRequestkullanılan tek sayfalık bir Ajax uygulaması. - Birden çok web sayfası. Kaynaklar ayrılır ve sayfa bazında 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şlevine birden fazla çağrı yaparak ve OverridableTokenClientConfig nesnesinin scope parametresini kullanarak uygulamanıza artımlı yetkilendirme desteği ekleyin. Bu sayede, gerekli olduğu anda ve yalnızca gerektiğinde tek tek kapsamlar 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.
| Ajax uygulaması |
|---|
Sayfa yüklemede jeton istemcisini başlatın:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Okunacak dokümanlarSon dokümanları göster
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Yaklaşan etkinliklerTakvim bilgilerini göster
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
Fotoğraf bandı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ün gerektirdiği 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 karmaşıklık ve kullanıcı izni almak ile erişim jetonu almak için birden fazla çağrı yapma ihtiyacı azaltılır.
| Çok sayfalı uygulama | ||||||||
|---|---|---|---|---|---|---|---|---|
|
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ı kapsamlarına göre net bir şekilde ayırmak için ayrı web sayfaları kullanılır. Gerçek hayattaki durumlarda, 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, önce sayfa yükleme sırasında veya daha sonra bir düğmeye basma gibi kullanıcı hareketiyle requestAccessToken() çağrısı tetiklenerek yeni bir jeton alınır.
Google API'leriyle REST ve CORS'u 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();
Google API'leri, varsayılan olarak CORS'u destekler. XMLHttpRequest veya fetch isteğinde erişim jetonu bulunması, GET veya POST'tan önce bir OPTIONS isteği olan CORS ön kontrolünü tetikler.
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 kullanım ömrüne sahiptir. Erişim jetonunun süresi kullanıcının oturumu sona ermeden önce dolarsa bir düğmeye basma gibi kullanıcı tarafından tetiklenen bir etkinlikten requestAccessToken() işlevini çağırarak yeni bir jeton alın.
İzni iptal etmek için erişim jetonu kullanma
Uygulamanıza verilen tüm kapsamlar için kullanıcı iznini ve 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);
});