OAuth 2.0 sunucusu uygulama

Her Cloud-to-cloud entegrasyonu, kullanıcıların kimliğini doğrulama mekanizması içermelidir.

Kimlik doğrulama, kullanıcılarınızın Google hesaplarını kimlik doğrulama sisteminizdeki kullanıcı hesaplarına bağlamanıza olanak tanır. Bu sayede, yerine getirme işleminiz akıllı ev isteği aldığında kullanıcılarınızı tanımlayabilirsiniz. Google akıllı ev, yalnızca yetkilendirme kodu akışı olan OAuth'u destekler.

Bu sayfada, OAuth 2.0 sunucunuzu Cloud-to-cloud entegrasyonunuzla çalışacak şekilde nasıl ayarlayacağınız açıklanmaktadır.

OAuth ile Google Hesabı Bağlama

Yetkilendirme kodu akışında iki uç noktaya ihtiyacınız vardır:

• Henüz oturum açmamış kullanıcılarınıza oturum açma kullanıcı arayüzünü sunan Yetkilendirme uç noktası. Yetkilendirme uç noktası, kullanıcıların istenen erişim için verdiği izni kaydetmek amacıyla kısa ömürlü bir yetkilendirme kodu da oluşturur.

• İki tür exchange'den sorumlu olan jeton değişimi uç noktası:

  1. Uzun ömürlü yenileme jetonu ve kısa ömürlü bir erişim jetonu için yetkilendirme kodu değiştirir. Bu değişim, kullanıcı hesap bağlama akışını gerçekleştirdiğinde gerçekleşir.
  2. Kısa ömürlü bir erişim jetonu için uzun ömürlü bir yenileme jetonu değiştirir. Bu exchange, süresi dolduğu için Google yeni bir erişim jetonuna ihtiyaç duyduğunda gerçekleşir.

Tasarım yönergeleri

Bu bölümde, OAuth bağlantı akışları için barındırdığınız kullanıcı ekranına yönelik tasarım gereksinimleri ve önerileri açıklanmaktadır. Google'ın uygulaması tarafından çağrıldıktan sonra platformunuz, Google sayfasında oturum açma işlemini ve hesap bağlama izin ekranını kullanıcıya gösterir. Kullanıcı, hesapları bağlamasına izin verdikten sonra tekrar Google'ın uygulamasına yönlendirilir.

Koşullar

1. Kullanıcının hesabının Google Home veya Google Asistan gibi belirli bir Google ürününe değil, Google'a bağlanacağını bildirmeniz gerekir.
2. "Oturum açarak, Google'a cihazlarınızı kontrol etme yetkisi veriyorsunuz" gibi bir Google yetkilendirme beyanınızın olması gerekir. Google Home Geliştirici Politikaları'nın Google Cihaz Kontrolü Yetkilendirmesi bölümüne bakın.
3. Kullanıcıların bağlantı oluşturmak istemedikleri takdirde geri dönebilecekleri veya iptal edebilecekleri bir yöntem sunmanız gerekir.
4. Web OAuth bağlantı sayfasını açmalı ve kullanıcıların, Google Hesaplarında oturum açmak için kullanıcı adı ve şifre alanları gibi net bir yönteme sahip olduğundan emin olmalısınız. Kullanıcıların Web OAuth Bağlantısı sayfasına yönlendirilmeden bağlantı kurmasını sağlayan Google ile Oturum Açma (GSI) yöntemini kullanmayın. Bu durum, Google politikasını ihlal etmektedir.

Öneriler

Aşağıdakileri yapmanızı öneririz:

1. Google'ın Gizlilik Politikası'nı görüntüleyin. İzin ekranına Google'ın Gizlilik Politikası'nın bağlantısını ekleyin.

2. Paylaşılacak veriler. Kullanıcıya Google'ın hangi verileri neden istediğini açıklamak için açık ve net bir dil kullanın.

3. Harekete geçirici mesajın net olması. İzin ekranınızda "Kabul et ve bağla" gibi net bir harekete geçirici mesaj belirtin. Bunun nedeni, kullanıcıların hesaplarını bağlamak için Google ile hangi verileri paylaşmaları gerektiğini anlamalarıdır.

4. Bağlantıyı kaldırma olanağı. Kullanıcılara, bağlantıyı kaldırmaları için platformunuzdaki hesap ayarlarına yönlendiren bir URL gibi bir mekanizma sunun. Alternatif olarak, kullanıcıların bağlı hesaplarını yönetebileceği bir Google Hesabı bağlantısı ekleyebilirsiniz.

5. Kullanıcı hesabı değiştirme olanağı. Kullanıcılara hesaplarını değiştirmeleri için bir yöntem önerin. Bu, özellikle kullanıcılar genellikle birden fazla hesaba sahipse yararlıdır.

   • Bir kullanıcının hesaplar arasında geçiş yapmak için izin ekranını kapatması gerekiyorsa kullanıcının OAuth bağlantısı oluşturma ile istediği hesapta oturum açabilmesi için Google'a kurtarılabilir bir hata gönderin.

6. Logonuzu ekleyin. İzin ekranında şirket logonuzu gösterin. Logonuzu yerleştirmek için stil kurallarınızı kullanın. Google'ın logosunu da görüntülemek istiyorsanız Logolar ve ticari markalar konusuna bakın.

Yetkilendirme kodu akışı

Yetkilendirme kodu akışının OAuth 2.0 sunucu uygulaması, hizmetinizin HTTPS üzerinden kullanıma sunduğu iki uç noktadan oluşur. İlk uç nokta, veri erişimi için kullanıcılardan izin almaktan veya izinleri bulmadan sorumlu olan yetkilendirme uç noktasıdır. Yetkilendirme uç noktası, oturum açmamış kullanıcılarınıza oturum açma kullanıcı arayüzü sunar ve istenen erişime verilen izni kaydeder. İkinci uç nokta, jeton değişimi uç noktasıdır. Bu uç noktası, kullanıcının hizmetinize erişmesine yetki veren, jeton adı verilen şifrelenmiş dizeleri almak için kullanılır.

Bir Google uygulamasının hizmetinizin API'lerinden birini çağırması gerektiğinde Google, bu API'leri kendi adlarına çağırmaları için kullanıcılarınızdan izin almak üzere bu uç noktaları birlikte kullanır.

Google tarafından başlatılan bir OAuth 2.0 yetkilendirme kodu akışı oturumunda aşağıdaki akış geçerlidir:

1. Google, kullanıcının tarayıcısında yetkilendirme uç noktanızı açar. Bir işlem için akış yalnızca sesli cihazda başlatılırsa Google, yürütmeyi bir telefona aktarır.
2. Kullanıcı, henüz oturum açmadıysa oturum açar ve Google'a, API'nizle verilerine erişme izni verir (henüz izin vermediyse).
3. Hizmetiniz bir yetkilendirme kodu oluşturur ve bu kodu Google'a döndürür. Bunun için kullanıcının tarayıcısını, isteğe yetkilendirme kodu eklenmiş şekilde Google'a yönlendirin.
4. Google, yetkilendirme kodunu jeton değişimi uç noktanıza gönderir. Bu uç nokta, kodun özgünlüğünü doğrular ve bir erişim jetonu ile yenileme jetonu döndürür. Erişim jetonu, hizmetinizin API'lere erişmek için kimlik bilgisi olarak kabul ettiği kısa ömürlü bir jetondur. Yenileme jetonu, Google'ın süresi dolan yeni erişim jetonları almak için saklayıp kullanabileceği uzun ömürlü bir jetondur.
5. Kullanıcı hesap bağlama akışını tamamladıktan sonra Google'dan gönderilen her istek bir erişim jetonu içerir.

Yetkilendirme isteklerini işleme

OAuth 2.0 yetkilendirme kodu akışını kullanarak hesap bağlamanız gerektiğinde Google, kullanıcıyı aşağıdaki parametreleri içeren bir istekle yetkilendirme uç noktanıza gönderir:

Örneğin, yetkilendirme uç noktanız https://myservice.example.com/auth adresindeyse bir istek aşağıdaki gibi görünebilir:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

Yetkilendirme uç noktanızın oturum açma isteklerini işleyebilmesi için aşağıdaki adımları uygulayın:

1. client_id değerinin Google'a atadığınız istemci kimliğiyle, redirect_uri değerinin ise hizmetiniz için Google tarafından sağlanan yönlendirme URL'siyle eşleştiğini doğrulayın. Bu kontroller, istemci uygulamalarına istenmeyen veya yanlış yapılandırılmış uygulamalara erişim izni verilmesini önlemek için önemlidir. Birden fazla OAuth 2.0 akışını destekliyorsanız response_type değerinin code olduğunu da onaylayın.
2. Kullanıcının hizmetinizde oturum açıp açmadığını kontrol edin. Kullanıcı oturum açmadıysa hizmetinizin oturum açma veya kaydolma akışını tamamlayın.
3. Google'ın API'nize erişmek için kullanacağı bir yetkilendirme kodu oluşturun. Yetkilendirme kodu herhangi bir dize değeri olabilir ancak kullanıcıyı, jetonun ait olduğu istemciyi ve kodun geçerlilik bitiş zamanını benzersiz şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Genellikle yaklaşık 10 dakika sonra süresi dolan yetkilendirme kodları gönderirsiniz.
4. redirect_uri parametresi tarafından belirtilen URL'nin aşağıdaki biçime sahip olduğunu doğrulayın:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

5. Kullanıcının tarayıcısını redirect_uri parametresi tarafından belirtilen URL'ye yönlendirir. code ve state parametrelerini ekleyerek yönlendirme yaparken, yeni oluşturduğunuz yetkilendirme kodunu ve değiştirilmemiş orijinal durum değerini ekleyin. Aşağıda, elde edilen URL'ye dair bir örnek verilmiştir:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Jeton değişimi isteklerini işleme

Hizmetinizin jeton değişimi uç noktası, iki tür jeton değişiminden sorumludur:

• Yetkilendirme kodlarını erişim jetonları ve yenileme jetonlarıyla değiştirme
• Yenileme jetonlarını erişim jetonlarıyla değiştirme

Jeton değişimi istekleri aşağıdaki parametreleri içerir:

Google'ın kimlik bilgilerini sunucunuza nasıl göndereceğini yapılandırma

Yetkilendirme sunucunuz, uygulanma şekline bağlı olarak istek gövdesinde veya istek başlığında istemci kimlik bilgilerini almayı bekler.

Google, kimlik bilgilerini varsayılan olarak istek gövdesinde gönderir. Yetkilendirme sunucunuz istemci kimlik bilgilerinin istek başlığında olmasını gerektiriyorsa Cloud-to-cloud entegrasyonunuzu buna göre yapılandırmanız gerekir:

Developer Console'a gidin

1. Proje listesinde, üzerinde çalışmak istediğiniz projenin yanındaki Aç'ı tıklayın.

2. Buluttan Buluta bölümünde Geliştir'i seçin.

3. Entegrasyonunuzun yanındaki Aç'ı tıklayın.

4. İzinler (isteğe bağlı) bölümüne gidin ve Google'ın istemci kimliğini ve gizlisini HTTP temel kimlik doğrulama üstbilgisi üzerinden iletmesini sağlayın onay kutusunu işaretleyin.

5. Değişikliklerinizi kaydetmek için Kaydet'i tıklayın.

Yetkilendirme kodlarını erişim jetonları ve yenileme jetonlarıyla değiştirme

Kullanıcı oturum açtıktan ve yetkilendirme uç noktanız Google'a kısa süreli bir yetkilendirme kodu döndürdükten sonra Google, yetkilendirme kodunu bir erişim jetonu ve yenileme jetonuyla değiştirmek için jeton değişimi uç noktanıza bir istek gönderir.

Bu isteklerde grant_type değeri authorization_code, code değeri ise daha önce Google'a verdiğiniz yetkilendirme kodunun değeridir. Aşağıda, yetkilendirme koduyla erişim jetonu ve yenileme jetonu değiş tokuşu yapma isteği örneği verilmiştir:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Yetkilendirme kodlarını erişim jetonu ve yenileme jetonuyla değiştirmek için jeton değişimi uç noktanız, aşağıdaki adımları uygulayarak POST isteklerine yanıt verir:

1. client_id değerinin, istek kaynağını yetkili bir kaynak olarak tanımladığından ve client_secret değerinin beklenen değerle eşleştiğinden emin olun.
2. Yetkilendirme kodunun geçerli ve süresinin dolmadığını ve isteğinde belirtilen istemci kimliğinin, yetkilendirme koduyla ilişkili istemci kimliğiyle eşleştiğini doğrulayın.
3. redirect_uri parametresi tarafından belirtilen URL'nin, ilk yetkilendirme isteğinde kullanılan değerle aynı olduğunu onaylayın.
4. Yukarıdaki ölçütlerin tümünü doğrulayamazsanız gövdesi {"error": "invalid_grant"} olan bir HTTP 400 Hatalı İstek hatası döndürün.
5. Aksi takdirde, yenileme jetonu ve erişim jetonu oluşturmak için yetkilendirme kodundaki kullanıcı kimliğini kullanın. Bu jetonlar herhangi bir dize değeri olabilir ancak kullanıcıyı ve jetonun kullanılacağı istemciyi benzersiz şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Erişim jetonları için jetonun geçerlilik bitiş zamanını da kaydedin. Bu zaman genellikle jetonu yayınladıktan bir saat sonradır. Yenileme jetonlarının süresi dolmaz.
6. HTTPS yanıtının gövdesinde aşağıdaki JSON nesnesini döndürün:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Google, kullanıcının erişim jetonunu ve yenileme jetonunu depolar ve erişim jetonunun süresinin dolduğunu kaydeder. Erişim jetonunun süresi dolduğunda Google, jeton değişimi uç noktanızdan yeni bir erişim jetonu almak için yenileme jetonunu kullanır.

Yenileme jetonlarını erişim jetonlarıyla değiştirme

Bir erişim jetonunun süresi dolduğunda Google, yenileme jetonunu yeni bir erişim jetonuyla değiştirmek için jeton değişimi uç noktanıza bir istek gönderir.

Bu isteklerde grant_type değeri refresh_token, refresh_token değeri ise daha önce Google'a verdiğiniz yenileme jetonunun değeridir. Aşağıda, yenileme jetonunu erişim jetonuyla değiştirme isteği örneği verilmiştir:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Yenileme jetonunu erişim jetonuyla değiştirmek için jeton değişimi uç noktanız, aşağıdaki adımları uygulayarak POST isteklerine yanıt verir:

1. client_id değerinin istek kaynağını Google olarak tanımladığından ve client_secret değerinin beklenen değerle eşleştiğinden emin olun.
2. Yenileme jetonunun geçerli olup olmadığını ve istekte belirtilen istemci kimliğinin, yenileme jetonuyla ilişkili istemci kimliğiyle eşleşip eşleşmediğini doğrulayın.
3. Yukarıdaki ölçütlerin tümünü doğrulayamazsanız gövdesi {"error": "invalid_grant"} olan bir HTTP 400 Kötü İstek hatası döndürün.
4. Aksi takdirde, erişim jetonu oluşturmak için yenileme jetonundaki kullanıcı kimliğini kullanın. Bu jetonlar herhangi bir dize değeri olabilir ancak kullanıcıyı ve jetonun kullanılacağı istemciyi benzersiz şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Erişim jetonları için jetonun geçerlilik bitiş zamanını da (genellikle jetonu verdikten bir saat sonra) kaydedin.
5. HTTPS yanıtının gövdesinde aşağıdaki JSON nesnesini döndürün:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Kullanıcı bilgileri isteklerini işleme

userinfo uç noktası, bağlı kullanıcıyla ilgili hak taleplerini döndüren, OAuth 2.0 korumalı bir kaynaktır. Kullanıcı bilgileri uç noktasını uygulamak ve barındırmak, aşağıdaki kullanım alanları hariç isteğe bağlıdır:

• Google One Tap ile Bağlı Hesapta Oturum Açma.
• AndroidTV'de sorunsuz abonelik.

Erişim jetonu, jeton uç noktanızdan başarıyla alındıktan sonra Google, bağlı kullanıcıyla ilgili temel profil bilgilerini almak için kullanıcı bilgileri uç noktanıza bir istek gönderir.

Örneğin, kullanıcı bilgileri uç noktanız https://myservice.example.com/userinfo, talep aşağıdaki gibi görünebilir:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Kullanıcı bilgileri uç noktanızın istekleri işlemesi için aşağıdaki adımları uygulayın:

1. Yetkilendirme başlığından erişim jetonunu çıkarın ve erişim jetonuyla ilişkilendirilmiş kullanıcının bilgilerini döndürün.
2. Erişim jetonu geçersizse WWW-Authenticate yanıt üstbilgisini kullanarak HTTP 401 Yetkilendirilmemiş hatası döndürün. Aşağıda kullanıcı bilgileri hata yanıtı örneği verilmiştir:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   . Bağlama işlemi sırasında 401 Yetkilendirilmedi veya başka bir başarısız hata yanıtı döndürülürse bu hata düzeltilemez, alınan jeton silinir ve kullanıcının bağlantı oluşturma işlemini yeniden başlatması gerekir.

3. Erişim jetonu geçerliyse HTTPS gövdesinde aşağıdaki JSON nesnesiyle HTTP 200 yanıtını döndürün ve HTTP 200 yanıtını alın yanıt:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }
   

   Kullanıcı bilgileri uç noktanız HTTP 200 başarılı yanıtı döndürürse alınan jeton ve hak talepleri kullanıcının Google Hesabı'na kaydedilir.

   userinfo uç nokta yanıtı
   sub	Sisteminizdeki kullanıcıyı tanımlayan benzersiz bir kimlik.
   email	Kullanıcının e-posta adresi.
   given_name	İsteğe bağlı: Kullanıcının adı.
   family_name	İsteğe bağlı: Kullanıcının soyadı.
   name	İsteğe bağlı: Kullanıcının tam adı.
   picture	İsteğe bağlı: Kullanıcının profil resmi.