Bu dokümanda, bir JavaScript web uygulamasından Google API'lerine erişmek için OAuth 2.0 yetkilendirmesinin nasıl uygulanacağı açıklanmaktadır. OAuth 2.0 sayesinde kullanıcılar, bir uygulamayla belirli verileri paylaşırken kullanıcı adlarını, şifrelerini ve diğer bilgilerini gizli tutabilir. Örneğin, bir uygulama, kullanıcıların Google Drive'larında dosya depolamak için kullanıcılardan izin almak üzere OAuth 2.0'ı kullanabilir.
Bu OAuth 2.0 akışına dolaylı izin akışı denir. Yalnızca kullanıcı uygulamadayken API'lere erişen uygulamalar için tasarlanmıştır. Bu uygulamalar gizli bilgileri depolayamaz.
Bu akışta uygulamanız, uygulamanızı ve uygulamanın gerektirdiği API erişim türünü tanımlamak için sorgu parametrelerini kullanan bir Google URL'si açar. URL'yi geçerli tarayıcı penceresinde veya bir iletişim kutusunda açabilirsiniz. Kullanıcı, Google ile kimlik doğrulayabilir ve istenen izinleri verebilir. Google daha sonra kullanıcıyı uygulamanıza geri yönlendirir. Yönlendirme, uygulamanızın doğruladığı ve ardından API istekleri yapmak için kullandığı bir erişim jetonu içerir.
Google API'leri İstemci Kitaplığı ve Google Kimlik Hizmetleri
Google'a yetkili çağrılar yapmak için JavaScript için Google API'leri istemci kitaplığını kullanıyorsanız yetkilendirme akışını yönetmek için Google Kimlik Hizmetleri JavaScript kitaplığını kullanmanız gerekir. PKCE ile daha güvenli yetkilendirme kodu akışını temel alan Google Kimlik Hizmetleri kod modelini kullanmanızı önemle tavsiye ederiz.
Ön koşullar
Projeniz için API'leri etkinleştirme
Google API'lerini çağıran tüm uygulamaların, API Konsolu'nda bu API'leri etkinleştirmesi gerekir.
Projeniz için bir API'yi etkinleştirmek üzere:
- Google API Konsolu'nda API Kitaplığı'nı açın.
- İstenirse bir proje seçin veya yeni bir proje oluşturun.
- API Kitaplığı, mevcut tüm API'leri ürün ailesine ve popülerliğe göre gruplandırarak listeler. Etkinleştirmek istediğiniz API listede görünmüyorsa arama yaparak bulun veya ait olduğu ürün ailesinde Tümünü Görüntüle'yi tıklayın.
- Etkinleştirmek istediğiniz API'yi seçin, ardından Etkinleştir düğmesini tıklayın.
- İstenirse faturalandırmayı etkinleştirin.
- İstenirse API'nin Hizmet Şartları'nı okuyup kabul edin.
Yetkilendirme kimlik bilgileri oluşturma
Google API'lerine erişmek için OAuth 2.0 kullanan tüm uygulamaların, uygulamayı Google'ın OAuth 2.0 sunucusuna tanımlayan yetkilendirme kimlik bilgilerine sahip olması gerekir. Aşağıdaki adımlarda, projeniz için nasıl kimlik bilgileri oluşturacağınız açıklanmaktadır. Uygulamalarınız, bu kimlik bilgilerini kullanarak ilgili proje için etkinleştirdiğiniz API'lere erişebilir.
- Müşteriler sayfasına gidin.
- Create Client'ı (İstemci Oluştur) tıklayın.
- Web uygulaması uygulama türünü seçin.
- Formu doldurun. Yetkili Google API istekleri göndermek için JavaScript kullanan uygulamaların, yetkili JavaScript kaynaklarını belirtmesi gerekir. Kaynaklar, uygulamanızın OAuth 2.0 sunucusuna istek gönderebileceği alanları tanımlar. Bu kaynaklar Google'ın doğrulama kurallarına uymalıdır.
Erişim kapsamlarını belirleme
Kapsamlar, uygulamanızın yalnızca ihtiyaç duyduğu kaynaklara erişim istemesini sağlarken kullanıcıların da uygulamanıza verdikleri erişim miktarını kontrol etmelerine olanak tanır. Bu nedenle, istenen kapsam sayısı ile kullanıcı rızası alma olasılığı arasında ters bir ilişki olabilir.
OAuth 2.0 yetkilendirmesini uygulamaya başlamadan önce uygulamanızın erişim izni gerektirecek kapsamları belirlemenizi öneririz.
OAuth 2.0 API Kapsamları dokümanında, Google API'lerine erişmek için kullanabileceğiniz kapsamların tam listesi yer alır.
OAuth 2.0 erişim jetonları alma
Aşağıdaki adımlarda, uygulamanızın kullanıcı adına API isteği gerçekleştirmek için kullanıcının iznini almak üzere Google'ın OAuth 2.0 sunucusuyla nasıl etkileşim kurduğu gösterilmektedir. Uygulamanızın, kullanıcı yetkilendirmesi gerektiren bir Google API isteğini yürütebilmesi için bu izne sahip olması gerekir.
1. adım: Google'ın OAuth 2.0 sunucusuna yönlendirme
Kullanıcı verilerine erişim izni istemek için kullanıcıyı Google'ın OAuth 2.0 sunucusuna yönlendirin.
OAuth 2.0 uç noktaları
https://accounts.google.com/o/oauth2/v2/auth adresindeki Google'ın OAuth 2.0 uç noktasından erişim istemek için bir URL oluşturun. Bu uç noktaya HTTPS üzerinden erişilebilir. Düz HTTP bağlantıları reddedilir.
Google yetkilendirme sunucusu, web sunucusu uygulamaları için aşağıdaki sorgu dizesi parametrelerini destekler:
| Parametreler | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Zorunlu
Uygulamanızın istemci kimliği. Bu değeri Cloud Console'daki İstemciler sayfasında bulabilirsiniz. |
||||||
redirect_uri |
Zorunlu
Kullanıcı yetkilendirme akışını tamamladıktan sonra API sunucusunun kullanıcıyı nereye yönlendireceğini belirler. Değer, istemcinizin Cloud Console İstemciler sayfasında yapılandırdığınız OAuth 2.0 istemcisinin yetkili yönlendirme URI'larından biriyle tam olarak eşleşmelidir. Bu değer, sağlanan
|
||||||
response_type |
Zorunlu
JavaScript uygulamalarının, parametrenin değerini |
||||||
scope |
Zorunlu
Uygulamanızın kullanıcı adına erişebileceği kaynakları tanımlayan, boşlukla ayrılmış kapsam listesi. Bu değerler, Google'ın kullanıcıya gösterdiği kullanıcı rızası ekranını bilgilendirir. Kapsamlar, uygulamanızın yalnızca ihtiyaç duyduğu kaynaklara erişim isteğinde bulunmasını sağlarken kullanıcıların da uygulamanıza verdikleri erişim miktarını kontrol etmelerine olanak tanır. Bu nedenle, istenen kapsam sayısı ile kullanıcı rızası alma olasılığı arasında ters bir ilişki vardır. Uygulamanızın, mümkün olduğunda yetkilendirme kapsamlarına bağlam içinde erişim isteğinde bulunmasını öneririz. Kademeli yetkilendirme kullanarak kullanıcı verilerine bağlam içinde erişim isteğinde bulunarak kullanıcıların, uygulamanızın neden istediği erişime ihtiyaç duyduğunu anlamalarına yardımcı olursunuz. |
||||||
state |
Önerilen
Uygulamanızın, yetkilendirme isteğiniz ile yetkilendirme sunucusunun yanıtı arasındaki durumu korumak için kullandığı dize değerini belirtir.
Sunucu, kullanıcı uygulamanızın erişim isteğini kabul ettikten veya reddettikten sonra Bu parametreyi, kullanıcıyı uygulamanızdaki doğru kaynağa yönlendirme, tek seferlik rastgele sayılar gönderme ve siteler arası istek sahteciliğini azaltma gibi çeşitli amaçlarla kullanabilirsiniz. |
||||||
include_granted_scopes |
İsteğe bağlı
Uygulamaların, bağlamdaki ek kapsamlara erişim istemek için artımlı yetkilendirmeyi kullanmasına olanak tanır. Bu parametrenin değerini |
||||||
enable_granular_consent |
İsteğe bağlı
Varsayılan değer Google, bir uygulama için ayrıntılı izinleri etkinleştirdiğinde bu parametrenin artık herhangi bir etkisi olmayacaktır. |
||||||
login_hint |
İsteğe bağlı
Uygulamanız, hangi kullanıcının kimlik doğrulaması yapmaya çalıştığını biliyorsa Google Kimlik Doğrulama Sunucusu'na ipucu sağlamak için bu parametreyi kullanabilir. Sunucu, oturum açma formundaki e-posta alanını önceden doldurarak veya uygun çoklu giriş oturumunu seçerek giriş akışını basitleştirmek için ipucunu kullanır. Parametre değerini, kullanıcının Google kimliğine eşdeğer bir e-posta adresi veya |
||||||
prompt |
İsteğe bağlı
Kullanıcıya sunulacak istemlerin boşlukla ayrılmış, büyük/küçük harfe duyarlı listesi. Bu parametreyi belirtmezseniz kullanıcıdan yalnızca projeniz ilk kez erişim istediğinde onay istenir. Daha fazla bilgi için Yeniden izin isteme bölümüne bakın. Olası değerler:
|
||||||
Google'ın yetkilendirme sunucusuna örnek yönlendirme
Aşağıda, okunabilirliği artırmak için satır sonları ve boşluklar içeren örnek bir URL gösterilmektedir.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//developers.google.com/oauthplayground& client_id=client_id
İstek URL'sini oluşturduktan sonra kullanıcıyı bu URL'ye yönlendirin.
JavaScript örnek kodu
Aşağıdaki JavaScript snippet'i, JavaScript için Google API'leri İstemci Kitaplığı'nı kullanmadan JavaScript'te yetkilendirme akışının nasıl başlatılacağını gösterir. Bu OAuth 2.0 uç noktası, merkezler arası kaynak paylaşımını (CORS) desteklemediğinden snippet, bu uç noktaya yönelik isteği açan bir form oluşturur.
/* * Create form to request access token from Google's OAuth 2.0 server. */ function oauthSignIn() { // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create <form> element to submit parameters to OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': 'YOUR_CLIENT_ID', 'redirect_uri': 'YOUR_REDIRECT_URI', 'response_type': 'token', 'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly', 'include_granted_scopes': 'true', 'state': 'pass-through value'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); }
2. adım: Google, kullanıcıdan izin ister
Bu adımda kullanıcı, uygulamanıza istenen erişimi verip vermeyeceğine karar verir. Bu aşamada Google, uygulamanızın adını ve kullanıcının yetkilendirme kimlik bilgileriyle erişim izni istediği Google API'leri hizmetlerini gösteren bir izin penceresi ve verilecek erişim kapsamlarının özetini gösterir. Kullanıcı, uygulamanızın istediği bir veya daha fazla kapsama erişim izni vermeyi kabul edebilir ya da isteği reddedebilir.
Uygulamanızın bu aşamada herhangi bir işlem yapması gerekmez. Google'ın OAuth 2.0 sunucusundan erişim izni verilip verilmediğini belirten yanıtı bekler. Bu yanıt, bir sonraki adımda açıklanmıştır.
Hatalar
Google'ın OAuth 2.0 yetkilendirme uç noktasına gönderilen istekler, beklenen kimlik doğrulama ve yetkilendirme akışları yerine kullanıcılara yönelik hata mesajları gösterebilir. Sık karşılaşılan hata kodları ve önerilen çözümler şunlardır:
admin_policy_enforced
Google Hesabı, Google Workspace yöneticisinin politikaları nedeniyle istenen bir veya daha fazla kapsamı yetkilendiremiyor. Yöneticilerin, OAuth istemci kimliğinize açıkça erişim izni verilene kadar tüm kapsamlara veya hassas ve kısıtlanmış kapsamlara erişimi nasıl kısıtlayabileceği hakkında daha fazla bilgi için Google Workspace verilerine hangi üçüncü taraf uygulamalar ve dahili uygulamaların erişebileceğini yönetme başlıklı Google Workspace Yönetici Yardım makalesini inceleyin.
disallowed_useragent
Yetkilendirme uç noktası, Google'ın OAuth 2.0 Politikaları tarafından izin verilmeyen yerleşik bir kullanıcı aracısı içinde gösteriliyor.
iOS ve macOS geliştiricileri, WKWebView uygulamasında yetkilendirme isteklerini açarken bu hatayla karşılaşabilir.
Geliştiriciler bunun yerine iOS için Google ile Oturum Açma veya OpenID Foundation'ın iOS için AppAuth gibi iOS kitaplıklarını kullanmalıdır.
Web geliştiricileri, bir iOS veya macOS uygulaması yerleşik bir kullanıcı aracısında genel bir web bağlantısı açtığında ve kullanıcı sitenizden Google'ın OAuth 2.0 yetkilendirme uç noktasına gittiğinde bu hatayla karşılaşabilir. Geliştiriciler, genel bağlantıların işletim sisteminin varsayılan bağlantı işleyicisinde açılmasına izin vermelidir. Bu işleyiciler arasında hem Geçiş Bağlantıları işleyicileri hem de varsayılan tarayıcı uygulaması yer alır. SFSafariViewController kitaplığı da desteklenen bir seçenektir.
org_internal
İstekteki OAuth istemci kimliği, belirli bir Google Cloud kuruluşundaki Google Hesaplarına erişimi sınırlayan bir projenin parçasıdır. Bu yapılandırma seçeneği hakkında daha fazla bilgi için OAuth kullanıcı rızası ekranınızı ayarlama yardım makalesindeki Kullanıcı türü bölümüne bakın.
invalid_client
İsteğin yapıldığı kaynak, bu istemci için yetkilendirilmemiş. origin_mismatch sayfasına göz atın.
deleted_client
İsteği göndermek için kullanılan OAuth istemcisi silinmiştir. Silme işlemi manuel olarak veya kullanılmayan istemciler söz konusu olduğunda otomatik olarak yapılabilir. Silinen müşteriler, silme işleminden sonraki 30 gün içinde geri yüklenebilir. Daha fazla bilgi edinin .
invalid_grant
Artımlı yetkilendirme kullanırken jetonun süresi dolmuş veya jeton geçersiz kılınmış olabilir. Kullanıcının kimliğini tekrar doğrulayın ve yeni jetonlar almak için kullanıcıdan izin isteyin. Bu hatayı görmeye devam ederseniz uygulamanızın doğru şekilde yapılandırıldığından ve isteğinizde doğru jetonları ve parametreleri kullandığınızdan emin olun. Aksi takdirde, kullanıcı hesabı silinmiş veya devre dışı bırakılmış olabilir.
origin_mismatch
Yetkilendirme isteğini başlatan JavaScript'in şeması, alanı ve/veya bağlantı noktası, OAuth istemci kimliği için kayıtlı yetkili bir JavaScript kaynak URI'siyle eşleşmeyebilir. Google Cloud Console'un İstemciler sayfasında yetkili JavaScript kaynaklarını inceleyin.
redirect_uri_mismatch
Yetkilendirme isteğinde iletilen redirect_uri, OAuth istemci kimliği için yetkilendirilmiş bir yönlendirme URI'siyle eşleşmiyor. Google Cloud Console'un İstemciler sayfasında yetkilendirilmiş yönlendirme URI'lerini inceleyin.
Yetkilendirme isteğini başlatan JavaScript'in şeması, alanı ve/veya bağlantı noktası, OAuth istemci kimliği için kayıtlı yetkili bir JavaScript kaynak URI'siyle eşleşmeyebilir. Google Cloud Console'un İstemciler sayfasında yetkili JavaScript kaynaklarını inceleyin.
redirect_uri parametresi, kullanımdan kaldırılan ve artık desteklenmeyen OAuth bant dışı (OOB) akışına başvuruyor olabilir. Entegrasyonunuzu güncellemek için geçiş rehberini inceleyin.
invalid_request
İsteğinizle ilgili bir sorun oluştu. Bunun birkaç nedeni olabilir:
- İstek doğru şekilde biçimlendirilmemiş.
- İstekte gerekli parametreler eksikti.
- İstek, Google'ın desteklemediği bir yetkilendirme yöntemi kullanıyor. OAuth entegrasyonunuzun önerilen bir entegrasyon yöntemi kullandığını doğrulayın.
3. adım: OAuth 2.0 sunucu yanıtını işleme
OAuth 2.0 uç noktaları
OAuth 2.0 sunucusu, erişim jetonu isteğinizde belirtilen redirect_uri adresine bir yanıt gönderir.
Kullanıcı isteği onaylarsa yanıt bir erişim jetonu içerir. Kullanıcı isteği onaylamazsa yanıtta bir hata mesajı yer alır. Erişim jetonu veya hata mesajı, aşağıdaki örneklerde gösterildiği gibi yönlendirme URI'sinin karma parçasında döndürülür:
Erişim jetonu yanıtı:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
Parça dizesi,
access_tokenparametresinin yanı sıra her zamanBearerolarak ayarlanantoken_typeparametresini ve jetonun geçerlilik süresini saniye cinsinden belirtenexpires_inparametresini de içerir. Erişim jetonu isteğindestateparametresi belirtildiyse bu parametrenin değeri de yanıta dahil edilir.- Hata yanıtı:
https://oauth2.example.com/callback#error=access_denied
Örnek OAuth 2.0 sunucu yanıtı
Google Drive'ınızdaki dosyaların meta verilerini görüntülemek için salt okuma erişimi ve Google Takvim etkinliklerinizi görüntülemek için salt okuma erişimi isteyen aşağıdaki örnek URL'yi tıklayarak bu akışı test edebilirsiniz:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//developers.google.com/oauthplayground& client_id=client_id
OAuth 2.0 akışını tamamladıktan sonra tarayıcınız sizi OAuth akışlarını test etmeye yönelik bir araç olan OAuth 2.0 Playground'a yönlendirir. OAuth 2.0 Playground'un yetkilendirme kodunu otomatik olarak yakaladığını göreceksiniz.
4. adım: Kullanıcıların hangi kapsamlara izin verdiğini kontrol edin
Birden fazla izin (kapsam) istediğinizde kullanıcılar uygulamanıza tüm izinlere erişim hakkı vermeyebilir. Uygulamanız, gerçekte hangi kapsamların verildiğini doğrulamalı ve bazı izinlerin reddedildiği durumları, genellikle reddedilen kapsamlara dayalı özellikleri devre dışı bırakarak sorunsuz bir şekilde ele almalıdır.
Ancak istisnalar bulunmaktadır. Alan genelinde yetki devri olan Google Workspace Enterprise uygulamaları veya Güvenilir olarak işaretlenen uygulamalar, ayrıntılı izinler için kullanıcı rızası ekranını atlar. Bu uygulamalarda kullanıcılar ayrıntılı kullanıcı rızası ekranını görmez. Bunun yerine, uygulamanız istenen tüm kapsamları alır veya hiçbirini almaz.
Daha ayrıntılı bilgi için Ayrıntılı izinleri işleme başlıklı makaleyi inceleyin.
OAuth 2.0 uç noktaları
Kullanıcının uygulamanıza belirli bir kapsam için erişim izni verip vermediğini kontrol etmek için erişim jetonu yanıtındaki scope alanını inceleyin. erişim jetonu tarafından verilen erişim kapsamları, boşlukla ayrılmış ve büyük/küçük harfe duyarlı dizelerden oluşan bir liste olarak ifade edilir.
Örneğin, aşağıdaki örnek erişim jetonu yanıtı, kullanıcının uygulamanıza salt okunur Drive etkinliği ve Takvim etkinlikleri izinlerine erişim izni verdiğini gösterir:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Google API'lerini çağırma
OAuth 2.0 uç noktaları
Uygulamanız bir erişim jetonu aldıktan sonra, API'nin gerektirdiği erişim kapsamları verilmişse belirli bir kullanıcı hesabı adına Google API'sine çağrı yapmak için jetonu kullanabilirsiniz. Bunu yapmak için bir access_token sorgu parametresi veya bir Authorization HTTP üstbilgisi Bearer değeri ekleyerek erişim jetonunu API'ye gönderilen bir isteğe ekleyin. Mümkün olduğunda HTTP başlığı tercih edilir çünkü sorgu dizeleri sunucu günlüklerinde görünür. Çoğu durumda, Google API'lerine çağrılarınızı ayarlamak için bir istemci kitaplığı kullanabilirsiniz (örneğin, Drive Files API'yi çağırırken).
Tüm Google API'lerini deneyebilir ve kapsamlarını OAuth 2.0 Playground'da görüntüleyebilirsiniz.
HTTP GET örnekleri
Authorization: Bearer HTTP üst bilgisini kullanarak
drive.files uç noktasına (Drive Files API) yapılan bir çağrı aşağıdaki gibi görünebilir. Kendi erişim jetonunuzu belirtmeniz gerektiğini unutmayın:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
access_token sorgu dizesi parametresini kullanan kimliği doğrulanmış kullanıcı için aynı API'ye yapılan çağrı aşağıda verilmiştir:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl örnek
Bu komutları curl komut satırı uygulamasıyla test edebilirsiniz. HTTP üstbilgisi seçeneğini (tercih edilen) kullanan bir örnek aşağıda verilmiştir:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Alternatif olarak sorgu dizesi parametresi seçeneğini de kullanabilirsiniz:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
JavaScript örnek kodu
Aşağıdaki kod snippet'i, bir Google API'sine istek göndermek için CORS'un (çapraz kaynak kaynak paylaşımı) nasıl kullanılacağını gösterir. Bu örnekte, JavaScript için Google API'leri istemci kitaplığı kullanılmaz. Ancak istemci kitaplığını kullanmıyor olsanız bile bu kitaplığın dokümanlarındaki CORS desteği kılavuzu, bu istekleri daha iyi anlamanıza yardımcı olabilir.
Bu kod snippet'inde access_token değişkeni, yetkili kullanıcı adına API istekleri yapmak için aldığınız jetonu temsil eder. Eksiksiz örnek, bu jetonun tarayıcının yerel depolama alanında nasıl saklanacağını ve API isteği gönderilirken nasıl alınacağını gösterir.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { console.log(xhr.response); }; xhr.send(null);
Eksiksiz örnek
OAuth 2.0 uç noktaları
Bu kod örneği, JavaScript için Google API'leri istemci kitaplığını kullanmadan JavaScript'te OAuth 2.0 akışının nasıl tamamlanacağını gösterir. Kod, API isteğini denemek için bir düğme gösteren HTML sayfası içindir. Düğmeyi tıklarsanız kod, sayfanın tarayıcınızın yerel depolama alanında bir API erişim jetonu depolayıp depolamadığını kontrol eder. Bu durumda API isteğini yürütür. Aksi takdirde OAuth 2.0 akışını başlatır.
OAuth 2.0 akışı için sayfa şu adımları izler:
- Kullanıcıyı Google'ın OAuth 2.0 sunucusuna yönlendirir. Bu sunucu,
https://www.googleapis.com/auth/drive.metadata.readonlyvehttps://www.googleapis.com/auth/calendar.readonlykapsamlarına erişim ister. - İstenen bir veya daha fazla kapsama erişim izni verdikten (veya reddettikten) sonra kullanıcı, erişim jetonunu parça tanımlayıcı dizesinden ayrıştıran orijinal sayfaya yönlendirilir.
- Sayfa, kullanıcının uygulamaya hangi kapsamlar için erişim izni verdiğini kontrol eder.
Kullanıcı, istenen kapsamlara erişim izni verdiyse sayfa, örnek API isteğinde bulunmak için erişim jetonunu kullanır.
API isteği, yetkili kullanıcının Google Drive hesabı hakkında bilgi almak için Drive API'nin
about.getyöntemini çağırır.- İstek başarıyla yürütülürse API yanıtı, tarayıcının hata ayıklama konsoluna kaydedilir.
Google Hesabınızın İzinler sayfasından uygulamanın erişimini iptal edebilirsiniz. Uygulama, istemci kimliği oluşturma sırasında OAuth kullanıcı rızası ekranındaki markalama sayfasında sağlanan uygulama adı olarak listelenir.
Bu kodu yerel olarak çalıştırmak için YOUR_CLIENT_ID ve YOUR_REDIRECT_URI değişkenlerine yetkilendirme kimlik bilgilerinize karşılık gelen değerler atamanız gerekir. YOUR_REDIRECT_URI değişkeni, sayfanın yayınlandığı URL ile aynı URL'ye ayarlanmalıdır. Değer, Cloud Console İstemciler sayfasında yapılandırdığınız OAuth 2.0 istemcisinin yetkili yönlendirme URI'larından biriyle tam olarak eşleşmelidir. Bu değer, yetkili bir URI ile eşleşmezse redirect_uri_mismatch hatası alırsınız. Projenizde bu istek için uygun API'nin de etkinleştirilmiş olması gerekir.
<html><head></head><body>
<script>
var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
// Parse query string to see if page request is coming from OAuth 2.0 server.
var fragmentString = location.hash.substring(1);
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0 && params['state']) {
if (params['state'] == localStorage.getItem('state')) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
trySampleRequest();
} else {
console.log('State mismatch. Possible CSRF attack');
}
}
// Function to generate a random state value
function generateCryptoRandomState() {
const randomValues = new Uint32Array(2);
window.crypto.getRandomValues(randomValues);
// Encode as UTF-8
const utf8Encoder = new TextEncoder();
const utf8Array = utf8Encoder.encode(
String.fromCharCode.apply(null, randomValues)
);
// Base64 encode the UTF-8 data
return btoa(String.fromCharCode.apply(null, utf8Array))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// If there's an access token, try an API request.
// Otherwise, start OAuth 2.0 flow.
function trySampleRequest() {
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
if (params && params['access_token']) {
// User authorized the request. Now, check which scopes were granted.
if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
// User authorized read-only Drive activity permission.
// Calling the APIs, etc.
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/drive/v3/about?fields=user&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
if (xhr.readyState === 4 && xhr.status === 200) {
console.log(xhr.response);
} else if (xhr.readyState === 4 && xhr.status === 401) {
// Token invalid, so prompt for user permission.
oauth2SignIn();
}
};
xhr.send(null);
}
else {
// User didn't authorize read-only Drive activity permission.
// Update UX and application accordingly
console.log('User did not authorize read-only Drive activity permission.');
}
// Check if user authorized Calendar read permission.
if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
// User authorized Calendar read permission.
// Calling the APIs, etc.
console.log('User authorized Calendar read permission.');
}
else {
// User didn't authorize Calendar read permission.
// Update UX and application accordingly
console.log('User did not authorize Calendar read permission.');
}
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// create random state value and store in local storage
var state = generateCryptoRandomState();
localStorage.setItem('state', state);
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create element to open OAuth 2.0 endpoint in new window.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': YOUR_CLIENT_ID,
'redirect_uri': YOUR_REDIRECT_URI,
'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
'state': state,
'include_granted_scopes': 'true',
'response_type': 'token'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
</script>
<button onclick="trySampleRequest();">Try sample request</button>
</body></html>JavaScript kaynak doğrulama kuralları
Google, geliştiricilerin uygulamalarını güvende tutmalarına yardımcı olmak için JavaScript kaynaklarına aşağıdaki doğrulama kurallarını uygular. JavaScript kaynaklarınız bu kurallara uymalıdır. Bu kurallarda kullanılan alan, ana makine ve şema tanımları için RFC 3986 bölüm 3'e bakın.
| Doğrulama kuralları | |
|---|---|
| Şema |
JavaScript kaynakları, düz HTTP yerine HTTPS şemasını kullanmalıdır. Localhost URI'leri (localhost IP adresi URI'leri dahil) bu kuraldan muaftır. |
| Düzenleyen |
Ana makineler ham IP adresleri olamaz. Localhost IP adresleri bu kuraldan muaftır. |
| Alan |
“googleusercontent.com” olamaz.goo.gl) içeremez. |
| Userinfo |
JavaScript kaynakları, kullanıcı bilgileri alt bileşenini içeremez. |
| Yol |
JavaScript kaynakları, yol bileşenini içeremez. |
| Sorgu |
JavaScript kaynakları, sorgu bileşeni içeremez. |
| Fragment |
JavaScript kaynakları, parça bileşeni içeremez. |
| Karakterler |
JavaScript kaynakları, aşağıdakiler de dahil olmak üzere belirli karakterleri içeremez:
|
Artımlı yetkilendirme
OAuth 2.0 protokolünde uygulamanız, kapsamlarla tanımlanan kaynaklara erişim için yetkilendirme ister. Kaynaklar için yetkilendirmeyi ihtiyaç duyduğunuz anda istemek, kullanıcı deneyimi açısından en iyi uygulama olarak kabul edilir. Bu uygulamayı etkinleştirmek için Google'ın yetkilendirme sunucusu, artımlı yetkilendirmeyi destekler. Bu özellik, kapsamları gerektiğinde istemenize olanak tanır ve kullanıcı yeni kapsam için izin verirse kullanıcının projeye verdiği tüm kapsamları içeren bir jetonla değiştirilebilecek bir yetkilendirme kodu döndürür.
Örneğin, kullanıcıların müzik parçalarını örneklemesine ve miksler oluşturmasına olanak tanıyan bir uygulamanın, oturum açma sırasında çok az kaynağa ihtiyacı olabilir. Belki de oturum açan kişinin adından başka bir şeye ihtiyacı yoktur. Ancak tamamlanan bir miksi kaydetmek için Google Drive'larına erişim gerekir. Çoğu kullanıcı, Google Drive'larına erişim izninin yalnızca uygulamanın gerçekten ihtiyaç duyduğu anda istenmesini doğal karşılar.
Bu durumda uygulama, oturum açma sırasında temel oturum açma işlemini gerçekleştirmek için openid ve profile kapsamlarını, daha sonra ise bir karışımı kaydetmek için ilk istek sırasında https://www.googleapis.com/auth/drive.file kapsamını isteyebilir.
Kademeli yetkilendirmeden alınan erişim jetonları için aşağıdaki kurallar geçerlidir:
- Jeton, yeni ve birleştirilmiş yetkilendirmeye dahil edilen kapsamlardan herhangi birine karşılık gelen kaynaklara erişmek için kullanılabilir.
- Erişim jetonu almak üzere birleştirilmiş yetkilendirme için yenileme jetonunu kullandığınızda erişim jetonu, birleştirilmiş yetkilendirmeyi temsil eder ve yanıta dahil edilen
scopedeğerlerinden herhangi biri için kullanılabilir. - Birleşik yetkilendirme, farklı istemcilerden istenmiş olsa bile kullanıcının API projesine verdiği tüm kapsamları içerir. Örneğin, bir kullanıcı bir uygulamanın masaüstü istemcisini kullanarak bir kapsama erişim izni verdikten sonra aynı uygulamaya mobil uygulama istemcisi aracılığıyla başka bir kapsam için izin verirse birleştirilmiş yetkilendirme her iki kapsamı da içerir.
- Birleşik bir yetkilendirmeyi temsil eden bir jetonu iptal ederseniz ilişkili kullanıcı adına bu yetkilendirmenin tüm kapsamlarına erişim aynı anda iptal edilir.
Aşağıdaki kod örneklerinde, mevcut bir erişim jetonuna nasıl kapsam ekleneceği gösterilmektedir. Bu yaklaşım, uygulamanızın birden fazla erişim jetonunu yönetme ihtiyacını ortadan kaldırır.
OAuth 2.0 uç noktaları
Mevcut bir erişim jetonuna kapsam eklemek için Google'ın OAuth 2.0 sunucusuna gönderdiğiniz isteğe include_granted_scopes parametresini ekleyin.
Aşağıdaki kod snippet'inde bunun nasıl yapılacağı gösterilmektedir. Snippet, erişim jetonunuzun geçerli olduğu kapsamları tarayıcının yerel depolama alanında depoladığınızı varsayar. (Eksiksiz örnek kodu, tarayıcının yerel depolama alanında oauth2-test-params.scope özelliğini ayarlayarak erişim jetonunun geçerli olduğu kapsamların listesini depolar.)
Snippet, erişim jetonunun geçerli olduğu kapsamları belirli bir sorgu için kullanmak istediğiniz kapsamla karşılaştırır. Erişim jetonu bu kapsamı içermiyorsa OAuth 2.0 akışı başlar.
Burada, oauth2SignIn işlevi 2. adımda sağlanan (ve daha sonra eksiksiz örnekte sağlanan) işlevle aynıdır.
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'; var params = JSON.parse(localStorage.getItem('oauth2-test-params')); var current_scope_granted = false; if (params.hasOwnProperty('scope')) { var scopes = params['scope'].split(' '); for (var s = 0; s < scopes.length; s++) { if (SCOPE == scopes[s]) { current_scope_granted = true; } } } if (!current_scope_granted) { oauth2SignIn(); // This function is defined elsewhere in this document. } else { // Since you already have access, you can proceed with the API request. }
Jeton iptali
Bazı durumlarda kullanıcılar bir uygulamaya verilen erişimi iptal etmek isteyebilir. Kullanıcı, Hesap Ayarları'nı ziyaret ederek erişimi iptal edebilir. Daha fazla bilgi için Hesabınıza erişimi olan üçüncü taraf siteleri ve uygulamaları destek dokümanındaki Site veya uygulama erişimini kaldırma bölümüne bakın.
Bir uygulamanın, kendisine verilen erişimi programatik olarak iptal etmesi de mümkündür. Programatik iptal; kullanıcının abonelikten çıktığı, bir uygulamayı kaldırdığı veya bir uygulama için gereken API kaynaklarının önemli ölçüde değiştiği durumlarda önemlidir. Başka bir deyişle, kaldırma işleminin bir parçası olarak, uygulamaya daha önce verilen izinlerin kaldırıldığından emin olmak için bir API isteği gönderilebilir.
OAuth 2.0 uç noktaları
Bir jetonu programatik olarak iptal etmek için uygulamanız https://oauth2.googleapis.com/revoke adresine istek gönderir ve jetonu parametre olarak ekler:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}Jeton, erişim jetonu veya yenileme jetonu olabilir. Jeton bir erişim jetonuysa ve karşılık gelen bir yenileme jetonu varsa yenileme jetonu da iptal edilir.
İptal işlemi başarıyla işlenirse yanıtın HTTP durum kodu 200 olur. Hata koşulları için hata koduyla birlikte bir HTTP durum kodu 400 döndürülür.
Aşağıdaki JavaScript snippet'i, JavaScript için Google API'leri İstemci Kitaplığı'nı kullanmadan JavaScript'te bir jetonun nasıl iptal edileceğini gösterir. Google'ın jetonları iptal etmek için kullandığı OAuth 2.0 uç noktası, çapraz kaynaklı kaynak paylaşımını (CORS) desteklemediğinden kod, isteği yayınlamak için XMLHttpRequest() yöntemini kullanmak yerine bir form oluşturur ve formu uç noktaya gönderir.
function revokeAccess(accessToken) { // Google's OAuth 2.0 endpoint for revoking access tokens. var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke'; // Create <form> element to use to POST data to the OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'post'); form.setAttribute('action', revokeTokenEndpoint); // Add access token to the form so it is set as value of 'token' parameter. // This corresponds to the sample curl request, where the URL is: // https://oauth2.googleapis.com/revoke?token={token} var tokenField = document.createElement('input'); tokenField.setAttribute('type', 'hidden'); tokenField.setAttribute('name', 'token'); tokenField.setAttribute('value', accessToken); form.appendChild(tokenField); // Add form to page and submit it to actually revoke the token. document.body.appendChild(form); form.submit(); }
Hesaplar Arası Koruma'yı uygulama
Kullanıcılarınızın hesaplarını korumak için atmanız gereken ek bir adım, Google'ın Hesaplar Arası Koruma Hizmeti'nden yararlanarak Hesaplar Arası Koruma'yı uygulamaktır. Bu hizmet, kullanıcı hesabındaki önemli değişiklikler hakkında uygulamanıza bilgi veren güvenlik etkinliği bildirimlerine abone olmanızı sağlar. Ardından, etkinliklere nasıl yanıt vereceğinize karar vermek için bu bilgileri kullanarak harekete geçin.
Google'ın Hesaplar Arası Koruma hizmeti tarafından uygulamanıza gönderilen etkinlik türlerine örnek olarak şunlar verilebilir:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Hesaplar Arası Koruma'yı nasıl uygulayacağınız hakkında daha fazla bilgi ve mevcut etkinliklerin tam listesi için Kullanıcı hesaplarını Hesaplar Arası Koruma ile koruma sayfasını inceleyin.