Overview

Every smart home Action must include a mechanism for authenticating users.

Authentication allows you to link your users' Google accounts with user accounts in your authentication system. This allows you to identify your users when your fulfillment receives a smart home intent. Google smart home only supports OAuth with an authorization code flow.

Tasarım Kuralları

Bu bölümde, App Flip hesap bağlama izni ekranı için tasarım gereksinimleri ve önerileri açıklanmaktadır. Google uygulamanızı aradıktan sonra, uygulamanız kullanıcıya izin ekranını görüntüler.

Gereksinimler

  1. Kullanıcının hesabının Google Home veya Google Assistant gibi belirli bir Google ürününe değil , Google'a bağlandığını bildirmelisiniz.

Öneriler

Aşağıdakileri yapmanızı tavsiye ederiz:

  1. Google'ın Gizlilik Politikasını görüntüleyin. İzin ekranına Google'ın Gizlilik Politikası'na bir bağlantı ekleyin.

  2. Paylaşılacak veriler. Kullanıcıya Google'ın hangi verileri gerektirdiğini ve neden istediğini söylemek için açık ve kısa bir dil kullanın.

  3. Harekete geçirici mesajı temizleyin. İzin ekranınızda "Kabul et ve bağlantı kur" 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ı gerektiğidir.

  4. İptal etme yeteneği. Bağlanmamayı seçerlerse kullanıcıların geri dönmesi veya iptal etmesi için bir yol sağlayın.

  5. Bağlantıyı kaldırma yeteneği. Kullanıcıların, platformunuzdaki hesap ayarlarının URL'si gibi bağlantısını kaldırmaları için bir mekanizma sunun. Alternatif olarak, kullanıcıların bağlı hesaplarını yönetebilecekleri bir Google Hesabı bağlantısı da ekleyebilirsiniz.

  6. Kullanıcı hesabını değiştirebilme. Kullanıcıların hesaplarını değiştirmeleri için bir yöntem önerin. Bu, özellikle kullanıcılar birden fazla hesaba sahip olma eğilimindeyse faydalıdır.

    • Bir kullanıcının hesap değiştirmek için izin ekranını kapatması gerekiyorsa Google'a kurtarılabilir bir hata gönderin, böylece kullanıcı OAuth bağlantısı ve örtük akış ile istenen hesapta oturum açabilir.
  7. Logonuzu ekleyin. Şirket logonuzu izin ekranında görüntüleyin. Logonuzu yerleştirmek için stil yönergelerinizi kullanın. Google'ın logosunu da görüntülemek isterseniz, Logolar ve ticari markalar bölümüne bakın.

Bu şekil, bir kullanıcı izin ekranı tasarlarken izlenecek bireysel gereksinimlere ve önerilere yönelik çağrıların yer aldığı örnek bir izin ekranını gösterir.
Şekil 2. Hesabı bağlama izni ekranı tasarım yönergeleri.

Implement OAuth account linking

To implement OAuth account linking in your smart home Action, you must do the following:

  1. Implement your OAuth 2.0 server.
  2. Configure account linking in the Actions console.

Implement your OAuth 2.0 server

This section describes how to set up your OAuth 2.0 server so that it works with your smart home Action.

Yetkilendirme kodu akışının OAuth 2.0 sunucu uygulaması, hizmetinizin HTTPS tarafından kullanılabilir hale getirdiği iki uç noktadan oluşur. İlk uç nokta, veri erişimi için kullanıcılardan izin almaktan veya onlardan izin almaktan sorumlu olan yetkilendirme uç noktasıdır. Yetkilendirme uç noktası, halihazırda oturum açmamış kullanıcılarınız için bir oturum açma kullanıcı arayüzü sunar ve istenen erişime izin verir. İkinci uç nokta, bir kullanıcıya hizmetinize erişme yetkisi veren, belirteç adı verilen şifrelenmiş dizeleri elde etmek için kullanılan belirteç değişimi uç noktasıdır.

Bir Google uygulamasının hizmetinizin API'larından birini çağırması gerektiğinde, Google, kullanıcılarınızdan bu API'leri kendi 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, yetkilendirme uç noktanızı kullanıcının tarayıcısında açar. Akış, bir Eylem için yalnızca sesin kullanılabildiği bir cihazda başladıysa, Google yürütmeyi bir telefona aktarır.
  2. Kullanıcı, henüz oturum açmadıysa oturum açar ve henüz izin vermediyse Google'a API'nizle verilerine erişme izni verir.
  3. Hizmetiniz bir yetkilendirme kodu oluşturur ve bunu Google'a iade eder. Bunu yapmak için, isteğe bağlı yetkilendirme koduyla kullanıcının tarayıcısını Google'a yeniden yönlendirin.
  4. Google, yetkilendirme kodunu, kodun gerçekliğini doğrulayan ve bir erişim jetonu ve bir yenileme jetonu döndüren jeton değişim uç noktanıza gönderir. Erişim belirteci, hizmetinizin API'lere erişmek için kimlik bilgileri olarak kabul ettiği kısa ömürlü bir belirteçtir. Yenileme jetonu, Google'ın saklayabileceğ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 sonraki 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:

Yetkilendirme uç noktası parametreleri
client_id Google'a kaydettiğiniz Google müşteri kimliği.
redirect_uri Bu isteğe yanıtı gönderdiğiniz URL.
state Yönlendirme URI'sinde değiştirilmeden Google'a geri aktarılan bir defter tutma değeri.
scope İsteğe bağlı: Google'ın yetkilendirme istediği verileri belirten, boşlukla sınırlandırılmış bir kapsam dizeleri kümesi.
response_type Yanıtta döndürülecek değer türü. OAuth 2.0 yetkilendirme kodu akışı için yanıt türü her zaman code .
user_locale İçeriğinizi kullanıcının tercih ettiği dilde yerelleştirmek için kullanılan, RFC5646 biçimindeki Google Hesabı dil ayarı.

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

  1. Doğrulayın client_id Google ile kayıtlı Google istemci kimliği ile eşleşen ve bu redirect_uri hizmetinize Google tarafından sağlanan yönlendirme URL'sini eşleşir. Bu kontroller, istenmeyen veya yanlış yapılandırılmış istemci uygulamalarına erişim verilmesini önlemek için önemlidir. Birden OAuth 2.0 akışlarını destekleyen varsa da teyit response_type olan code .
  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 kayıt işlemlerini tamamlayın.
  3. Google'ın API'nize erişmek için kullanması için bir yetkilendirme kodu oluşturun. Yetkilendirme kodu herhangi bir dize değeri olabilir, ancak kullanıcıyı, belirtecin bulunduğu istemciyi ve kodun sona erme süresini benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Genellikle yaklaşık 10 dakika sonra sona eren yetkilendirme kodları verirsiniz.
  4. redirect_uri parametresi tarafından belirtilen URL'nin şu biçime sahip 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 redirect_uri . code ve state parametrelerini ekleyerek yeniden yönlendirme yaparken yeni oluşturduğunuz yetkilendirme kodunu ve orijinal, değiştirilmemiş durum değerini ekleyin. Aşağıda, sonuçta ortaya çıkan URL'ye bir örnek verilmiştir:
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Jeton değişimi taleplerini yönetin

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

  • Erişim belirteçleri ve yenileme belirteçleri için yetkilendirme kodlarını değiştirin
  • Erişim belirteçleri için yenileme belirteçlerini değiştirin

Token değişim talepleri aşağıdaki parametreleri içerir:

Jeton değişimi uç nokta parametreleri
client_id İsteğin kaynağını Google olarak tanımlayan bir dize. Bu dize, sisteminize Google'ın benzersiz tanımlayıcısı olarak kaydedilmelidir.
client_secret Hizmetiniz için Google'a kaydettiğiniz gizli bir dize.
grant_type Değiştirilen jetonun türü. Ya authorization_code ya da refresh_token .
code grant_type=authorization_code , bu parametre Google'ın oturum açma veya jeton değişimi uç noktanızdan aldığı koddur.
redirect_uri grant_type=authorization_code , bu parametre ilk yetkilendirme isteğinde kullanılan URL'dir.
refresh_token grant_type=refresh_token , bu parametre Google'ın jeton değişimi uç noktanızdan aldığı yenileme belirtecidir.
Erişim belirteçleri ve yenileme belirteçleri için yetkilendirme kodlarını değiştirin

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 bir erişim jetonu ve bir 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 ve code değeri daha önce Google'a verdiğiniz yetkilendirme kodunun değeridir. Aşağıda, bir erişim jetonu ve yenileme jetonu için bir yetkilendirme kodunu değiştirme talebine 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

Erişim jetonu ve yenileme jetonu için yetkilendirme kodlarını değiş tokuş etmek için jeton değişim uç noktanız aşağıdaki adımları uygulayarak POST isteklerine yanıt verir:

  1. Doğrulayın client_id tanımlar yetkili kökenli olarak ve bu istek kökenli client_secret beklenen değeri ile eşleşir.
  2. Yetkilendirme kodunun geçerli olduğunu ve süresinin dolmadığını ve istekte belirtilen istemci kimliğinin yetkilendirme koduyla ilişkili istemci kimliğiyle eşleştiğini doğrulayın.
  3. redirect_uri parametresiyle belirtilen URL'nin ilk yetkilendirme isteğinde kullanılan değerle aynı olduğunu onaylayın.
  4. Yukarıdaki kriterlerin tümünü doğrulayamıyorsanız, gövde olarak {"error": "invalid_grant"}
  5. Aksi takdirde, bir yenileme jetonu ve bir erişim jetonu oluşturmak için yetkilendirme kodundaki kullanıcı kimliğini kullanın. Bu belirteçler herhangi bir dize değeri olabilir, ancak simgenin ait olduğu kullanıcıyı ve istemciyi benzersiz bir şekilde temsil etmelidir ve tahmin edilebilir olmamalıdır. Erişim belirteçleri için, belirteci verdikten sonra genellikle bir saat olan belirtecin sona erme süresini de kaydedin. Yenileme jetonlarının süresi dolmaz.
  6. HTTPS yanıtının gövdesinde şu JSON nesnesini döndür:
    {
    "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 belirteçleri için yenileme belirteçlerini değiştirin

Bir erişim jetonunun süresi dolduğunda Google, jeton değişimi uç noktanıza yeni bir erişim jetonu için yenileme jetonu takası için bir istek gönderir.

Bu istekler için, değeri grant_type edilir refresh_token ve değeri refresh_token daha önce Google'a verilen belirteç yenileme değeridir. Aşağıda, bir erişim belirteci için yenileme belirtecini değiştirme talebine 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=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ı uygulayarak POST isteklerine yanıt verir:

  1. Doğrulayın client_id tanımlar isteği Google gibi kökeni ve bu client_secret beklenen değeriyle eşleşir.
  2. Yenileme belirtecinin geçerli olduğunu ve istekte belirtilen istemci kimliğinin yenileme belirteciyle ilişkilendirilmiş istemci kimliğiyle eşleştiğini doğrulayın.
  3. Yukarıdaki kriterlerin tümünü doğrulayamıyorsanız, gövde olarak {"error": "invalid_grant"} içeren bir HTTP 400 Kötü İstek hatası {"error": "invalid_grant"} .
  4. Aksi takdirde, bir erişim belirteci oluşturmak için yenileme belirtecindeki kullanıcı kimliğini kullanın. Bu belirteçler herhangi bir dize değeri olabilir, ancak simgenin ait olduğu kullanıcıyı ve istemciyi benzersiz bir şekilde temsil etmelidir ve tahmin edilebilir olmamalıdır. Erişim jetonları için, jetonun sona erme süresini de, genellikle jetonu verdikten bir saat sonra kaydedin.
  5. HTTPS yanıtının gövdesinde şu JSON nesnesini döndür:
    {
    "token_type": "Bearer",
    "access_token": " ACCESS_TOKEN ",
    "expires_in": SECONDS_TO_EXPIRATION
    }

Configure account linking in the console

To set up account linking in the Actions console, follow these steps:

  1. Go to the Actions console.
  2. Select your smart home Action project.
  3. Click the Develop tab. Then, click Account linking in the left navigation.
  4. Fill out all the fields under OAuth Client information. Click Next.
  5. Click Save.

Next steps (optional)

Once you have an OAuth 2.0 implementation, you can optionally configure OAuth-based App Flip, which allows your users to more quickly link their accounts in your authentication system to their Google accounts. For App Flip implementation instructions, see OAuth-based App Flip.