Kullanıcı Kimlik Doğrulaması

Web kimlik doğrulama protokolleri HTTP özelliklerini kullanır ancak Chrome uygulamaları uygulama kapsayıcısında çalışır. HTTP üzerinden yüklenmez, yönlendirme yapamaz veya çerez ayarlayamaz.

Kullanıcıların kimliğini doğrulamak için Chrome Identity API'yi kullanın: Google Hesaplarına giriş yapan kullanıcılar için getAuthToken, Google dışı bir hesaba giriş yapan kullanıcılar için launchWebAuthFlow. Uygulamanız, kullanıcıların kimliğini doğrulamak için kendi sunucusunu kullanıyorsa bu sunucuyu kullanmanız gerekir.

İşleyiş şekli

Chrome uygulamaları kullanıcılarının profilleriyle ilişkili bir Google Hesabı vardır. Uygulamalar, getAuthToken API'yi kullanarak bu kullanıcılar için OAuth2 jetonları alabilir.

Google dışı kimlik sağlayıcılarla kimlik doğrulaması yapmak isteyen uygulamaların launchWebAuthFlow çağrısı yapması gerekir. Bu yöntem, sağlayıcı sayfalarını göstermek için bir tarayıcı pop-up'ı kullanır ve belirli URL kalıplarına yönlendirmeleri yakalar. Yönlendirme URL'leri uygulamaya iletilir ve uygulama, jetonu URL'den çıkarır.

Google Hesabı kimlik doğrulaması

Tamamlamanız gereken beş adım şunlardır:

  1. Manifest dosyanıza izinler ekleyin ve uygulamanızı yükleyin.
  2. Yüklü manifest.json'teki anahtarı kaynak manifestinize kopyalayın. Böylece uygulama kimliğiniz geliştirme sırasında sabit kalır.
  3. Chrome uygulamanız için bir OAuth2 istemci kimliği alın.
  4. Manifest dosyanızı istemci kimliğini ve kapsamları içerecek şekilde güncelleyin.
  5. Kimlik doğrulama jetonunu alın.

İzin ekleme ve uygulama yükleme

Manifest'inizde kimlik izninin bulunduğundan emin olmanız gerekir. Ardından uygulamanızı uygulamalar ve uzantı yönetimi sayfasına yükleyebilirsiniz (Yayınlama bölümüne bakın).

"permissions": [
  "identity"
]

Anahtarı manifest dosyanıza kopyalama

Uygulamanızı Google OAuth Konsolu'na kaydettiğinizde, jeton istekleri sırasında kontrol edilecek olan uygulamanızın kimliğini belirtirsiniz. Bu nedenle, geliştirme sırasında tutarlı bir uygulama kimliğine sahip olmanız önemlidir.

Uygulama kimliğinizi sabit tutmak için yüklü manifest.json'teki anahtarı kaynak manifestinize kopyalamanız gerekir. Bu işlem çok kolay değildir ancak aşağıdaki adımları uygulayarak yapabilirsiniz:

  1. Kullanıcı verileri dizininize gidin. MacOs'te örnek: ~/Library/Application\ Support/Google/Chrome/Default/Extensions
  2. Yüklü uygulamaları ve uzantıları listeleyin ve uygulama ve uzantı yönetim sayfasındaki uygulama kimliğinizi buradaki aynı kimlikle eşleştirin.
  3. Yüklü uygulama dizinine gidin (bu, uygulama kimliği içindeki bir sürüm olacaktır). Yüklü manifest.json dosyasını açın (pico, dosyayı açmanın hızlı bir yoludur).
  4. Yüklü manifest.json'teki"anahtarı" kopyalayıp uygulamanızın kaynak manifest dosyasına yapıştırın.

OAuth2 istemci kimliğinizi alma

İstemci kimliğini almak için uygulamanızı Google API'leri Konsolu'na kaydetmeniz gerekir:

  1. Uygulamanızı Chrome Web Mağazası'na yüklemek için kullanılan Google Hesabı'nı kullanarak Google API Konsolu'na giriş yapın.
  2. Sol üst köşedeki açılır menüyü genişletip Oluştur... menü öğesini seçerek yeni bir proje oluşturun.
  3. Oluşturup adlandırdıktan sonra "Hizmetler" gezinme menüsü öğesine gidip uygulamanızın ihtiyaç duyduğu tüm Google hizmetlerini etkinleştirin.
  4. "API Erişimi" gezinme menüsü öğesine gidin ve OAuth 2.0 istemci kimliği oluştur... mavi düğmesini tıklayın.
  5. İstenen marka bilgilerini girin ve Yüklü uygulama türünü seçin.
  6. Chrome Uygulaması'nı seçin ve uygulama kimliğinizi girin (uygulama ve uzantı yönetimi sayfasında gösterilen kimlikle aynıdır).

Manifest dosyanızı OAuth2 istemci kimliği ve kapsamlarıyla güncelleyin

Manifest dosyanızı istemci kimliğini ve kapsamları içerecek şekilde güncellemeniz gerekir. gdrive örneği için "oauth2" örneğini burada bulabilirsiniz:

"oauth2": {
    "client_id": "665859454684.apps.googleusercontent.com",
    "scopes": [
      "https://www.googleapis.com/auth/drive"
    ]
  }

Erişim jetonları alma

Artık identity.getAuthToken kimliğini çağırarak yetkilendirme jetonunu almaya hazırsınız.

chrome.identity.getAuthToken({ 'interactive': true }, function(token) {
  // Use the token.
});

Kullanıcı etkileşimi

getAuthToken işlevini çağırırken, API'nin etkileşimli modda mı yoksa sessiz modda mı çağrılmasını istediğinizi belirten bir işaret (yukarıdaki örnekte 'interactive': true) iletebilirsiniz. API'yi etkileşimli modda çağırırsanız gerektiğinde kullanıcıya aşağıdaki ekran görüntüsünde gösterildiği gibi bir oturum açma ve/veya onay kullanıcı arayüzü gösterilir:

Bir uygulamanın, Google Hesabı'nın kimliğini doğrulamak için Identity API'yi kullandığında kullanıcı arayüzünü gösteren ekran görüntüsü

API'yi sessiz modda çağırırsanız API yalnızca kullanıcı arayüzü göstermeden jeton oluşturmak mümkünse jeton döndürür. Bu, örneğin bir uygulamanın uygulama başlatılırken akışı gerçekleştirdiği durumlarda veya genel olarak kullanıcı hareketi içermeyen durumlarda yararlıdır.

Önerdiğimiz en iyi uygulama, kullanıcı hareketi olmadığında sessiz modu, kullanıcı hareketi olduğunda (ör. kullanıcı uygulamanızda Giriş yap düğmesini tıkladığında) etkileşimli modu kullanmaktır. Herhangi bir hareket koşulu uygulamadığımızı unutmayın.

Önbelleğe alma

Chrome, erişim jetonlarının bellek içi bir önbelleği olduğundan, jeton kullanmanız gerektiğinde dilediğiniz zaman getAuthToken işlevini çağırabilirsiniz. Jetonun geçerlilik süresi, önbellek tarafından otomatik olarak yönetilir.

chrome://identity-internals adresinde jeton önbelleği durumunu görebilirsiniz.

Kullanıcının şifresini değiştirmesi gibi bazı durumlarda, süresi dolmamış erişim jetonları çalışmayı durdurur. Jetonu kullanan API çağrıları 401 HTTP durum koduyla döndürülmeye başlar. Bunun olduğunu tespit ederseniz identity.removeCachedAuthToken adresini çağırarak geçersiz jetonu Chrome'un önbelleğinden kaldırabilirsiniz.

removeCachedAuthToken kullanımı örneği:

// callback = function (error, httpStatus, responseText);
function authenticatedXhr(method, url, callback) {
  var retry = true;
  function getTokenAndXhr() {
    chrome.identity.getAuthToken({/* details */},
                                 function (access_token) {
      if (chrome.runtime.lastError) {
        callback(chrome.runtime.lastError);
        return;
      }

      var xhr = new XMLHttpRequest();
      xhr.open(method, url);
      xhr.setRequestHeader('Authorization',
                           'Bearer ' + access_token);

      xhr.onload = function () {
        if (this.status === 401 && retry) {
          // This status may indicate that the cached
          // access token was invalid. Retry once with
          // a fresh token.
          retry = false;
          chrome.identity.removeCachedAuthToken(
              { 'token': access_token },
              getTokenAndXhr);
          return;
        }

        callback(null, this.status, this.responseText);
      }
    });
  }
}

Google dışı hesap kimlik doğrulaması

Tamamlamanız gereken üç adım şunlardır:

  1. Sağlayıcıya kaydolun.
  2. Uygulamanızın erişeceği sağlayıcı kaynakları için izinler ekleyin.
  3. Kimlik doğrulama jetonunu alın.

Sağlayıcıya kaydolun

Sağlayıcıya bir OAuth2 istemci kimliği kaydettirmeniz ve istemci kimliğini web sitesi olarak yapılandırmanız gerekir. Kayıt sırasında girilecek yönlendirme URI'si için formun URL'sini kullanın: https://<extension-id>.chromiumapp.org/<anything-here>

Örneğin, uygulama kimliğiniz abcdefghijklmnopqrstuvwxyzabcdef ise ve provider_cb'nin yol olmasını istiyorsanız diğer sağlayıcıların yönlendirme URI'lerinden ayırt etmek için şunu kullanmanız gerekir: https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb

Sağlayıcı için izin ekleme

Sağlayıcı API uç noktalarına kaynaktan bağımsız XHR'ler göndermek için izinlerde uygun kalıpları izin verilenler listesine eklemeniz gerekir:

"permissions": [
  ...
  "https://www.website-of-provider-with-user-photos.com/photos/*"
]

Jetonu alma

Jetonu almak için:

chrome.identity.launchWebAuthFlow(
  {'url': '<url-to-do-auth>', 'interactive': true},
  function(redirect_url) { /* Extract token from redirect_url */ });

<url-to-do-auth>, bir web sitesinden sağlayıcıya kimlik doğrulaması yapmak için kullanılan URL'dir. Örneğin, bir sağlayıcıyla OAuth2 akışı gerçekleştirdiğinizi, uygulamanızı 123456789012345 istemci kimliğiyle kaydettiğinizi ve sağlayıcının web sitesindeki kullanıcı fotoğraflarına erişmek istediğinizi varsayalım: https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_id=123456789012345& redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb&response_type=token&scope=user_photos

Sağlayıcı, kimlik doğrulamayı gerçekleştirir ve uygunsa kullanıcıya giriş ve/veya onay kullanıcı arayüzünü gösterir. Ardından https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token> adresine yönlendirilir.

Chrome bunu yakalar ve tam yönlendirme URL'siyle uygulamanın geri çağırma işlevini çağırır. Uygulama, jetonu URL'den çıkarmalıdır.

Etkileşimli mod ve sessiz mod

launchWebAuthFlow öğesini çağırırken API'nin etkileşimli modda (sessiz modda) çağrılmasını isteyip istemediğinizi belirten bir işaret (yukarıdaki örnekte 'interactive': true) iletebilirsiniz. API'yi etkileşimli modda çağırırsanız gerekirse jetonu alması için kullanıcıya (oturum açma kullanıcı arayüzü ve/veya onay kullanıcı arayüzü ya da bu konuda sağlayıcıya özel herhangi bir kullanıcı arayüzü) kullanıcı arayüzü gösterilir.

API'yi sessiz modda çağırırsanız API yalnızca sağlayıcı herhangi bir kullanıcı arayüzü göstermeden jeton sağlayabiliyorsa jeton döndürür. Bu, örneğin bir uygulamanın uygulama başlatılırken akışı gerçekleştirdiği durumlarda veya genel olarak kullanıcı hareketi içermeyen durumlarda yararlıdır.

Önerdiğimiz en iyi uygulama, kullanıcı hareketi olmadığında sessiz modu, kullanıcı hareketi olduğunda (ör. kullanıcı uygulamanızda Giriş yap düğmesini tıkladığında) etkileşimli modu kullanmaktır. Hareket şartını zorunlu kılmadığımızı unutmayın.