Collegamento semplificato con OAuth e Accedi con Google

Panoramica

Il collegamento semplificato di Accedi con Google basato su OAuth aggiunge Accedi con Google oltre ad altre funzionalità. Collegamento OAuth. Ciò fornisce un'esperienza di collegamento perfetta per Per gli utenti Google e consente anche la creazione di account, che consente all'utente di creare un nuovo account sul tuo servizio utilizzando il proprio Account Google.

Per eseguire il collegamento dell'account con OAuth e Accedi con Google, segui queste informazioni generali passaggi:

  1. Per prima cosa, chiedi all'utente di dare il consenso per accedere al suo profilo Google.
  2. Utilizzare le informazioni presenti nel profilo dell'utente per verificare se l'account utente esiste.
  3. Per gli utenti esistenti, collega gli account.
  4. Se non riesci a trovare una corrispondenza per l'utente Google nel tuo sistema di autenticazione, convalidare il token ID ricevuto da Google. Puoi quindi creare un'interfaccia utente nelle informazioni del profilo contenute nel token ID.
Questa figura mostra i passaggi necessari a un utente per collegare il proprio Account Google utilizzando il flusso di collegamento semplificato. Il primo screenshot mostra in che modo un utente può selezionare la tua app per il collegamento. Il secondo screenshot consente all'utente di confermare se dispone o meno di un account esistente nel tuo servizio. Il terzo screenshot consente all'utente di selezionare l'Account Google a cui vuole collegarsi. Il quarto screenshot mostra la conferma del collegamento dell'Account Google alla tua app. Il quinto screenshot mostra un account utente collegato correttamente nell'app Google.

Figura 1. Collegamento dell'account sullo smartphone di un utente con Collegamento semplificato

Requisiti per il collegamento semplificato

di Gemini Advanced.

Implementare il server OAuth

L'endpoint per lo scambio di token deve supportare gli intent check, create e get. Di seguito sono riportati i passaggi completati durante la procedura di collegamento dell'account e viene indicato quando vengono richiamati i diversi intent:

  1. L'utente dispone di un account nel tuo sistema di autenticazione? (L'utente decide selezionando SÌ o NO)
    1. SÌ : l'utente utilizza l'indirizzo email associato al proprio Account Google per accedere alla piattaforma? (L'utente decide selezionando SÌ o NO)
      1. SÌ : l'utente dispone di un account corrispondente nel tuo sistema di autenticazione? (check intent viene chiamato per confermare)
        1. SÌ : get intent viene chiamato e l'account viene collegato se la richiesta di ritorno per intenzione riesce.
        2. NO : creare un nuovo account? (L'utente decide selezionando SÌ o NO)
          1. SÌ : create intent viene chiamato e l'account viene collegato se la funzionalità di creazione dell'intent viene restituita correttamente.
          2. NO : viene attivato il flusso OAuth per il web, l'utente viene indirizzato al browser e gli viene offerta la possibilità di collegarsi a un indirizzo email diverso.
      2. NO : viene attivato il flusso OAuth web, l'utente viene indirizzato al browser e gli viene offerta la possibilità di collegarsi a un'altra email.
    2. NO : l'utente dispone di un account corrispondente nel tuo sistema di autenticazione? (check intent viene chiamato per confermare)
      1. SÌ : get intent viene chiamato e l'account viene collegato se la richiesta di ritorno per intenzione riesce.
      2. NO : create intent viene chiamato e l'account viene collegato se la funzionalità di creazione dell'intent viene restituita correttamente.

Verificare la presenza di un account utente esistente (check intent)

Dopo che l'utente acconsente ad accedere al proprio profilo Google, Google invia una contenente un'asserzione firmata dell'identità dell'utente Google. La l'asserzione contiene informazioni che includono l'ID dell'Account Google dell'utente, nome e indirizzo email. L'endpoint di scambio di token configurato per il progetto gestisce la richiesta.

Se l'Account Google corrispondente è già presente nella tua autenticazione di sistema, il tuo endpoint di scambio di token risponde con account_found=true. Se L'Account Google non corrisponde a un utente esistente, il tuo endpoint di scambio di token restituisce un errore HTTP 404 - Non trovato con account_found=false.

La richiesta ha il seguente modulo:

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

L'endpoint di scambio di token deve essere in grado di gestire i seguenti parametri:

Parametri endpoint token
intent Per queste richieste, il valore di questo parametro è check.
grant_type Il tipo di token che viene scambiato. Per queste richieste, ha il valore urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion un token JWT (JSON Web Token) che fornisce un'asserzione firmata dei l'identità dell'utente. Il JWT contiene informazioni che includono il ID dell'Account Google, nome e indirizzo email.
client_id L'ID client che hai assegnato a Google.
client_secret Il client secret che hai assegnato a Google.

Per rispondere alle richieste di intent check, l'endpoint dello scambio di token deve eseguire i seguenti passaggi:

  • Convalida e decodifica l'asserzione JWT.
  • Verifica se l'Account Google è già presente nel sistema di autenticazione.
验证和解码 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 字段）。

使用 email、email_verified 和 hd 字段，您可以确定 Google 负责托管电子邮件地址，并对其具有权威性。如果 Google 权威性 - 用户当前被认定为合法账号所有者 您可以跳过密码或其他验证方法。否则，这些方法 可用于在关联之前验证账号。

Google 具有权威性的情形：

  • email 的后缀为 @gmail.com，这是一个 Gmail 账号。
  • email_verified 为 true 且 hd 已设置，这是 G Suite 账号。

用户无需使用 Gmail 或 G Suite 即可注册 Google 账号。时间 email 不包含 @gmail.com 后缀，且 hd 不存在 Google 不 建议使用权威凭据和密码或其他验证方法进行验证 用户。email_verified 可能为 true，因为 Google 最初验证了 创建 Google 账号后，该用户会获得第三方的所有权， 后，电子邮件账号可能已更改。

Controllare se l'Account Google è già presente nel sistema di autenticazione

Controlla se è vera una delle seguenti condizioni:

  • L'ID Account Google, che si trova nel campo sub dell'asserzione, è nel tuo utente per configurare un database.
  • L'indirizzo email nell'asserzione corrisponde a un utente nel tuo database utenti.

Se una delle condizioni è vera, l'utente ha già effettuato la registrazione. In questo caso, restituiscono una risposta simile alla seguente:

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

{
  "account_found":"true",
}

Se né l'ID Account Google né l'indirizzo email specificato nella asserzione corrisponde a un utente presente nel tuo database, l'utente non si è ancora registrato. Nella In questo caso, l'endpoint di scambio di token deve rispondere con un errore HTTP 404. che specifica "account_found": "false", come nell'esempio seguente:

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

{
  "account_found":"false",
}

Gestire il collegamento automatico (ottenere l'intenzione)

Dopo che l'utente acconsente ad accedere al proprio profilo Google, Google invia una contenente un'asserzione firmata dell'identità dell'utente Google. La l'asserzione contiene informazioni che includono l'ID dell'Account Google dell'utente, nome e indirizzo email. L'endpoint di scambio di token configurato per il progetto gestisce la richiesta.

Se l'Account Google corrispondente è già presente nell'autenticazione il tuo endpoint di scambio di token restituisce un token per l'utente. Se L'Account Google non corrisponde a un utente esistente, il tuo endpoint di scambio di token restituisce un errore linking_error e un valore facoltativo per il campo login_hint.

La richiesta ha il seguente modulo:

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

L'endpoint di scambio di token deve essere in grado di gestire i seguenti parametri:

Parametri endpoint token
intent Per queste richieste, il valore di questo parametro è get.
grant_type Il tipo di token che viene scambiato. Per queste richieste, ha il valore urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion un token JWT (JSON Web Token) che fornisce un'asserzione firmata dei l'identità dell'utente. Il JWT contiene informazioni che includono il ID dell'Account Google, nome e indirizzo email.
scope Facoltativo:tutti gli ambiti che hai configurato per le richieste da parte di Google utenti.
client_id L'ID client che hai assegnato a Google.
client_secret Il client secret che hai assegnato a Google.

Per rispondere alle richieste di intent get, l'endpoint dello scambio di token deve eseguire i seguenti passaggi:

  • Convalida e decodifica l'asserzione JWT.
  • Verifica se l'Account Google è già presente nel sistema di autenticazione.
验证和解码 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 字段）。

使用 email、email_verified 和 hd 字段，您可以确定 Google 负责托管电子邮件地址，并对其具有权威性。如果 Google 权威性 - 用户当前被认定为合法账号所有者 您可以跳过密码或其他验证方法。否则，这些方法 可用于在关联之前验证账号。

Google 具有权威性的情形：

  • email 的后缀为 @gmail.com，这是一个 Gmail 账号。
  • email_verified 为 true 且 hd 已设置，这是 G Suite 账号。

用户无需使用 Gmail 或 G Suite 即可注册 Google 账号。时间 email 不包含 @gmail.com 后缀，且 hd 不存在 Google 不 建议使用权威凭据和密码或其他验证方法进行验证 用户。email_verified 可能为 true，因为 Google 最初验证了 创建 Google 账号后，该用户会获得第三方的所有权， 后，电子邮件账号可能已更改。

Controllare se l'Account Google è già presente nel sistema di autenticazione

Controlla se è vera una delle seguenti condizioni:

  • L'ID Account Google, che si trova nel campo sub dell'asserzione, è nel tuo utente per configurare un database.
  • L'indirizzo email nell'asserzione corrisponde a un utente nel tuo database utenti.

Se viene trovato un account per l'utente, invia un token di accesso e restituisci i valori in un oggetto JSON nel corpo della risposta HTTPS, come nell'esempio seguente: 

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

  "expires_in": SECONDS_TO_EXPIRATION
}

In alcuni casi, il collegamento dell'account basato sul token ID potrebbe non riuscire per l'utente. Se lo fa per qualsiasi motivo, l'endpoint di scambio di token deve rispondere con un Errore 401 che specifica error=linking_error, come mostrato nell'esempio seguente:

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

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

Quando Google riceve una risposta di errore 401 con linking_error, invia l'utente all'endpoint di autorizzazione con login_hint come parametro. La l'utente completa il collegamento dell'account utilizzando il flusso di collegamento OAuth nel proprio browser.

通过 Google 登录功能处理账号创建（创建 intent）

当用户需要在您的服务中创建账号时，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 令牌 (JWT)，提供 Google 用户身份。JWT 包含的信息包括用户 Google 账号 ID、姓名和电子邮件地址。
client_id 您分配给 Google 的客户 ID。
client_secret 您分配给 Google 的客户端密钥。

assertion 参数中的 JWT 包含用户的 Google 账号 ID。 姓名和电子邮件地址，可用于在 Gmail 中创建新账号 服务。

如需响应 create intent 请求，您的令牌交换端点必须执行以下步骤：

  • 验证和解码 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 字段）。

使用 email、email_verified 和 hd 字段，您可以确定 Google 负责托管电子邮件地址，并对其具有权威性。如果 Google 权威性 - 用户当前被认定为合法账号所有者 您可以跳过密码或其他验证方法。否则，这些方法 可用于在关联之前验证账号。

Google 具有权威性的情形：

  • email 的后缀为 @gmail.com，这是一个 Gmail 账号。
  • email_verified 为 true 且 hd 已设置，这是 G Suite 账号。

用户无需使用 Gmail 或 G Suite 即可注册 Google 账号。时间 email 不包含 @gmail.com 后缀，且 hd 不存在 Google 不 建议使用权威凭据和密码或其他验证方法进行验证 用户。email_verified 可能为 true，因为 Google 最初验证了 创建 Google 账号后，该用户会获得第三方的所有权， 后，电子邮件账号可能已更改。

验证用户信息并创建新账号

请检查以下任一条件是否成立：

  • Google 账号 ID（可在断言的 sub 字段中找到）位于您的用户中 数据库。
  • 断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足上述任一条件，请提示用户关联其现有账号 与其 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 关联流程完成账号关联。

如果以上两个条件都不满足，请使用相应信息创建一个新的用户账号 。新账号通常不会设置密码。时间是 建议您将 Google 登录功能添加到其他平台，以便用户 使用 Google 账号登录。或者 可以通过电子邮件向用户发送链接，启动密码恢复流程，以允许 用户设置密码，以便在其他平台上登录。

创建完成后，发出一个访问令牌 并在 HTTPS 响应的正文，如以下示例所示： 

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

  "expires_in": SECONDS_TO_EXPIRATION
}

Ottenere l'ID client API di Google

Ti verrà chiesto di fornire il tuo ID client API di Google durante la procedura di registrazione al collegamento degli account.

Per ottenere il tuo ID client API tramite il progetto che hai creato durante il completamento dei passaggi di collegamento OAuth. Per farlo, segui questa procedura.

  1. Apri la pagina Credentials (Credenziali) della Console API di Google.

  2. Crea o seleziona un progetto delle API di Google.

    Se il progetto non ha un ID client per il tipo di applicazione web, fai clic su Crea le credenziali > ID client OAuth per crearne uno. Assicurati di includere al dominio del tuo sito nella casella Origini JavaScript autorizzate. Quando esegui per i test o lo sviluppo locale, devi aggiungere sia http://localhost http://localhost:<port_number> al campo Origini JavaScript autorizzate.

Convalida dell'implementazione

È possibile convalidare l'implementazione utilizzando il parco giochi OAuth 2.0 strumento.

Nello strumento, eseguire le seguenti operazioni:

  1. Fare clic su Configurazione per aprire la finestra di configurazione OAuth 2.0.
  2. Nel campo di flusso OAuth, selezionare sul lato client.
  3. Nel campo OAuth endpoint, selezionare Personalizzato.
  4. Specifica il tuo endpoint OAuth 2.0 e l'ID client che hai assegnato a Google nei campi corrispondenti.
  5. Nella sezione Passaggio 1, non selezionare tutti gli ambiti di Google. Lascia invece vuoto questo campo o digita un ambito valido per il tuo server (o una stringa arbitraria se non utilizzi gli ambiti OAuth). Quando hai finito, clicca API Autorizza.
  6. Nelle sezioni Fase 2 e Fase 3, passare attraverso il flusso OAuth 2.0 e verificare che ogni passo funziona come previsto.

È possibile convalidare l'implementazione utilizzando l' account Google Linking Demo strumento.

Nello strumento, eseguire le seguenti operazioni:

  1. Fare clic sul segno-in con pulsante di Google.
  2. Scegli l'account che desideri collegare.
  3. Inserisci l'ID del servizio.
  4. Facoltativamente, inserisci uno o più ambiti per i quali richiedere l'accesso.
  5. Fare clic su Start Demo.
  6. Quando richiesto, conferma che puoi acconsentire e negare la richiesta di collegamento.
  7. Conferma di essere reindirizzato alla tua piattaforma.