簡化 OAuth 和 Google 登入機制的連結程序

總覽

以 OAuth 為基礎的 Google 登入簡化連結功能除了加入 Google 登入外, OAuth 連結。這樣就能順暢連結 Google 使用者並可建立帳戶,讓使用者透過自己的 Google 帳戶在您的服務中建立新帳戶。

如要使用 OAuth 和 Google 登入功能進行帳戶連結,請遵循下列一般做法 步驟:

  1. 請先徵得使用者同意,允許存取自己的 Google 個人資料。
  2. 使用設定檔中的資訊檢查使用者帳戶是否存在。
  3. 如果是現有使用者,請連結這些帳戶。
  4. 如果在驗證系統中找不到對應的 Google 使用者, 驗證從 Google 收到的 ID 權杖。接著您可以根據需求建立使用者 儲存在 ID 權杖所含設定檔資訊上
這張圖顯示使用者透過簡化的連結流程來連結 Google 帳戶的步驟。第一張螢幕截圖顯示使用者該如何選取要連結的應用程式。第二個螢幕截圖可讓使用者確認他們是否已使用你的服務帳戶。第三張螢幕截圖可讓使用者選取要連結的 Google 帳戶。第四個螢幕截圖顯示將 Google 帳戶與您的應用程式連結的確認畫面。第五張螢幕截圖顯示 Google 應用程式中成功連結的使用者帳戶。

圖 1. 透過簡化連結程序在使用者手機上進行帳戶連結

精簡連結規定

,瞭解如何調查及移除這項存取權。

實作 OAuth 伺服器

您的權杖交換端點必須支援 checkcreateget 意圖。下方顯示完成帳戶連結流程的步驟,並指出呼叫不同意圖的時機:

  1. 使用者是否在驗證系統中擁有帳戶?(使用者選取「是」或「否」)
    1. 是:使用者是否使用與其 Google 帳戶相關聯的電子郵件地址登入平台?(使用者選取「是」或「否」)
      1. 是 :使用者是否在驗證系統中擁有相符的帳戶?(呼叫 check intent 以確認)
        1. 是:系統會呼叫 get intent,如果成功傳回意圖,就會連結帳戶。
        2. 否 :建立新帳戶?(使用者選取「是」或「否」)
          1. 是:系統會呼叫 create intent,如果建立意圖成功傳回,就會連結帳戶。
          2. 否 :系統會觸發網路 OAuth 流程、將使用者導向瀏覽器,並提供使用者其他電子郵件的連結選項。
      2. 否:系統會觸發網路 OAuth 流程、將使用者導向瀏覽器,並提供其他電子郵件的連結選項。
    2. 否 :使用者是否在驗證系統中擁有相符的帳戶?(呼叫 check intent 以確認)
      1. 是:系統會呼叫 get intent,如果成功傳回意圖,就會連結帳戶。
      2. 否:如果建立意圖成功傳回,系統會呼叫 create intent,並連結帳戶。

檢查現有的使用者帳戶 (檢查意圖)

使用者同意存取自己的 Google 個人資料後,Google 會傳送 要求,包含已簽署的 Google 使用者身分識別資訊。 聲明包含使用者的 Google 帳戶 ID、 姓名、姓名和電子郵件地址為叢集設定的憑證交換端點 就會處理該要求

如果驗證資訊中已有對應的 Google 帳戶 系統,權杖交換端點會以 account_found=true 回應。如果 Google 帳戶與現有使用者不相符,您的權杖交換端點 會傳回 account_found=false 的 HTTP 404 找不到錯誤。

這項要求的格式如下:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

您的權杖交換端點必須能處理下列參數:

權杖端點參數
intent 在這些要求中,這個參數的值為 check
grant_type 要交換的權杖類型。對於這些要求,這個 參數值為 urn:ietf:params:oauth:grant-type:jwt-bearer
assertion JSON Web Token (JWT),提供已簽署 識別使用者的身分JWT 所含資訊包括使用者的 Google 帳戶 ID、名稱和電子郵件地址。
client_id 您指派給 Google 的用戶端 ID。
client_secret 您指派給 Google 的用戶端密鑰。

如要回應 check 意圖要求,您的權杖交換端點必須執行下列步驟:

  • 驗證並解碼 JWT 斷言。
  • 檢查驗證系統是否已有 Google 帳戶。
驗證並解碼 JWT 斷言

您可以使用 適用於您語言的 JWT 解碼程式庫。使用 Google 的公開金鑰,位於 JWK 或 使用 PEM 格式進行驗證 憑證的簽章

解碼後的 JWT 斷言會如下所示:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

除了驗證權杖的簽章外,也請驗證斷言 核發者 (iss 欄位) 為 https://accounts.google.com,目標對象為 (aud 欄位) 是您指派的用戶端 ID,且權杖尚未過期 (exp 欄位)。

您可以使用 emailemail_verifiedhd 欄位判斷 Google 代管且具公信力的電子郵件地址。如果 Google 權威使用者目前是合法帳戶擁有者 可以略過密碼或其他驗證方式此外,這些方法 可用於驗證帳戶再建立連結。

Google 具有公信力的案例:

  • email 的尾碼是 @gmail.com,這是 Gmail 帳戶。
  • email_verified」為 true,且已設定「hd」,代表這是 G Suite 帳戶。

使用者註冊 Google 帳戶時,不必使用 Gmail 或 G Suite。時間 email 未包含 @gmail.com 後置字串,且 hd 不是 Google 建議使用權威性密碼、密碼或其他驗證方法 使用者。email_verified 也可能是 true,因為 Google 一開始就驗證過 使用者就是 Google 帳戶建立時的使用者,但第三方的擁有權 電子郵件帳戶可能會有所變更。

檢查驗證系統是否已有 Google 帳戶

確認是否符合下列任一條件:

  • 在聲明的「sub」欄位中,有 Google 帳戶 ID 代表您的使用者 資料庫
  • 斷言中的電子郵件地址與您使用者資料庫中的使用者相符。

如果其中一個條件為 true,使用者已經註冊。在此情況下 會傳回類似以下的回應:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

如果 Google 帳戶 ID 和 斷言與資料庫中的使用者相符,表示使用者尚未註冊。於 在此情況下,您的權杖交換端點必須回覆 HTTP 404 錯誤 指定 "account_found": "false",如以下範例所示:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

處理自動連結 (取得意圖)

使用者同意存取自己的 Google 個人資料後,Google 會傳送 要求,包含已簽署的 Google 使用者身分識別資訊。 聲明包含使用者的 Google 帳戶 ID、 姓名、姓名和電子郵件地址為叢集設定的憑證交換端點 就會處理該要求

如果驗證資訊中已有對應的 Google 帳戶 系統,您的權杖交換端點會傳回使用者權杖。如果 Google 帳戶與現有使用者不相符,您的權杖交換端點 會傳回 linking_error 錯誤和選用的 login_hint

這項要求的格式如下:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

您的權杖交換端點必須能處理下列參數:

權杖端點參數
intent 在這些要求中,這個參數的值為 get
grant_type 要交換的權杖類型。對於這些要求,這個 參數值為 urn:ietf:params:oauth:grant-type:jwt-bearer
assertion JSON Web Token (JWT),提供已簽署 識別使用者的身分JWT 所含資訊包括使用者的 Google 帳戶 ID、名稱和電子郵件地址。
scope 選用:您設為 Google 要求存取範圍的任何範圍 使用者。
client_id 您指派給 Google 的用戶端 ID。
client_secret 您指派給 Google 的用戶端密鑰。

如要回應 get 意圖要求,您的權杖交換端點必須執行下列步驟:

  • 驗證並解碼 JWT 斷言。
  • 檢查驗證系統是否已有 Google 帳戶。
驗證並解碼 JWT 斷言

您可以使用 適用於您語言的 JWT 解碼程式庫。使用 Google 的公開金鑰,位於 JWK 或 使用 PEM 格式進行驗證 憑證的簽章

解碼後的 JWT 斷言會如下所示:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

除了驗證權杖的簽章外,也請驗證斷言 核發者 (iss 欄位) 為 https://accounts.google.com,目標對象為 (aud 欄位) 是您指派的用戶端 ID,且權杖尚未過期 (exp 欄位)。

您可以使用 emailemail_verifiedhd 欄位判斷 Google 代管且具公信力的電子郵件地址。如果 Google 權威使用者目前是合法帳戶擁有者 可以略過密碼或其他驗證方式此外,這些方法 可用於驗證帳戶再建立連結。

Google 具有公信力的案例:

  • email 的尾碼是 @gmail.com,這是 Gmail 帳戶。
  • email_verified」為 true,且已設定「hd」,代表這是 G Suite 帳戶。

使用者註冊 Google 帳戶時,不必使用 Gmail 或 G Suite。時間 email 未包含 @gmail.com 後置字串,且 hd 不是 Google 建議使用權威性密碼、密碼或其他驗證方法 使用者。email_verified 也可能是 true,因為 Google 一開始就驗證過 使用者就是 Google 帳戶建立時的使用者,但第三方的擁有權 電子郵件帳戶可能會有所變更。

檢查驗證系統是否已有 Google 帳戶

確認是否符合下列任一條件:

  • 在聲明的「sub」欄位中,有 Google 帳戶 ID 代表您的使用者 資料庫
  • 斷言中的電子郵件地址與您使用者資料庫中的使用者相符。

如果找到使用者的帳戶,請核發存取權杖,並以 JSON 物件傳回 HTTPS 回應內文中的值,如以下範例所示:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

在某些情況下,根據 ID 權杖進行帳戶連結的使用者可能會失敗。如果是 因為無論出於什麼原因,您的權杖交換端點都必須以 HTTP 指定 error=linking_error 的 401 錯誤,如以下範例所示:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

當 Google 收到含有 linking_error 的 401 錯誤回應時, 將使用者傳送至您的授權端點,並以 login_hint 做為參數。 使用者在瀏覽器中使用 OAuth 連結流程完成帳戶連結。

透過 Google 登入功能處理帳戶建立作業 (建立意圖)

當使用者需要在您的服務上建立帳戶時,Google 會提出要求 附加至指定 intent=create 的權杖交換端點。

這項要求的格式如下:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

您的權杖交換端點必須能處理下列參數:

權杖端點參數
intent 在這些要求中,這個參數的值為 create
grant_type 要交換的權杖類型。對於這些要求,這個 參數值為 urn:ietf:params:oauth:grant-type:jwt-bearer
assertion JSON Web Token (JWT),提供已簽署 識別使用者的身分JWT 所含資訊包括使用者的 Google 帳戶 ID、名稱和電子郵件地址。
client_id 您指派給 Google 的用戶端 ID。
client_secret 您指派給 Google 的用戶端密鑰。

assertion 參數中的 JWT 包含使用者的 Google 帳戶 ID。 姓名和電子郵件地址;您可以在 課程中也會快速介紹 Memorystore 這是 Google Cloud 的全代管 Redis 服務

如要回應 create 意圖要求,您的權杖交換端點必須執行下列步驟:

  • 驗證並解碼 JWT 斷言。
  • 驗證使用者資訊並建立新帳戶。
驗證並解碼 JWT 斷言

您可以使用 適用於您語言的 JWT 解碼程式庫。使用 Google 的公開金鑰,位於 JWK 或 使用 PEM 格式進行驗證 憑證的簽章

解碼後的 JWT 斷言會如下所示:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

除了驗證權杖的簽章外,也請驗證斷言 核發者 (iss 欄位) 為 https://accounts.google.com,目標對象為 (aud 欄位) 是您指派的用戶端 ID,且權杖尚未過期 (exp 欄位)。

您可以使用 emailemail_verifiedhd 欄位判斷 Google 代管且具公信力的電子郵件地址。如果 Google 權威使用者目前是合法帳戶擁有者 可以略過密碼或其他驗證方式此外,這些方法 可用於驗證帳戶再建立連結。

Google 具有公信力的案例:

  • email 的尾碼是 @gmail.com,這是 Gmail 帳戶。
  • email_verified」為 true,且已設定「hd」,代表這是 G Suite 帳戶。

使用者註冊 Google 帳戶時,不必使用 Gmail 或 G Suite。時間 email 未包含 @gmail.com 後置字串,且 hd 不是 Google 建議使用權威性密碼、密碼或其他驗證方法 使用者。email_verified 也可能是 true,因為 Google 一開始就驗證過 使用者就是 Google 帳戶建立時的使用者,但第三方的擁有權 電子郵件帳戶可能會有所變更。

驗證使用者資訊並建立新帳戶

確認是否符合下列任一條件:

  • 在聲明的「sub」欄位中,有 Google 帳戶 ID 代表您的使用者 資料庫
  • 斷言中的電子郵件地址與您使用者資料庫中的使用者相符。

只要符合任一條件,就會提示使用者連結現有帳戶 使用自己的 Google 帳戶。方法是回應要求,並傳回 HTTP 401 錯誤 指定 error=linking_error,並提供使用者的電子郵件地址做為 login_hint。以下是回應範例:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

當 Google 收到含有 linking_error 的 401 錯誤回應時, 將使用者傳送至您的授權端點,並以 login_hint 做為參數。 使用者在瀏覽器中使用 OAuth 連結流程完成帳戶連結。

如果兩個條件皆不成立,請以這些資訊建立新的使用者帳戶 使用這組 API新帳戶通常不會設定密碼。是 建議您在其他平台中加入 Google 登入功能,方便使用者 使用 Google 帳戶登入或者,您也可以 是否可以透過電子郵件將密碼復原流程的連結傳送給使用者,以便允許 使用者設定密碼以登入其他平台。

建立完畢後,請核發存取權杖 然後重新整理權杖 ,並傳回 JSON 物件中 也就是您的 HTTPS 回應內文,如以下範例所示:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

取得 Google API 用戶端 ID

在帳戶連結註冊程序期間,系統會要求您提供 Google API 用戶端 ID。

如要使用您在完成 OAuth 連結步驟時建立的專案取得 API 用戶端 ID,若要這樣做,請完成下列步驟:

  1. 開啟 Cloud Shell 的「Credentials」(憑證) 頁面, Google API 控制台
  2. 建立或選取 Google API 專案。

    如果專案沒有網頁應用程式類型的用戶端 ID,請按一下 建立憑證 >OAuth 用戶端 ID要建立。請務必附上 在「已授權的 JavaScript 來源」方塊中找出您網站的網域。當你在 本機測試或開發,您必須同時新增 http://localhost 和 將 http://localhost:<port_number> 設為「已授權的 JavaScript 來源」欄位。

驗證實作

您可以通過使用驗證實現的OAuth 2.0遊樂場工具。

在工具中,執行以下步驟:

  1. 單擊配置打開的OAuth 2.0配置窗口。
  2. OAuth流場中,選擇客戶端
  3. OAuth端點字段中,選擇自定義
  4. 在相應字段中指定您的 OAuth 2.0 端點和您分配給 Google 的客戶端 ID。
  5. 步驟1部分,不要選擇任何谷歌範圍。相反,將此字段留空或鍵入對您的服務器有效的範圍(如果不使用 OAuth 範圍,則輸入任意字符串)。當您完成後,單擊授權的API。
  6. 步驟2步驟3段,完成OAuth 2.0流程和驗證每個步驟按預期工作。

您可以通過驗證您的實現谷歌帳戶鏈接演示工具。

在工具中,執行以下步驟:

  1. 點擊登錄在與谷歌按鈕。
  2. 選擇您要關聯的帳戶。
  3. 輸入服務標識。
  4. (可選)輸入您將請求訪問的一個或多個範圍。
  5. 單擊開始演示
  6. 出現提示時,確認您可以同意並拒絕鏈接請求。
  7. 確認您被重定向到您的平台。