OAuth 2.0 sunucusu uygulama

Her smart home işlemi, kullanıcıların kimliklerini doğrulayan bir mekanizma içermelidir.

Kimlik doğrulama, kullanıcılarınızın Google hesaplarını kimlik doğrulama sisteminizdeki kullanıcı hesaplarına bağlamanızı sağlar. Bu sayede, siparişleriniz akıllı ev amacı aldığında kullanıcılarınızı belirleyebilirsiniz. Google akıllı ev, yalnızca yetkilendirme kodu akışıyla OAuth'u destekler.

Bu sayfada, OAuth 2.0 sunucunuzu smart home İşleminizle ç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 sunucusu uygulaması, hizmetinizin HTTPS tarafından kullanıma sunulduğu iki uç noktadan oluşur. İlk uç nokta, veri erişimi için kullanıcılardan izin almak veya izin almaktan sorumlu yetkilendirme uç noktasıdır. Yetkilendirme uç noktası, kullanıcılarınıza halihazırda oturum açmamış bir oturum açma kullanıcı arayüzü sunar ve istenen erişim için izni kaydeder. İkinci uç nokta, kullanıcının hizmetinize erişme yetkisi veren şifrelenmiş dizeler olarak adlandırılan jeton değişimi uç noktasıdır.

Bir Google uygulamasının, hizmetinizin API'lerinden birini çağırması gerektiğinde, kullanıcılarınızdan bu API'leri onlar adına çağırmak için bu uç noktaları birlikte kullanır.

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

1. Google, yetkilendirme uç noktasını kullanıcının tarayıcısında açar. Akış bir Action için yalnızca sesli cihazda başlatılmışsa Google, yürütme işlemini bir telefona aktarır.
2. Kullanıcı henüz oturum açmamışsa oturum açar ve henüz izin vermemişse Google'a API'nizle verilerine erişme izni verir.
3. Hizmetiniz bir yetkilendirme kodu oluşturur ve Google'a geri gönderir. Bunu yapmak için kullanıcının tarayıcısını, isteğe eklenmiş yetkilendirme koduyla Google'a yönlendirin.
4. Google, yetkilendirme kodunu jeton exchange uç noktanıza gönderir. Bu, kodun orijinalliğini 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 bilgileri olarak kabul ettiği kısa ömürlü bir jetondur. Yenileme jetonu, Google'ın depoladığı ve yeni erişim jetonları almak için kullanabileceği uzun ömürlü bir jetondur.
5. Kullanıcı hesap bağlama akışını tamamladıktan sonra, Google'dan gönderilen her istekte bir erişim jetonu bulunur.

Yetkilendirme isteklerini işleme

OAuth 2.0 yetkilendirme kodu akışını kullanarak hesap bağlama işlemi gerçekleştirmeniz gerektiğinde Google, aşağıdaki parametreleri içeren bir isteği içeren kullanıcıyı yetkilendirme uç noktanıza gönderir:

Yetkilendirme uç noktası parametreleri
client_id	Google'a atadığınız İstemci Kimliği.
redirect_uri	Bu isteğe yanıt gönderdiğiniz URL.
state	Yönlendirme URI'sında değişiklik olmadan Google'a geri aktarılan bir muhasebe değeri.
scope	İsteğe bağlı: Google'ın yetkilendirme istediği verileri belirten, boşlukla sınırlandırılmış bir kapsam dizeleri grubu.
response_type	Yanıtta döndürülecek değerin türü. OAuth 2.0 yetkilendirme kodu akışı için yanıt türü her zaman code'dir.
user_locale	İçeriğinizi kullanıcının tercih ettiği dilde yerelleştirmek için RFC5646 biçimindeki Google Hesabı dil ayarı.

Örneğin, yetkilendirme uç noktanız https://myservice.example.com/auth adresinde kullanılabiliyorsa 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şlemesi için aşağıdaki adımları uygulayın:

1. client_id öğesinin, Google'a atadığınız İstemci Kimliği ile ve redirect_uri hizmetinin, hizmetiniz için Google tarafından sağlanan yönlendirme URL'siyle eşleştiğini doğrulayın. Bu kontroller, istenmeyen veya yanlış yapılandırılmış istemci uygulamalarına erişim izni verilmesini önlemek için önemlidir. Birden fazla OAuth 2.0 akışını destekliyorsanız response_type öğesinin code olduğunu da onaylayın.
2. Kullanıcının hizmetinizde oturum açıp açmadığını kontrol edin. Kullanıcı oturum açmamışsa 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 istemcisini, kodun kullanım süresini ve kodun son kullanma tarihini benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Genellikle yaklaşık 10 dakika sonra sona eren yetkilendirme kodları yayınlarsınız.
4. redirect_uri parametresi tarafından belirtilen URL'nin aşağıdaki biçimde 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önlendirin. Yönlendirme yaparken code ve state parametrelerini ekleyerek, oluşturduğunuz yetkilendirme kodunu ve değiştirilmemiş orijinal durum değerini ekleyin. Elde edilen URL'nin bir örneğini aşağıda görebilirsiniz:

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

Jeton değişimi isteklerini işleme

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

• Erişim jetonları ve yenileme jetonları için yetkilendirme kodlarını değiştirme
• Erişim jetonları için exchange yenileme jetonları

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

Jeton değişimi uç nokta parametreleri
client_id	İstek kaynağını Google olarak tanımlayan bir dize. Bu dize, sisteminizde Google’ın benzersiz tanımlayıcısı olarak kaydedilmelidir.
client_secret	Hizmetiniz için Google'a kaydettiğiniz gizli dize.
grant_type	Alınan jetonun türü. authorization_code veya refresh_token şeklindedir.
code	grant_type=authorization_code olduğunda, bu parametre Google'ın oturum açma veya jeton değişimi uç noktanızdan aldığı koddur.
redirect_uri	grant_type=authorization_code olduğunda bu parametre, ilk yetkilendirme isteğinde kullanılan URL'dir.
refresh_token	grant_type=refresh_token olduğunda bu parametre, Google'ın jeton takas uç noktanızdan aldığı yenileme jetonudur.

Erişim jetonları ve yenileme jetonları için yetkilendirme kodlarını değiştirme

Kullanıcı oturum açıp yetkilendirme uç noktanız Google'a kısa ömürlü bir yetkilendirme kodu döndürdükten sonra Google, jeton Exchange uç ucunuza bir erişim jetonu ve yenileme jetonuyla yetkilendirme kodu değişimi için 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, bir erişim jetonu ve yenileme jetonu için yetkilendirme kodu değişimi 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

Bir erişim jetonu ve yenileme jetonu için yetkilendirme kodları alışverişi yapmak üzere, jeton değişimi uç noktanız aşağıdaki adımları yürüterek POST isteklerine yanıt verir:

1. client_id öğesinin, istek kaynağını yetkili bir kaynak olarak tanımladığını ve client_secret değerinin beklenen değerle eşleştiğini doğrulayın.
2. Yetkilendirme kodunun geçerli olduğunu, geçerlilik süresinin dolmadığını ve istekte belirtilen istemci kimliğinin, yetkilendirme koduyla ilişkilendirilen 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 tamamını doğrulayamıyorsanız gövde olarak {"error": "invalid_grant"} ile 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 jeton, kullanıcıyı ve jetonun ait olduğu istemciyi benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Erişim jetonları için, jetonun geçerlilik süresini de kaydedin. Bu, genellikle jetonun düzenlenmesinin ardından bir saat sürer. 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, erişim jetonunu ve yenileme jetonunu kullanıcı için depolar ve erişim jetonunun geçerlilik süresini kaydeder. Erişim jetonunun süresi dolduğunda Google, jeton jetonunuzu yeni bir erişim jetonu almak için yenileme jetonunu kullanır.

Erişim jetonları için exchange yenileme jetonları

Bir erişim jetonunun süresi dolduğunda Google, jeton Exchange uç noktanıza yeni bir erişim jetonu için yenileme jetonu karşılığında 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, bir erişim jetonuyla yenileme jetonu alma isteğinin bir ö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

Bir erişim jetonuyla yenileme jetonunu 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 öğesinin, isteğin kaynağını Google olarak tanımladığını ve client_secret değerinin beklenen değerle eşleştiğini doğrulayın.
2. Yenileme jetonunun geçerli olduğunu ve istekte belirtilen istemci kimliğinin, yenileme jetonuyla ilişkilendirilen istemci kimliğiyle eşleştiğini doğrulayın.
3. Yukarıdaki ölçütlerin tamamını doğrulayamıyorsanız gövde olarak {"error": "invalid_grant"} ile bir HTTP 400 Hatalı İ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 bu jeton, kullanıcıyı ve jetonun ait olduğu istemciyi benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Erişim jetonları için, jetonun geçerlilik süresini de (genellikle jetonu vermenizin ardından bir saat) 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ı bilgisi isteklerini işleme

Userinfo uç noktası, bağlı kullanıcıyla ilgili hak talepleri döndüren OAuth 2.0 korumalı bir kaynaktır. Aşağıdaki kullanım alanları hariç, kullanıcı bilgileri uç noktasını uygulama ve barındırma 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.

kullanıcı bilgisi uç nokta isteği üstbilgileri
Authorization header	Taşıyıcı türünün erişim jetonu.

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

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

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

1. Erişim jetonunu Yetkilendirme başlığından çıkarın ve erişim jetonuyla ilişkilendirilmiş kullanıcı için bilgileri döndürün.
2. Erişim jetonu geçersizse WWW-Authenticate Yanıt Başlığı ile HTTP 401 Yetkisiz hatası döndürün. Kullanıcı bilgisi hata yanıtı örneği:

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

   Bağlantı oluşturma işlemi sırasında 401 Yetkilendirilmediyse veya başka bir hata yanıtı döndürülürse hata kurtarılamaz. Alınan jeton silinir ve kullanıcının bağlantı işlemini yeniden başlatması gerekir.

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

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

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

   kullanıcı bilgisi 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.