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ıyla bağlamanıza olanak tanır. Bu sayede, karşılamanız bir akıllı ev amacı aldığında kullanıcılarınızı tanımlayabilirsiniz. Google akıllı ev yalnızca yetkilendirme kodu akışıyla 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ğlantısı

Yetkilendirme kodu akışında iki uç nokta gerekir:

• Oturum açmamış kullanıcılarınıza oturum açma kullanıcı arayüzünü sunan yetkilendirme uç noktası. Yetkilendirme uç noktası, istenen erişime kullanıcıların iznini kaydetmek için kısa ömürlü bir yetkilendirme kodu da oluşturur.

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

  1. Yetkilendirme kodunu uzun ömürlü bir yenileme jetonu ve kısa ömürlü bir erişim jetonuyla değiştirir. Bu değişim, kullanıcı hesap bağlama akışından geçtiğinde gerçekleşir.
  2. Uzun ömürlü bir yenileme jetonunu kısa ömürlü bir erişim jetonuyla değiştirir. Bu değişim, Google'ın elindeki erişim jetonunun süresi dolduğu için 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ıyla ilgili tasarım koşulları ve önerileri açıklanmaktadır. Google'ın uygulaması tarafından çağrıldıktan sonra platformunuz, kullanıcıya Google'da oturum açma sayfasını ve hesap bağlama izni ekranını gösterir. Kullanıcı, hesapları bağlamayı kabul ettikten sonra Google'ın uygulamasına geri yönlendirilir.

Şartlar

1. Kullanıcı hesabının Google Home veya Google Asistan gibi belirli bir Google ürününe değil Google'a bağlanacağını belirtmeniz gerekir.
2. "Oturum açarak Google'ın cihazlarınızı kontrol etmesine yetki veriyorsunuz." gibi bir Google yetkilendirme beyanınız olmalıdır. Google Home Geliştirici Politikaları'nın Google Cihaz Kontrolü Yetkilendirme bölümüne bakın.
3. Web OAuth bağlantı oluşturma sayfasını açmanız ve kullanıcıların Google Hesaplarında oturum açmak için net bir yönteme sahip olmasını sağlamanız gerekir. Örneğin, kullanıcı adı ve şifre alanları gibi. Kullanıcıların Web OAuth Bağlantısı sayfasına yönlendirilmeden bağlantı oluşturmasına olanak tanıyan Google ile Oturum Açma (GSI) yöntemini kullanmayın. Bu durum, Google politikasının ihlalidir.
4. Kullanıcının bağlandığı entegrasyonu belirtmek için OAuth bağlama sayfasına aşağıdaki öğelerden en az birini eklemeniz gerekir:
   • Şirket logosu
   • Şirket adı
   • Entegrasyon adı
   • Uygulama simgesi

Öneriler

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

1. Google'ın Gizlilik Politikası'nı gösterin. Kullanıcı rızası ekranına Google'ın Gizlilik Politikası'nın bağlantısını ekleyin.

2. Paylaşılacak veriler. Kullanıcıya, Google'ın hangi verilerini neden istediğini ve hangi kullanım ya da etkileşim verilerinin Google tarafından sizinle paylaşılabileceğini açık ve net bir dille anlatın.

3. Net harekete geçirici mesaj. İ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. İptal etme imkanı. Bağlantı oluşturmayı tercih etmeyen kullanıcılara geri dönme veya işlemi iptal etme olanağı tanıyın.

5. Net oturum açma süreci. Kullanıcıların Google Hesaplarında oturum açmak için net bir yöntemi olduğundan emin olun. Örneğin, kullanıcı adı ve şifre alanları veya Google ile oturum açma.

6. Bağlantıyı kaldırma özelliği. Kullanıcılara bağlantıyı kaldırma mekanizması sunun. Örneğin, platformunuzdaki hesap ayarlarına yönlendiren bir URL. Alternatif olarak, kullanıcıların bağlı hesaplarını yönetebileceği Google Hesabı'na bir bağlantı ekleyebilirsiniz. Bir kullanıcı entegrasyonunuzun bağlantısını kaldırırsa Google'ı bu değişiklikten haberdar etmek için agentUsers.delete kullanın.

7. Kullanıcı hesabını değiştirme Kullanıcılara hesaplarını değiştirmeleri için bir yöntem önerin. Bu özellik, özellikle kullanıcıların birden fazla hesabı olduğu durumlarda faydalıdır.

   • Kullanıcının hesap değiştirmek için kullanıcı rızası ekranını kapatması gerekiyorsa Google'a kurtarılabilir bir hata gönderin. Böylece kullanıcı, OAuth bağlantısı ile istediği hesapta oturum açabilir.

8. Logonuzu ekleyin. Kullanıcı rızası ekranında şirket logonuzu gösterin. Logonuzu yerleştirmek için stil kurallarınızı kullanın. Google'ın logosunu da göstermek istiyorsanız Logolar ve ticari markalar bölümüne bakın.

Yetkilendirme kodu akışı

Yetkilendirme kodu akışının OAuth 2.0 sunucu uygulaması, hizmetinizin HTTPS üzerinden kullanılabilir hale getirdiği iki uç noktadan oluşur. İlk uç nokta, yetkilendirme uç noktasıdır. Bu uç nokta, veri erişimi için kullanıcılardan izin bulmaktan veya almaktan sorumludur. Yetkilendirme uç noktası, henüz oturum açmamış kullanıcılarınıza bir oturum açma kullanıcı arayüzü sunar ve istenen erişim için izin kaydeder. İkinci uç nokta, jeton değişimi uç noktasıdır. Bu uç nokta, kullanıcının hizmetinize erişmesine izin veren ve 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, kullanıcılarınızdan bu API'leri kullanıcılar adına çağırma izni almak için bu uç noktaları birlikte kullanır.

Google tarafından başlatılan bir OAuth 2.0 yetkilendirme kodu akışı oturumu aşağıdaki akışa sahiptir:

1. Google, kullanıcının tarayıcısında yetkilendirme uç noktanızı açar. Akış, bir işlem için yalnızca sesli bir cihazda başladıysa Google, yürütmeyi bir telefona aktarır.
2. Kullanıcı oturum açmamışsa oturum açar ve daha önce izin vermediyse Google'a API'nizle verilerine erişme izni verir.
3. Hizmetiniz bir yetkilendirme kodu oluşturur ve bunu Google'a döndürür. Bunun için kullanıcının tarayıcısını, isteğe eklenmiş yetkilendirme koduyla birlikte Google'a yönlendirin.
4. Google, yetkilendirme kodunu jeton değiş tokuşu uç noktanıza gönderir. Bu uç nokta, kodun gerçekliğ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 bilgisi olarak kabul ettiği kısa ömürlü bir jetondur. Yenileme jetonu, Google'ın depolayabileceği ve süresi dolduğunda 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 istek bir erişim jetonu içerir.

Yetkilendirme isteklerini işleme

OAuth 2.0 yetkilendirme kodu akışını kullanarak hesap bağlama işlemi yapmanı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 adresinde kullanılabiliyorsa 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

Yetkilendirme uç noktanızın oturum açma isteklerini işlemesi 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 Google'ın hizmetiniz için sağladığı 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 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 bir şekilde temsil etmeli ve tahmin edilememelidir. Genellikle yaklaşık 10 dakika sonra geçerliliğini yitiren yetkilendirme kodları yayınlarsınız.
4. redirect_uri parametresi tarafından belirtilen URL'nin aşağıdaki biçimde olduğunu onaylayı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 parametresiyle belirtilen URL'ye yönlendirin. Yönlendirme yaparken code ve state parametrelerini ekleyerek yeni oluşturduğunuz yetkilendirme kodunu ve orijinal, değiştirilmemiş 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:

• Erişim jetonları ve yenileme jetonları için yetkilendirme kodlarını 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 sunucunuza kimlik bilgilerini nasıl göndereceğini yapılandırma

Uygulanma şekline bağlı olarak yetkilendirme sunucunuz, istemci kimlik bilgilerini istek gövdesinde veya istek başlığında 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. Cloud-to-Cloud bölümünde Develop'ı (Geliştir) seçin.

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

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

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

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

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

Bu istekler için grant_type değeri authorization_code, code değeri ise daha önce Google'a verdiğiniz yetkilendirme kodunun değeridir. Aşağıda, bir yetkilendirme kodunu erişim jetonu ve yenileme jetonuyla değiştirmek için gönderilen istek ö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ı bir erişim jetonu ve yenileme jetonuyla değiştirmek için jeton değiş tokuşu uç noktanız, aşağıdaki adımları uygulayarak POST isteklerine yanıt verir:

1. client_id, istek kaynağını yetkili bir kaynak olarak tanımlamalı ve client_secret, beklenen değerle eşleşmelidir.
2. Yetkilendirme kodunun geçerli ve süresinin dolmamış olduğunu ve istekte 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ö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 jetonun ait olduğu kullanıcıyı ve istemciyi benzersiz bir şekilde temsil etmeli ve tahmin edilemez olmalıdır. Erişim jetonları için jetonun sona erme zamanını da kaydedin. Bu süre genellikle jetonu oluşturduktan 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ı için erişim jetonunu ve yenileme jetonunu depolar ve erişim jetonunun geçerlilik bitiş tarihini kaydeder. Erişim jetonunun süresi dolduğunda Google, jeton değişim 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şim uç noktanıza 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ştirmek için gönderilen bir istek ö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, istek 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şkili istemci kimliğiyle eşleştiğini doğrulayın.
3. Yukarıdaki ölçütlerin tümünü doğrulayamazsanı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 jetonun ait olduğu kullanıcıyı ve istemciyi benzersiz bir şekilde temsil etmeli ve tahmin edilemez olmalıdır. Erişim jetonları için jetonun geçerlilik bitiş zamanını da kaydedin. Bu süre genellikle jetonu oluşturduktan bir saat sonradır.
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.