OAuth hesap bağlama türü, endüstri standardı iki OAuth 2.0 akışını destekler: dolaylı ve yetkilendirme kodu akışları. Google, dolaylı kod akışında 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 verirsiniz. Bu erişim jetonu daha sonra Asistan'dan İşleminize gönderilen her isteğe dahil edilir.
Aşağıdaki durumlarda hesap bağlama çözümü olarak OAuth önerilir:
- Mevcut bir OAuth 2.0 sunucusu uygulamanız var ve Google'ın bir kimlik jetonundan otomatik bağlantı ve hesap oluşturma protokollerini desteklemek için jeton değişimi uç noktanızı genişletemezsiniz (ör. isteklere
intent=getveintent=createparametrelerini bu uç noktaya ekleme).
OAuth'un sizin için doğru çözüm olduğunu doğrulamak için Hesap bağlama türünüzü seçin sayfasını inceleyin.
Anahtar terimler
OAuth'un işleyiş şekli hakkında bilgi edinmeden önce aşağıdaki terimler hakkında bilgi edinin:
- Hesapta oturum açma yardımcı amacı: Asistan'dan hesap bağlama akışı istemek için çağırdığınız yardımcı intent. Daha fazla bilgi için Hesapta Oturum Açma bölümüne bakın.
- Bağlam dizesi: Hesapta oturum açma yardımcısı amacına eklediğiniz ve kullanıcıya neden hesabını bağlaması gerektiğini açıklayan özelleştirilmiş bir dize.
Yetkilendirme kodu akışı: Bu OAuth 2.0 akışı sırasında Google, kullanıcının tarayıcısında yetkilendirme uç noktanızı açar. Oturum açma başarılı olursa hizmetiniz bir yetkilendirme kodu oluşturur ve bu kodu Google'a geri gönderir. Google, bu 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 yenileme jetonu döndürür.
Bu akış iki uç nokta gerektirir:
- Yetkilendirme uç noktası: Veri erişimi için kullanıcıların iznini bulup almaktan sorumlu olan uç nokta. Bu uç nokta şunları yapar:
- Oturum açma kullanıcı arayüzünü, henüz oturum açmamış kullanıcılarınıza sunar.
- Kayıtlar, kısa ömürlü yetkilendirme kodu şeklinde istenen erişim iznini verir.
- Jeton değişimi uç noktası: Bu uç nokta, işlem kullanıcısını hizmetinize erişmesi için yetkilendiren jeton adı verilen şifrelenmiş dizeleri elde etmek için kullanılır. Bu uç nokta, iki tür exchange'den sorumludur:
- Uzun ömürlü yenileme jetonu ve kısa ömürlü erişim jetonu için yetkilendirme kodu değiştirir. Bu değişim, kullanıcı hesap bağlama akışından geçtiğinde gerçekleşir.
- Kısa ömürlü bir erişim jetonu için uzun süreli yenileme jetonunu değiştirir. Bu exchange, Google'ın süresi dolduğu için yeni bir erişim jetonuna ihtiyacı olduğunda gerçekleşir.
- Yetkilendirme uç noktası: Veri erişimi için kullanıcıların iznini bulup almaktan sorumlu olan uç nokta. Bu uç nokta şunları yapar:
Dolaylı kod akışı: Bu OAuth 2.0 akışı sırasında Google, kullanıcının tarayıcısında yetkilendirme uç noktanızı açar. Oturum açma başarılı olursa Google'a uzun ömürlü bir erişim jetonu döndürürsünüz. Bu erişim jetonu daha sonra Asistan'dan İşleminize gönderilen her isteğe dahil edilir. Bu akış yalnızca bir yetkilendirme uç noktası gerektirir.
Erişim jetonu: Hizmetinize kullanıcı verilerinin belirli kısımlarına erişim yetkisi veren bir jeton. Erişim jetonları her bir kullanıcıyla ilişkilendirilir ve tahmin edilemez olmalıdır.
Yenileme jetonu: Kısa ömürlü bir erişim jetonunun süresi dolduktan sonra yeni bir erişim jetonuyla değiştirilen jeton.
İşleyiş şekli
Bu bölümde, OAuth yetkilendirme kodunun genel akışı ve dolaylı akışlar açıklanmaktadır. Aşağıdaki OAuth akışları bölümünde, OAuth'ta gerçekleşebilecek çeşitli akışlar açıklanmaktadır.
Yetkilendirme kodu akışı şu şekilde özetlenebilir:
- İşleminiz kullanıcıya hesabını hizmetinize bağlamak isteyip istemediğini soruyor.
- Kullanıcı hesapları bağlamayı kabul ettikten sonra 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ütme işlemini telefona aktarır.
- Kullanıcı oturum açar (henüz oturum açmadıysa) ve API'nizle verilerine erişmesi için Google'a izin verir (önceden izin vermemişse).
- 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.
- 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 süreli bir jetondur.
- Kullanıcı, hesap bağlama akışını tamamladıktan sonra, Asistan'dan istek karşılama webhook'unuza gönderilen her istek bir erişim jetonu içerir.
Örtülü kod akışı şu şekilde özetlenebilir:
- İşleminiz kullanıcıya hesabını hizmetinize bağlamak isteyip istemediğini soruyor.
- Kullanıcı hesapları bağlamayı kabul ettikten sonra Google, kullanıcının tarayıcısında yetkilendirme uç noktanızı açar.
- Kullanıcı oturum açar (henüz oturum açmadıysa) ve API'nizle verilerine erişmesi için Google'a izin verir (önceden izin vermemişse).
- Hizmetiniz bir erişim jetonu oluşturur ve kullanıcının tarayıcısını isteğe bağlı erişim jetonuyla birlikte tekrar Google'a yönlendirerek bu jetonu Google'a gönderir.
- Kullanıcı, hesap bağlama akışını tamamladıktan sonra Google, hizmetinizin API'lerini çağırır ve her isteğe erişim jetonunu ekler. Hizmetiniz, erişim jetonunun Google'a API'ye erişim yetkisi verdiğini doğrular ve ardından API çağrısını tamamlar.
Temel yetkilendirme kodu akışı aşağıdaki gibidir:
- İşleminiz kullanıcıya hesabını hizmetinize bağlamak isteyip istemediğini soruyor.
- Kullanıcı hesapları bağlamayı kabul ettikten sonra 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ütme işlemini telefona aktarır.
- Kullanıcı oturum açar (henüz oturum açmadıysa) ve API'nizle verilerine erişmesi için Google'a izin verir (önceden izin vermemişse).
- Hizmetiniz bir yetkilendirme kodu oluşturur ve bu kodu, kısa ömürlü yetkilendirme kodu isteğe eklenmiş ve kullanıcının tarayıcısını tekrar Google'a yönlendirerek Google'a gönderir.
- 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 süreli bir jetondur.
- Kullanıcı, hesap bağlama akışını tamamladıktan sonra, Asistan'dan istek karşılama webhook'unuza gönderilen her istek bir erişim jetonu içerir.
OAuth akışları
Bu bölümde, OAuth'ta oluşabilecek çeşitli akışlar ele alınmaktadır.
Her akış, kullanıcı İşleminizi çağırdıktan sonra şu yaygın adımları içerir:
Yukarıdaki akışta, hesap bağlama akışını başlatmak için actions.intent.SIGN_IN yardımcı niyetini çağırırsınız. Asistan, kullanıcıya hesabını hizmetinize bağlamak isteyip istemediğini sorar ve istenen izinleri içeren bir ekran gösterir. Kullanıcı izin verdiğinde Google, kullanıcıyı hizmetinizin tarayıcıda bulunan yetkilendirme uç noktasına yönlendirir. Kullanıcı oturum açar (veya yapılandırmanıza bağlı olarak yeni bir hesap oluşturur) ve İşleminize verilerine erişme izni verir.
Bu noktadan sonraki akışlar, örtülü akış veya yetkilendirme kodu akışını uygulayıp uygulamadığınıza bağlı olarak farklılık gösterir. Bu akışlar aşağıdaki bölümlerde açıklanmıştır.
1. Akış: Kullanıcı dolaylı akışla oturum açar
Kullanıcı giriş yaptıktan ve kimlik bilgileri doğrulandıktan sonra hizmetiniz uzun ömürlü bir erişim jetonu oluşturur ve bunu Google'a geri gönderir. Bu noktada, kullanıcının İşleminizdeki kimliği oturum açtığı hesaba bağlanır ve erişim jetonu, Google'ın hizmetinizin API'lerine yaptığı her API çağrısına eklenir.
2. Akış: Kullanıcı, yetkilendirme kodu akışıyla oturum açar
Kullanıcı giriş yaptıktan ve kimlik bilgileri doğrulandıktan sonra hizmetiniz bir yetkilendirme kodu oluşturur ve bu kodu Google'a geri gönderir.
Bu yetkilendirme kodu, jeton değişimi uç noktanıza gönderilir ve bu da hem erişim jetonu hem de yenileme jetonu döndürür. Bu noktada, kullanıcının İşleminizdeki kimliği, oturum açtığı hesaba bağlanır ve Asistan'dan istek karşılama sayfanıza gönderilen sonraki her istek bir erişim jetonu içerir.