iOS ve masaüstü uygulamaları için OAuth 2.0

Bu belgede, telefon, tablet ve bilgisayar gibi cihazlara yüklenen uygulamaların Google API'lerine erişimi yetkilendirmek için Google'ın OAuth 2.0 uç noktalarını nasıl kullandığı 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ına dosya depolamak için OAuth 2.0'ı kullanarak izin alabilir.

Yüklenen uygulamalar tek tek cihazlara dağıtılır ve bu uygulamaların sır tutamayacağı varsayılır. Kullanıcı uygulamada bulunurken veya uygulama arka planda çalışırken Google API'lerine erişebilirler.

Bu yetkilendirme akışı, web sunucusu uygulamaları için kullanılan akışa benzer. Aradaki temel fark, yüklenen uygulamaların sistem tarayıcısını açması ve Google'ın yetkilendirme sunucusundan gelen yanıtları işlemek için yerel bir yönlendirme URI'si sağlaması gerektiğidir.

Kitaplıklar ve örnekler

iOS uygulamaları için Google ile Oturum Açma iOS SDK'sının en son sürümünü kullanmanızı öneririz. SDK, kullanıcı yetkilendirmesini yönetir ve bu kılavuzda açıklanan alt düzey protokole kıyasla uygulaması daha kolaydır.

Sistem tarayıcısını desteklemeyen veya sınırlı giriş özelliklerine sahip cihazlarda (ör. TV'ler, oyun konsolları, kameralar ya da yazıcılar) çalışan uygulamalar için TV'ler ve Cihazlar İçin OAuth 2.0 veya TV'lerde ve Sınırlı Giriş Cihazlarında Oturum Açma başlıklı makaleyi inceleyin.

Ön koşullar

Projeniz için API'leri etkinleştirme

Google API'lerini çağıran tüm uygulamaların bu API'leri API Konsolu'nda etkinleştirmesi gerekir.

Projenizde bir API'yi etkinleştirmek için:

  1. Google API Konsolu'nda API kitaplığını açın.
  2. İstenirse bir proje seçin veya yeni bir proje oluşturun.
  3. API kitaplığında, ürün ailesine ve popülerliğe göre gruplandırılmış tüm API'ler listelenir. Etkinleştirmek istediğiniz API listede görünmüyorsa arama özelliğini kullanarak API'yi bulun veya ait olduğu ürün ailesinde Tümünü Göster'i tıklayın.
  4. Etkinleştirmek istediğiniz API'yi seçin ve Etkinleştir düğmesini tıklayın.
  5. İstenirse faturalandırmayı etkinleştirin.
  6. İ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 uygulamalarda, uygulamayı Google'ın OAuth 2.0 sunucusuna tanıtan yetkilendirme kimlik bilgileri olmalıdır. Aşağıdaki adımlarda, projeniz için kimlik bilgilerinin nasıl oluşturulacağı açıklanmaktadır. Uygulamalarınız daha sonra bu kimlik bilgilerini kullanarak söz konusu proje için etkinleştirdiğiniz API'lere erişebilir.

  1. Müşteriler sayfasına gidin.
  2. Create client'ı (İstemci oluştur) tıklayın.
  3. Aşağıdaki bölümlerde, Google'ın yetkilendirme sunucusunun desteklediği istemci türleri açıklanmaktadır. Uygulamanız için önerilen istemci türünü seçin, OAuth istemcinizi adlandırın ve formdaki diğer alanları uygun şekilde ayarlayın.
iOS
  1. iOS uygulama türünü seçin.
  2. OAuth istemcisi için bir ad girin. Bu ad, müşteriyi tanımlamak için projenizin Müşteriler sayfasında gösterilir.
  3. Uygulamanızın paket kimliğini girin. Paket kimliği, uygulamanızın bilgi özelliği listesi kaynak dosyasındaki (info.plist) CFBundleIdentifier anahtarının değeridir. Değer en yaygın olarak Xcode proje düzenleyicisinin Genel bölmesinde veya İmzalama ve Yetenekler bölmesinde gösterilir. Paket kimliği, Apple'ın App Store Connect sitesindeki uygulamanın Uygulama Bilgileri sayfasının Genel Bilgiler bölümünde de gösterilir.

    Uygulama Kontrolü özelliğini kullanıyorsanız daha sonra değiştiremeyeceğiniz için uygulamanız için doğru paket kimliğini kullandığınızı onaylayın.

  4. (İsteğe bağlı)

    Uygulama Apple'ın App Store'unda yayınlanmışsa uygulamanızın App Store kimliğini girin. Mağaza kimliği, her Apple App Store URL'sinde bulunan sayısal bir dizedir.

    1. iOS veya iPadOS cihazınızda Apple App Store uygulamasını açın.
    2. Uygulamanızı arayın.
    3. Paylaş düğmesini (kare ve yukarı ok simgesi) seçin.
    4. Bağlantıyı kopyala'yı seçin.
    5. Bağlantıyı bir metin düzenleyiciye yapıştırın. App Store kimliği, URL'nin son kısmıdır.

      Örnek: https://apps.apple.com/app/google/id284815942

  5. (İsteğe bağlı)

    Ekip kimliğinizi girin. Daha fazla bilgi için Apple Developer Account belgelerindeki Locate your Team ID (Ekip Kimliğinizi Bulma) başlıklı makaleyi inceleyin.

    Not: Müşteriniz için Uygulama Denetimi'ni etkinleştiriyorsanız Takım Kimliği alanı zorunludur.
  6. (İsteğe bağlı)

    iOS uygulamanızda Uygulama Kontrolü'nü etkinleştirin. Uygulama Kontrolü'nü etkinleştirdiğinizde, OAuth istemcinizden gelen OAuth 2.0 isteklerinin orijinal olduğunu ve uygulamanızdan geldiğini doğrulamak için Apple'ın App Attest hizmeti kullanılır. Bu, uygulamanın kimliğine bürünme riskini azaltmaya yardımcı olur. iOS uygulamanızda Uygulama Kontrolü'nü etkinleştirme hakkında daha fazla bilgi edinin.

  7. Oluştur'u tıklayın.
UWP
  1. Evrensel Windows Platformu uygulama türünü seçin.
  2. OAuth istemcisi için bir ad girin. Bu ad, müşteriyi tanımlamak için projenizin bölümünde gösterilir.
  3. Uygulamanızın 12 karakterli Microsoft Store kimliğini girin. Bu değeri, Microsoft İş Ortağı Merkezi'ndeki Uygulama yönetimi bölümünün Uygulama kimliği sayfasında bulabilirsiniz.
  4. Oluştur'u tıklayın.

UWP uygulamalarında yönlendirme URI'si, uygulamanızın benzersiz Paket Güvenliği Tanımlayıcısı (SID) kullanılarak oluşturulur. Uygulamanızın Package SID değerini Visual Studio projenizdeki Package.appxmanifest dosyasında bulabilirsiniz.

Google Cloud Console'da istemci kimliğinizi oluştururken yönlendirme URI'sini aşağıdaki biçimde belirtmeniz gerekir. Bu biçimde, Paket SID'nizin küçük harfli değerini kullanın: 

ms-app://YOUR_APP_PACKAGE_SID

UWP uygulamalarında, özel URI şeması Microsoft belgelerinde belirtildiği gibi 39 karakterden uzun olamaz.

Erişim kapsamlarını belirleme

Kapsamlar, uygulamanızın yalnızca ihtiyaç duyduğu kaynaklara erişim isteğinde bulunmasını sağlar. Ayrıca, kullanıcıların uygulamanıza verdiği erişim miktarını kontrol etmesine de olanak tanır. Bu nedenle, istenen kapsam sayısı ile kullanıcı izni alma olasılığı arasında ters bir ilişki olabilir.

OAuth 2.0 yetkilendirmesini uygulamaya başlamadan önce, uygulamanızın erişim izni gerektireceği 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ını edinme

Aşağıdaki adımlarda, uygulamanızın kullanıcı adına bir API isteği gerçekleştirmek için kullanıcının iznini almak üzere Google'ın OAuth 2.0 sunucusuyla nasıl etkileşimde bulunduğu gösterilmektedir. Uygulamanızın, kullanıcı yetkilendirmesi gerektiren bir Google API isteğini yürütmeden önce bu izni almış olması gerekir.

1. adım: Bir kod doğrulayıcı ve sorgu oluşturun

Google, yüklenen uygulama akışını daha güvenli hale getirmek için Proof Key for Code Exchange (PKCE) protokolünü destekler. Her yetkilendirme isteği için benzersiz bir kod doğrulayıcı oluşturulur ve "code_challenge" adı verilen dönüştürülmüş değeri, yetkilendirme kodunu almak için yetkilendirme sunucusuna gönderilir.

Kod doğrulayıcıyı oluşturma

code_verifier, ayrılmamış karakterler [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" kullanılarak oluşturulan, yüksek entropili bir kriptografik rastgele dizedir. Minimum uzunluğu 43 karakter, maksimum uzunluğu ise 128 karakterdir.

Kod doğrulayıcı, değeri tahmin etmeyi pratik olmayacak kadar zorlaştıracak kadar entropiye sahip olmalıdır.

Kod doğrulamasını oluşturma

Kod zorluğu oluşturmak için iki yöntem desteklenir.

Code Challenge Oluşturma Yöntemleri
S256 (önerilen) Kod sorgulaması, kod doğrulayıcının Base64URL (doldurma olmadan) kodlamalı SHA256 karmasıdır.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain Kod zorluğu, yukarıda oluşturulan kod doğrulayıcı ile aynı değere sahiptir.
code_challenge = code_verifier

2. adım: Google'ın OAuth 2.0 sunucusuna istek gönderin

Kullanıcı yetkilendirmesi almak için https://accounts.google.com/o/oauth2/v2/auth adresindeki Google'ın yetkilendirme sunucusuna istek gönderin. Bu uç nokta, etkin oturum aramasını işler, kullanıcının kimliğini doğrular ve kullanıcı iznini alır. Uç noktaya yalnızca SSL üzerinden erişilebilir ve HTTP (SSL olmayan) bağlantıları reddeder.

Yetkilendirme sunucusu, yüklü 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

Google'ın yetkilendirme sunucusunun uygulamanıza nasıl yanıt göndereceğini belirler. Yüklü uygulamalar için çeşitli yönlendirme seçenekleri mevcuttur ve yetkilendirme kimlik bilgilerinizi belirli bir yönlendirme yöntemini göz önünde bulundurarak ayarlamış olursunuz.

Değer, istemcinizin Cloud Console'daki İstemciler sayfasında yapılandırdığınız OAuth 2.0 istemcisinin yetkili yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir. Bu değer yetkili bir URI ile eşleşmezse redirect_uri_mismatch hatası alırsınız.

Tabloda, her yöntem için uygun redirect_uri parametre değeri gösterilmektedir:

redirect_uri değerleri
Özel URI şeması com.example.app:redirect_uri_path

veya

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app, kontrolünüzdeki bir alanın ters DNS gösterimidir. Özel şemanın geçerli olması için nokta içermesi gerekir.
  • com.googleusercontent.apps.123, istemci kimliğinin ters DNS gösterimidir.
  • redirect_uri_path, /oauth2redirect gibi isteğe bağlı bir yol bileşenidir. Yolun, normal HTTP URL'lerinden farklı olarak tek bir eğik çizgiyle başlaması gerektiğini unutmayın.
Loopback IP adresi http://127.0.0.1:port veya http://[::1]:port

Platformunuzda ilgili geri döngü IP adresini sorgulayın ve rastgele kullanılabilir bir bağlantı noktasında HTTP dinleyicisi başlatın. port yerine uygulamanızın dinlediği gerçek bağlantı noktası numarasını girin.

Mobil uygulamalarda geri döngü IP adresi yönlendirme seçeneği desteğinin KULLANIMDAN KALDIRILDIĞINI unutmayın.
response_type Zorunlu

Google OAuth 2.0 uç noktasının yetkilendirme kodu döndürüp döndürmeyeceğini belirler.

Yüklü uygulamalar için parametre değerini code olarak ayarlayın.
scope Zorunlu

Uygulamanızın kullanıcı adına erişebileceği kaynakları tanımlayan, boşlukla ayrılmış bir 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ğlar. Ayrıca, kullanıcıların uygulamanıza verdiği erişim miktarını kontrol etmesine de olanak tanır. Bu nedenle, istenen kapsam sayısı ile kullanıcı izni alma olasılığı arasında ters orantı vardır.
code_challenge