google.accounts.oauth2 JavaScript kitaplığı, kullanıcı verilerini kullanmak için kullanıcı izni istemenize ve erişim jetonu almanıza yardımcı olur. OAuth 2.0 örtülü izin akışına dayanır ve Google API'lerini doğrudan REST ve CORS kullanarak çağırmanıza veya daha karmaşık API'lerimize basit ve esnek bir şekilde erişmek için JavaScript için Google API'leri istemci kitaplığımızı (gapi.client olarak da bilinir) kullanmanıza olanak tanıyacak şekilde tasarlanmıştır.
Sitenizdeki kullanıcılar, tarayıcıdan korunan kullanıcı verilerine erişmeden önce Google'ın web tabanlı hesap seçicisini, oturum açma ve izin verme işlemlerini tetikler. Son olarak Google'ın OAuth sunucuları, web uygulamanıza bir erişim jetonu gönderir ve döndürür.
Jeton tabanlı yetkilendirme modelinde, arka uç sunucunuzda kullanıcı başına yenileme jetonları depolamaya gerek yoktur.
Eski İstemci Tarafı Web Uygulamaları için OAuth 2.0 kılavuzunda açıklanan teknikler yerine burada açıklanan yaklaşımı uygulamanız önerilir.
Kurulum
Google API istemci kimliğinizi edinme kılavuzunda açıklanan adımları uygulayarak bir istemci kimliği bulun veya oluşturun. Ardından, sitenizde Google API'lerini çağıracak sayfalara istemci kitaplığını ekleyin. Son olarak, jeton istemcisini başlatın. Bu işlem genellikle istemci kitaplığının onload işleyicisinde yapılır.
Jeton istemcisini başlatma
Web uygulamanızın istemci kimliğiyle yeni bir jeton istemcisi başlatmak için initTokenClient() işlevini çağırın. İsteğe bağlı olarak, kullanıcının erişmesi gereken bir veya daha fazla kapsamın listesini ekleyebilirsiniz:
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ıdan şunları yapmasını ister:
- Hesabını seçin,
- Henüz oturum açmadıysanız Google Hesabınızda oturum açın.
- Web uygulamanızın istenen her kapsama erişmesi için izin verin.
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 döndürür veya 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.
İzinleri yönetme
Uygulamanızın tasarımı ve kullanıcı deneyimi, yalnızca Google'ın OAuth 2.0 Politikaları'nın ayrıntılı bir incelemesinden sonra uygulanmalıdır. Bu politikalar, birden fazla kapsamla çalışma, kullanıcı rızasını ne zaman ve nasıl işleyeceğiniz gibi konuları kapsar.
Artımlı yetkilendirme, kaynaklara erişim isteğinde bulunmak için kullanılan bir politika ve uygulama tasarımı metodolojisidir. Bu yöntemde, kapsamlar kullanılarak kaynaklara erişim önceden ve tek seferde değil, yalnızca gerektiğinde istenir. Kullanıcılar, uygulamanız tarafından istenen kaynakların tek tek paylaşılmasını onaylayabilir veya reddedebilir. Buna ayrıntılı izinler denir.
Bu süreçte Google, istenen her kapsamı tek tek listeleyerek kullanıcıdan izin ister. Kullanıcılar, uygulamanızla paylaşılacak kaynakları seçer ve son olarak Google, erişim jetonu ve kullanıcı onaylı kapsamları döndürmek için geri çağırma işlevinizi çağırır. Ardından uygulamanız, ayrıntılı izinlerle mümkün olan çeşitli farklı sonuçları güvenli bir şekilde yönetir.
Ancak istisnalar da vardır. Alan genelinde yetki devri olan Google Workspace Enterprise uygulamaları veya Güvenilir olarak işaretlenmiş uygulamalar ayrıntılı izinler kullanıcı rızası ekranını atlar. Bu uygulamalarda kullanıcılar ayrıntılı izin rıza ekranını görmez. Bunun yerine, uygulamanız istenen tüm kapsamları veya hiçbirini alır.
Daha ayrıntılı bilgi için Ayrıntılı izinleri yönetme başlıklı makaleyi inceleyin.
Artımlı 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
XMLHttpRequestkullanan tek sayfalık bir Ajax uygulaması. - Birden çok web sayfası, kaynaklar sayfa başına ayrılır ve yönetilir.
Bu iki senaryo, tasarımla ilgili hususları ve metodolojileri açıklamak için sunulmuştur ancak uygulamanızda izinleri nasıl oluşturacağınızla ilgili kapsamlı öneriler olarak tasarlanmamıştır. Gerçek uygulamalarda bu tekniklerin bir varyasyonu veya kombinasyonu kullanılabilir.
Ajax
requestAccessToken() adresine birden fazla çağrı yaparak ve OverridableTokenClientConfig nesnesinin scope parametresini kullanarak uygulamanıza artımlı yetkilendirme desteği ekleyin. Böylece, ihtiyaç duyulduğunda ve yalnızca gerektiğinde ayrı kapsamlar isteyebilirsiniz. Bu örnekte kaynaklar yalnızca kullanıcı hareketiyle daraltılmış bir içerik bölümünün genişletilmesinden sonra istenir ve görünür olur.
| Ajax uygulaması |
|---|
Sayfa yüklenirken 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österme
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
Fotoğraf bandıFotoğrafları gösterme
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
})
);
|
requestAccessToken çağrısı her yapıldığında kullanıcı rızası anı tetiklenir. Uygulamanız yalnızca kullanıcının genişletmeyi seçtiği bölüm tarafından gerekli olan kaynaklara erişebilir. Böylece, kaynak paylaşımı kullanıcının seçimiyle sınırlandırılır.
Birden fazla web sayfası
Artımlı yetkilendirme için tasarım yapılırken 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 ve 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() ve requestAccessToken() çağrılarını yaparak bir erişim jetonu alır. Bu senaryoda, kullanıcı işlevlerini ve kaynaklarını kapsama göre net bir şekilde ayırmak için ayrı web sayfaları kullanılır. Gerçek dünyada, bağımsız 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 oturumlarda veya isteklerde daha önce kabul edilen tüm bağışlar da yanıta dahil edilir. Kullanıcı izninin kaydı, kullanıcı ve istemci kimliği başına tutulur ve initTokenClient() veya requestAccessToken()'a yapılan birden fazla çağrıda devam eder. Varsayılan olarak, kullanıcı izni yalnızca kullanıcı web sitenizi ilk kez ziyaret edip yeni bir kapsam istediğinde gereklidir ancak jeton istemcisi yapılandırma nesnelerinde prompt=consent kullanılarak her sayfa yüklendiğinde istenebilir.
Jetonlarla çalışma
Jeton modelinde, erişim jetonu işletim sistemi veya tarayıcı tarafından depolanmaz. Bunun yerine, önce sayfa yükleme zamanında veya daha sonra düğmeye basma gibi bir kullanıcı hareketi aracılığıyla requestAccessToken() çağrısı tetiklenerek yeni bir jeton elde edilir.
Google API'leriyle REST ve CORS'u kullanma
Erişim jetonları, 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 yayınlayabilir 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ını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'u kullanma başlıklı makaleyi inceleyin.
Sonraki bölümde, daha karmaşık API'lerle nasıl kolayca entegrasyon yapılacağı 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ının geçerlilik süresi, tasarım gereği kısadır. Erişim jetonunun süresi, kullanıcının oturumu sona ermeden önce dolarsa düğme basma gibi kullanıcı tarafından yönlendirilen bir etkinlikten requestAccessToken()'ü ç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);
});