OAuth bağlantısı kavram kılavuzu

OAuth bağlama türü, endüstri standardı iki OAuth 2.0 akışını destekler: örtülü 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.

OAuth bağlama, aşağıdaki durumlarda önerilen hesap bağlama çözümüdür:

• 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=get ve intent=create parametrelerini bu uç noktaya ekleme).

OAuth bağlantısının sizin için doğru çözüm olduğunu doğrulamak üzere Hesap bağlama türünüzü seçme sayfasını inceleyin.

Anahtar terimler

OAuth bağlantısının işleyiş şekli hakkında bilgi edinmeden önce aşağıdaki terimler hakkında bilgi edinin:

• user.verificationStatus: Mevcut oturumda doğrulanmış bir kullanıcı olup olmadığını göstermek için sistem tarafından ayarlanan mülk.

• user.accountLinkingStatus: Geçerli oturumdaki kullanıcının bağlı bir kimliğine sahip olup olmadığını belirtmek için sistem tarafından ayarlanan özellik.

• Hesap bağlama sistemi sahnesi: Hesap bağlama için onay akışını uygulayan ve belirli kullanım alanlarına uyacak şekilde özelleştirilebilen önceden tanımlanmış bir düzen.

• 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:
    1. Oturum açma kullanıcı arayüzünü, henüz oturum açmamış kullanıcılarınıza sunar.
    2. 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:
    1. 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.
    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 dolduğu için yeni bir erişim jetonuna ihtiyacı olduğunda gerçekleşir.

• 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 bağlama akışları bölümünde, OAuth'ta oluşabilecek çeşitli akışlar açıklanmaktadır.

Yetkilendirme kodu akışı şu şekilde özetlenebilir:

1. İşleminiz kullanıcıya hesabını hizmetinize bağlamak isteyip istemediğini soruyor.
2. 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.
3. 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).
4. 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.
5. 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.
6. 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.

Örtülü kod akışı şu şekilde özetlenebilir:

1. İşleminiz kullanıcıya hesabını hizmetinize bağlamak isteyip istemediğini soruyor.
2. Kullanıcı hesapları bağlamayı kabul ettikten sonra Google, kullanıcının tarayıcısında yetkilendirme uç noktanızı açar.
3. 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).
4. 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.
5. 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:

1. İşleminiz kullanıcıya hesabını hizmetinize bağlamak isteyip istemediğini soruyor.
2. 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.
3. 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).
4. 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.
5. 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.
6. 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.

OAuth bağlantı akışları

Bu bölümde, OAuth bağlantısıyla oluşabilecek çeşitli akışlar ele alınmaktadır.

Not: Aşağıdaki akışlarda, kullanıcının, hesabını hizmetinize bağlamayı ve Google'a API'nizle kendi verilerine erişme izni vermeyi kabul ettiği varsayılır. Bir kullanıcı izin vermezse ona İşleminize alternatif, sınırlı bir akışla devam etmeleri için bir yol sağlayın. Daha fazla bilgi için En iyi uygulamalar makalesini inceleyin.

Her akış, kullanıcı İşleminizi çağırdıktan sonra şu yaygın adımları içerir:

Not: Webhook'tan User'a giden bir satır, oluşturduğunuz ve özelleştirdiğiniz basit bir yanıtı temsil eder. Asistan'dan Kullanıcı'ya çizilen çizgiler Asistan'a ait olan ve sınırlı özelleştirme seçeneklerine sahip istemleri temsil eder (izin gerektiren istekler her zaman Asistan'a aittir). Kullanıcı açısından bakıldığında her iki yanıt türü de Asistan'dan geliyor.

Yukarıdaki akışta, hesap bağlama sistemi sahnesine geçiş yapar ve özelleştirilmiş bir gerekçe sunarsı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

Not: Bu şema, yukarıdaki Genel adımlar diyagramına dayanır.

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

Not: Bu şema, yukarıdaki Genel adımlar diyagramına dayanır.

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 sipariş karşılamanıza gönderilen her istek bir erişim jetonu içerir.