OAuth ile Google Hesabı Bağlama

Hesaplar, endüstri standardı OAuth 2.0 dolaylı ve yetkilendirme kodu akışları kullanılarak bağlanır. Hizmetiniz, OAuth 2.0 uyumlu yetkilendirme ve jeton değişimi uç noktalarını desteklemelidir.

Dolaysız akışta Google, kullanıcının tarayıcısında yetkilendirme uç noktanızı açar. Başarıyla oturum açtıktan sonra Google'a uzun süreli bir erişim jetonu döndürürsünüz. Bu erişim jetonu artık Google'dan gönderilen her isteğe dahil edilir.

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

• Oturum açmamış kullanıcılarınıza oturum açma kullanıcı arayüzünü sunan authorization uç noktası. Yetkilendirme uç noktası ayrıca kullanıcıların istenen erişim için iznini kaydetmek üzere kısa ömürlü bir yetkilendirme kodu 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ışında ilerlerken gerçekleşir.
  2. Uzun ömürlü yenileme jetonunu kısa ömürlü erişim jetonuyla değiştirir. Bu değişim, Google'ın süresi dolmuş olan erişim jetonu nedeniyle yeni bir erişim jetonuna ihtiyaç duyduğunda gerçekleşir.

OAuth 2.0 akışı seçme

Yarı açık akışın uygulanması daha kolay olsa da Google, yarı açık akış tarafından verilen erişim jetonlarının süresinin hiçbir zaman dolmaması gerektiğini önerir. Bunun nedeni, kullanıcının, jetonun süresi dolduğunda, gizli akışla hesabını tekrar bağlamaya zorlanmasıdır. Güvenlik nedeniyle jetonun son geçerlilik tarihine ihtiyacınız varsa bunun yerine yetkilendirme kodu akışını kullanmanızı önemle tavsiye ederiz.

Not: Uygulamak istediğiniz OAuth 2.0 akışını seçmek için aşağıdaki düğmeleri kullanın. Gerekirse bu kılavuzun içeriği, seçiminize uyacak şekilde yeniden yüklenir.

Dolaylı akış Yetkilendirme kodu

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 şartları ve öneriler açıklanmaktadır. Google'ın uygulaması tarafından çağrıldıktan sonra platformunuz kullanıcıya Google'da oturum açma sayfası ve hesap bağlama izni ekranı gösterir. Kullanıcı, hesapları bağlama izni verdikten sonra Google'ın uygulamasına geri yönlendirilir.

Şekil 1. Hesap bağlama, kullanıcının Google'da oturum açma ve izin ekranları.

Şartlar

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

Öneriler

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

1. Google'ın Gizlilik Politikası'nı gösterin. İzin ekranına Google'ın Gizlilik Politikası'nın bağlantısını ekleyin.

2. Paylaşılacak veriler. Google'ın kullanıcının hangi verilerini neden gerekli kıldığını net ve kısa bir dille açıklayın.

3. Net bir 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ı Kullanıcıların bağlantı oluşturmayı tercih etmemesi durumunda geri dönmelerine veya işlemi iptal etmelerine olanak tanıyacak bir yöntem sunun.

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

6. Bağlantı kaldırma yetkisi. Kullanıcıların bağlantıyı kaldırabileceği bir mekanizma (ör. platformunuzdaki hesap ayarlarının URL'si) sunun. Alternatif olarak, kullanıcıların bağlı hesaplarını yönetebilecekleri Google Hesabı'nın bağlantısını da ekleyebilirsiniz.

7. Kullanıcı hesabını değiştirme olanağı Kullanıcılara hesaplarını değiştirmek için bir yöntem önerebilirsiniz. Bu, özellikle kullanıcıların birden fazla hesabı varsa yararlıdır.

   • Kullanıcının hesap değiştirmek için izin ekranını kapatması gerekiyorsa kullanıcının OAuth bağlama ve örtülü akışla istediği hesapta oturum açabilmesi için Google'a kurtarılabilir bir hata gönderin.

8. Logonuzu ekleyin. İzin ekranında şirket logonuzu gösterin. Logonuzu yerleştirmek için stil yönergelerinizi kullanın. Google'ın logosunu da göstermek istiyorsanız Logolar ve ticari markalar başlıklı makaleyi inceleyin.

Şekil 2. Kullanıcıların Google'da oturum açmaları ve izin ekranlarıyla ilgili yönergeler tasarlayın.

Projeyi oluşturma

Not: Mevcut bir projeyi yeniden kullanabilirsiniz. Hesap bağlama için öncelikli olarak yeni bir proje oluşturmanız gerekmez.

Hesap bağlamayı kullanmak için projenizi oluşturmak üzere:

2. Proje oluştur'u tıklayın.
3. Bir ad girin veya oluşturulan öneriyi kabul edin.
4. Kalan alanları onaylayın veya düzenleyin.
5. Oluştur'u tıklayın.

Proje kimliğinizi görüntülemek için:

2. Açılış sayfasındaki tabloda projenizi bulun. Proje kimliği, Kimlik sütununda görünür.

OAuth izin ekranınızı yapılandırma

Google Hesabı bağlama sürecinde, kullanıcılara verilerine erişim isteyen uygulamayı, hangi tür verileri istediğini ve geçerli şartları bildiren bir izin ekranı gösterilir. Google API istemci kimliği oluşturmadan önce OAuth izin ekranınızı yapılandırmanız gerekir.

1. Google API'leri konsolunun OAuth izin ekranı sayfasını açın.
2. İstenirse yeni oluşturduğunuz projeyi seçin.

3. "OAuth izin ekranı" sayfasında formu doldurun ve "Kaydet" düğmesini tıklayın.

   Uygulama adı: İzin isteyen uygulamanın adı. Ad, uygulamanızı doğru bir şekilde yansıtmalı ve kullanıcıların başka yerlerde gördüğü uygulama adıyla tutarlı olmalıdır. Uygulama adı, hesap bağlama izin ekranında gösterilir.

   Uygulama logosu: İzin ekranında, kullanıcıların uygulamanızı tanımasına yardımcı olacak bir resim. Logo, hesap bağlama izin ekranında ve hesap ayarlarında gösterilir.

   Destek e-postası: Kullanıcıların rızalarıyla ilgili soruları için sizinle iletişime geçmesi amacıyla.

   Google API'leri için kapsamlar: Kapsamlar, uygulamanızın kullanıcınızın gizli Google verilerine erişmesine olanak tanır. Google Hesabı Bağlama kullanım alanı için varsayılan kapsam (e-posta, profil, openid) yeterlidir. Hassas kapsamlar eklemeniz gerekmez. Genel olarak, kapsamları önceden değil, erişim gerektiğinde artımlı olarak istemek en iyi uygulamadır. Daha fazla bilgi edinin.

   Yetkilendirilen alanlar: Google, sizi ve kullanıcılarınızı korumak için yalnızca OAuth kullanarak kimlik doğrulayan uygulamaların Yetkilendirilen Alanları kullanmasına izin verir. Uygulamalarınızın bağlantıları, yetkilendirilmiş alanlarda barındırılmalıdır. Daha fazla bilgi edinin.

   Uygulama ana sayfası bağlantısı: Uygulamanızın ana sayfası. Yetkili bir alan adında barındırılmalıdır.

   Uygulamanın gizlilik politikası bağlantısı: Google Hesabı Bağlama izni ekranında gösterilir. Yetkili bir alan adında barındırılmalıdır.

   Uygulama Hizmet Şartları bağlantısı (isteğe bağlı): Yetkili bir alanda barındırılmalıdır.

   

   Şekil 1. Kurgusal bir uygulama olan Tunery için Google Hesabı Bağlama İzin Ekranı

4. "Doğrulama Durumu"nu kontrol edin. Uygulamanızın doğrulanması gerekiyorsa "Doğrulamaya Gönder" düğmesini tıklayarak uygulamanızı doğrulamaya gönderin. Ayrıntılar için OAuth doğrulama koşulları bölümüne bakın.

OAuth sunucunuzu uygulama

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authentication and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When a Google application needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

1. Google opens your authorization endpoint in the user's browser. The user signs in, if not signed in already, and grants Google permission to access their data with your API, if they haven't already granted permission.
2. Your service creates an access token and returns it to Google. To do so, redirect the user's browser back to Google with the access token attached to the request.
3. Google calls your service's APIs and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When a Google application needs to perform account linking via an OAuth 2.0 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id	The client ID you assigned to Google.
redirect_uri	The URL to which you send the response to this request.
state	A bookkeeping value that is passed back to Google unchanged in the redirect URI.
response_type	The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.
user_locale	The Google Account language setting in RFC5646 format used to localize your content in the user's preferred language.

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like the following:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

For your authorization endpoint to handle sign-in requests, do the following steps:

1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

   • Confirm that the client_id matches the client ID you assigned to Google.
   • Confirm that the URL specified by the redirect_uri parameter has the following form:

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

2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

3. Generate an access token for Google to use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

   • access_token: The access token you just generated
   • token_type: The string bearer
   • state: The unmodified state value from the original request

   The following is an example of the resulting URL:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler receives the access token and confirms that the state value hasn't changed. After Google has obtained an access token for your service, Google attaches the token to subsequent calls to your service APIs.

处理 userinfo 请求

userinfo 端点是受 OAuth 2.0 保护的资源，会返回关联用户的声明。实现和托管 userinfo 端点是可选的，但以下用例除外：

• 使用 Google One Tap 登录关联的账号。
• Android TV 提供顺畅的订阅体验。

从您的令牌端点成功检索到访问令牌后，Google 会向您的 userinfo 端点发送请求，以检索关联用户的基本个人资料信息。

userinfo 端点请求标头
Authorization header	Bearer 类型的访问令牌。

例如，如果您的 userinfo 端点可通过 https://myservice.example.com/userinfo 时，请求可能如下所示：

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

为了让 userinfo 端点能够处理请求，请执行以下步骤：

1. 从 Authorization 标头中提取访问令牌，并返回与访问令牌相关联的用户的信息。
2. 如果访问令牌无效，则使用 WWW-Authenticate 响应标头返回 HTTP 401 Unauthorized 错误。下面是一个 userinfo 错误响应示例：

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   如果在关联过程中返回 401 未经授权错误或任何其他失败的错误响应，该错误将无法恢复，检索到的令牌将被舍弃，并且用户必须重新开始关联流程。

3. 如果访问令牌有效，则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应 回答：

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   如果您的 userinfo 端点返回 HTTP 200 成功响应，则系统会针对用户的 Google 账号注册检索到的令牌和声明。

   userinfo 端点响应
   sub	系统中用于识别用户的唯一 ID。
   email	用户的电子邮件地址。
   given_name	可选：用户的名字。
   family_name	可选：用户的姓氏。
   name	可选：用户的全名。
   picture	可选：用户的个人资料照片。

Uygulamanızı doğrulama

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击配置 以打开 OAuth 2.0 配置窗口。
2. 在 OAuth flow 字段中，选择 Client-side（客户端）。
3. 在 OAuth 端点字段中，选择自定义。
4. 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
5. 在第 1 步部分，不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围（如果您不使用 OAuth 范围，则可以输入任意字符串）。完成后，点击授权 API。
6. 在 Step 2 和 Step 3 部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示版工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击使用 Google 账号登录按钮。
2. 选择您要关联的账号。
3. 输入服务 ID。
4. （可选）输入您要请求访问权限的一个或多个范围。
5. 点击开始演示。
6. 当系统提示时，请确认您同意或拒绝关联请求。
7. 确认您已被重定向到您的平台。