OAuth ile hesap bağlama

OAuth bağlama türü, sektör standardı olan iki OAuth 2.0 akışını (örtük ve yetkilendirme kod akışı) destekler.

Dolaylı kod akışında Google, yetkilendirme uç noktanızı kullanıcının tarayıcısında açar. Başarılı bir şekilde oturum açtıktan sonra Google'a uzun ömürlü bir erişim jetonu döndürürsünüz. Bu erişim jetonu artık Asistan'dan Action'ınıza gönderilen her isteğe dahil edilir.

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

• Oturum açma kullanıcı arayüzünü henüz oturum açmamış kullanıcılara sunmaktan ve istenen erişime kısa süreli bir yetkilendirme kodu biçiminde izin kaydetmekten sorumlu olan yetkilendirme uç noktası.
• İki tür exchange'den sorumlu olan jeton değişimi uç noktası:
  1. Yetkilendirme kodunu uzun ömürlü yenileme jetonu ve kısa ömürlü erişim jetonu ile değiştirir. Bu değişim, kullanıcı hesap bağlama akışından geçer.
  2. Kısa ömürlü bir erişim jetonu için uzun süreli yenileme jetonunu değiştirir. Bu exchange, Google'ın süresi dolmuş olduğundan yeni bir erişim jetonuna ihtiyacı olduğunda gerçekleşir.

Örtülü akış kullanılarak verilen erişim jetonlarının geçerlilik süresinin hiçbir zaman dolmaması, Google'ın örtülü akışla kullanılması nedeniyle kullanıcının hesabını tekrar bağlamayı zorunlu kıldığı için Google, örtülü akış akışının uygulanmasını önerir. Güvenlik nedeniyle jetonun süresinin dolması gerekiyorsa kimlik doğrulama kodu akışını kullanmanız önerilir.

Not: Lütfen hangi OAuth 2.0 akışını uygulamak istediğinizi seçin. Gerekirse bu kılavuzun içeriği, seçiminize uyum sağlamak için yeniden yüklenir.

Kimlik doğrulama kodu Dolaylı akış

OAuth hesap bağlamayı uygulayın

Not: Finansal bilgileri işlemek için hesap bağlama işlemi gerçekleştiriyorsanız İşleminiz için ek politikaların geçerli olabileceğini unutmayın. Finansal bilgiler için hesap bağlama içeren bir işlemi incelememiz altı haftaya kadar sürebilir. Bu nedenle, yayın planınızı planlarken bu süreyi de hesaba katın. İnceleme sürecini kolaylaştırmak için İşleminizi incelemeye göndermeden önce mali hizmetler politikalarına uyduğunuzdan emin olun.

Projeyi yapılandırma

Projenizi OAuth bağlantısını kullanacak şekilde yapılandırmak için aşağıdaki adımları uygulayın:

1. Actions Console'u açın ve kullanmak istediğiniz projeyi seçin.
2. Geliştirme sekmesini tıklayın ve Hesap bağlama'yı seçin.
3. Hesap bağlama'nın yanındaki anahtarı etkinleştirin.
4. Hesap oluşturma bölümünde Hayır, yalnızca web sitemde hesap oluşturulmasına izin vermek istiyorum'u seçin.

5. Bağlantı türü bölümünde OAuth ve Yetkilendirme kodu seçeneklerini belirleyin.

   

6. Müşteri Bilgileri bölümünde:

   • Google'dan gelen istekleri tanımlamak için Actions to Google'a (İşlemleriniz tarafından Google'a gönderilen) bir değer atayın.
   • Google tarafından İşlemlerinize verilen istemci kimliğinin değerini not edin;
   • Yetkilendirme ve Jeton Değişimi uç noktalarınızın URL'lerini ekleyin.

Not: İstemci kimliğiniz ve gizli anahtarınızın base64 olarak kodlanmış dize olarak gönderilmesini istiyorsanız İstemcinizi yapılandırın (isteğe bağlı) seçeneğinin yanındaki açılır oku tıklayın ve Google'ın, istemci kimliğini ve gizli anahtarı HTTP temel kimlik doğrulama üst bilgisi üzerinden iletmek için kutusunu işaretleyin.

6. Kaydet'i tıklayın.

OAuth sunucunuzu uygulama

Yetkilendirme kodu akışının OAuth 2.0 sunucusu uygulaması, hizmetinizin HTTPS ile kullanılabilir hale getirdiği iki uç noktadan oluşur. İlk uç nokta, veri erişimi için kullanıcıların iznini bulup almaktan sorumlu olan yetkilendirme uç noktasıdır. 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 izni kaydeder. İkinci uç nokta, işlem kullanıcısına hizmetinize erişim yetkisi veren jeton adı verilen şifrelenmiş dizeleri elde etmek için kullanılan jeton değişimi uç noktasıdır.

İşleminizin, hizmetinizin API'lerinden birini çağırması gerektiğinde Google, kullanıcılarınızın kendi adlarına bu API'leri çağırmasına izin vermek için bu uç noktaları birlikte kullanır.

Google tarafından başlatılan 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. Bir İşlem için akış yalnızca ses özellikli bir cihazda başladıysa Google yürütmeyi bir telefona aktarır.

2. Kullanıcı oturum açar (daha önce oturum açmamışsa) ve henüz izin vermemişse Google'ın API'nizle verilerine erişmesine izin verir.

   Not: Kullanıcının hesabının Google Home veya Google Asistan gibi belirli bir Google ürününe değil, Google'a bağlandığını bildirmeniz gerekir.

3. Hizmetiniz bir yetkilendirme kodu oluşturur ve bu kodu, isteğe bağlı yetkilendirme kodu ile birlikte kullanıcının tarayıcısını tekrar Google'a yönlendirerek Google'a gönderir.

4. Google, yetkilendirme kodunu jeton değişimi uç noktanıza gönderir. Bu işlem, kodun gerçekliğini doğrular ve bir erişim jetonu ile bir 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 depolayıp süresi dolduktan sonra 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, Asistan'dan istek karşılama webhook'unuza gönderilen sonraki her istek bir erişim jetonu içerir.

Yetkilendirme isteklerini işleme

İşleminizin bir OAuth 2.0 yetkilendirme kodu akışı üzerinden hesap bağlaması gerektiğinde Google, aşağıdaki parametreleri içeren bir istekle kullanıcıyı yetkilendirme uç noktanıza gönderir:

Yetkilendirme uç noktası parametreleri
client_id	Google'a kaydettirdiğiniz Google müşteri kimliği.
redirect_uri	Bu isteğe yanıt gönderdiğiniz URL.
state	Yönlendirme URI'sında değiştirilmeden Google'a geri aktarılan defter değeri.
scope	İsteğe bağlı: Google'ın yetkilendirme istediği verileri belirten, boşlukla sınırlandırılmış kapsam dizeleri grubu.
response_type	code dizesi.

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

1. client_id değerinin Google'a kaydettiğiniz Google istemci kimliğiyle eşleştiğini ve redirect_uri öğesinin, Google tarafından hizmetiniz için 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 kayıt 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 son kullanma zamanını benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Genellikle, süresi yaklaşık 10 dakika sonra dolacak yetkilendirme kodları gönderirsiniz.

4. redirect_uri parametresiyle belirtilen URL'nin aşağıdaki biçimde olduğunu onaylayın:

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

   YOUR_PROJECT_ID, Actions Console'un Proje ayarları sayfasında bulunan kimliktir.

5. Kullanıcının tarayıcısını redirect_uri parametresiyle belirtilen URL'ye yönlendirin. code ve state parametrelerini ekleyerek, az önce oluşturduğunuz yetkilendirme kodunu ve yönlendirme yaparken orijinal, değiştirilmemiş durum değerini belirtin. 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 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
• Erişim jetonları için yenileme jetonlarını değiştirme

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, Google'ın benzersiz tanımlayıcısı olarak sisteminizde kayıtlı olmalıdır.
client_secret	Hizmetiniz için Google'a kaydettiğiniz gizli dize.
grant_type	Alınan jetonun türü. authorization_code veya refresh_token.
code	grant_type=authorization_code olduğunda Google'ın oturum açma veya jeton değişimi uç noktanızdan aldığı kod.
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 Google'ın jeton değişimi uç noktanızdan aldığı yenileme jetonu.

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 süreli bir yetkilendirme kodu döndürdükten sonra Google, yetkilendirme kodunu erişim jetonu ve yenileme jetonuyla değiştirmek için jeton değişimi 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, erişim jetonu ve yenileme jetonuyla yetkilendirme kodu değiştirme isteğine ilişkin bir örnek 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 öğesinin istek kaynağını yetkili kaynak olarak tanımladığını ve client_secret öğesinin beklenen değerle eşleştiğini doğrulayın.
2. Aşağıdakileri doğrulayın:
   • Yetkilendirme kodu geçerli ve süresi dolmamış. İstekte belirtilen istemci kimliği, yetkilendirme koduyla ilişkilendirilmiş istemci kimliği ile eşleşiyor.
   • redirect_uri parametresi tarafından belirtilen URL, ilk yetkilendirme isteğinde kullanılan değerle aynıdır.
3. Yukarıdaki ölçütlerin tümünü doğrulayamıyorsanız gövde olarak {"error": "invalid_grant"} içeren HTTP 400 Hatalı İstek hatası döndürün.
4. Aksi takdirde, yetkilendirme kodundaki kullanıcı kimliğini kullanarak yenileme jetonu ve erişim jetonu oluşturun. Bu jetonlar herhangi bir dize değeri olabilir ancak jetonun ait olduğu kullanıcıyı ve müşteriyi benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Erişim jetonları için jetonun geçerlilik süresini de kaydedin (genellikle jetonu yayınlamanızdan bir saat sonra). Yenileme jetonlarının süresi dolmaz.
5. 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 saklar ve erişim jetonunun sona erme tarihini 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.

Erişim jetonları için yenileme jetonlarını 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 istekler için grant_type değeri refresh_token, refresh_token değeri ise daha önce Google'a verdiğiniz yenileme jetonunun değeridir. Aşağıda, erişim jetonuyla yenileme jetonu değişimine yönelik 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 bir erişim jetonuyla değiştirmek için jeton değişimi uç noktanız, aşağıdaki adımları yürüten POST isteklerine yanıt verir:

1. client_id öğesinin istek kaynağını Google olarak tanımladığını ve client_secret öğesinin 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 tümünü doğrulayamıyorsanız gövde olarak {"error": "invalid_grant"} içeren 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 kullanıcıyı ve jetonun ait olduğu müşteriyi benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Erişim jetonları için jetonun geçerlilik süresini de kaydedin (genellikle jetonu yayınlamanızdan bir saat sonra).
5. HTTPS yanıtının gövdesinde aşağıdaki JSON nesnesini döndürün:

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

Not: İsterseniz yanıtınızda yeni bir refresh_token değeri de döndürebilirsiniz. Yeni bir refresh_token iadenin ne zaman tercih edildiği hakkında daha fazla bilgi için Jetonlarla çalışma bölümüne bakın.

Kimlik doğrulama akışı için ses kullanıcı arayüzünü tasarlama

Uyarı: İşleminizle görüşmenin başında kullanıcılara zorunlu bir hesap bağlama istemi vermeyin. Bunun yerine, kimliği doğrulanmamış kullanıcılara İşleminizin nasıl çalıştığını göstermek için misafir akışı sağlayın ve yalnızca devam etmek için gerekliyse hesap bağlama işlemini isteyin. Kullanıcılar, hesap bağlama sorunları nedeniyle İşlem'den sürekli olarak ayrılıyorsa Google, İşlemi etkin bir şekilde tanıtmaz. Bu da işlemin kullanıcı trafiğini azaltabilir.

Not: Hesap bağlamanın uygulandığı bir İşlem oluşturmak için Actions Builder'ı kullanmanız gerekir.

Kullanıcının doğrulanıp doğrulanmadığını kontrol etme ve hesap bağlama akışını başlatma

1. Actions Console'da Actions Builder projenizi açın.
2. İşleminizde hesap bağlamayı başlatmak için yeni bir sahne oluşturun:
   1. Sahneler'i tıklayın.
   2. Yeni bir sahne eklemek için ekle (+) simgesini tıklayın.
3. Yeni oluşturulan sahnede Koşullar için ekle simgesini tıklayın.
4. Görüşmeyle ilişkilendirilen kullanıcının doğrulanmış bir kullanıcı olup olmadığını kontrol eden bir koşul ekleyin. Kontrol başarısız olursa İşleminiz görüşme sırasında hesap bağlama işlemi gerçekleştiremez ve hesap bağlamayı gerektirmeyen işlevlere erişim sağlamaya devam etmelidir.
   1. Koşul bölümündeki Enter new expression alanına aşağıdaki mantığı girin: user.verificationStatus != "VERIFIED"
   2. Geçiş bölümünde, hesap bağlama gerektirmeyen bir düzen veya yalnızca konuklara özel işleve giriş noktası olan bir düzen seçin.

1. Koşullar için ekle simgesini tıklayın.
2. Kullanıcının ilişkili bir kimliği yoksa hesap bağlama akışını tetiklemek için bir koşul ekleyin.
   1. Koşul bölümündeki Enter new expression alanına aşağıdaki mantığı girin: user.verificationStatus == "VERIFIED"
   2. Geçiş bölümünde, Hesap Bağlama sistem sahnesini seçin.
   3. Kaydet'i tıklayın.

Kaydettikten sonra projenize <SceneName>_AccountLinking adlı yeni bir hesap bağlama sistemi düzeni eklenir.

Hesap bağlama sahnesini özelleştirin

1. Sahneler bölümünde, hesap bağlama sistemi sahnesini seçin.
2. İstem gönder'i tıklayın ve işlemin neden kimliğine erişmesi gerektiğini kullanıcıya açıklamak için kısa bir cümle ekleyin (örneğin, "Tercihlerinizi kaydetmek için").
3. Kaydet'i tıklayın.

1. Koşullar bölümünde, Kullanıcı hesap bağlamayı başarıyla tamamlarsa'yı tıklayın.
2. Kullanıcı, hesabını bağlamayı kabul ederse akışın nasıl devam edeceğini yapılandırın. Örneğin, gerekli olan özel iş mantığını işlemesi ve kaynak sahneye geri dönmesi için webhook'u çağırın.
3. Kaydet'i tıklayın.

1. Koşullar bölümünde, Kullanıcı hesap bağlamayı iptal eder veya reddederse'yi tıklayın.
2. Kullanıcı, hesabını bağlamayı kabul etmezse akışın nasıl devam edeceğini yapılandırın. Örneğin, onaylama mesajı gönderin ve kullanıcıları, hesap bağlamayı gerektirmeyen işlevler sunan sahnelere yönlendirin.
3. Kaydet'i tıklayın.

1. Koşullar bölümünde, Sistem veya ağ hatası oluşursa'yı tıklayın.
2. Hesap bağlama akışı sistem veya ağ hataları nedeniyle tamamlanamıyorsa akışın nasıl devam edeceğini yapılandırın. Örneğin, onaylama mesajı gönderin ve kullanıcıları, hesap bağlamayı gerektirmeyen işlevler sunan sahnelere yönlendirin.
3. Kaydet'i tıklayın.

Veri erişim isteklerini işleme

Asistan isteği erişim jetonu içeriyorsa öncelikle erişim jetonunun geçerli olduğundan (ve süresinin dolmamış olduğundan) emin olun, ardından veritabanınızdan ilişkili kullanıcı hesabını alın.