Se usó la API de Cloud Translation para traducir esta página.

Vinculación de Cuentas de Google con OAuth

Las cuentas se vinculan mediante los flujos implícitos y de código de autorización de OAuth 2.0 estándar de la industria. Tu servicio debe ser compatible con los extremos de autorización y intercambio de tokens que cumplan con OAuth 2.0.

En el flujo implícito, Google abre el extremo de autorización en el navegador del usuario. Después de que el acceso sea exitoso, se muestra un token de acceso de larga duración a Google. Este token de acceso ahora se incluye en cada solicitud enviada desde Google.

En el flujo de código de autorización, necesitas dos extremos:

El extremo de autorización, que presenta la IU de acceso a los usuarios que aún no accedieron. El extremo de autorización también crea un código de autorización de corta duración para registrar el acceso solicitado por los usuarios.
El extremo de intercambio de tokens, que es responsable de dos tipos de intercambios:
1. Intercambia un código de autorización por un token de actualización de larga duración y un token de acceso de corta duración. Este intercambio se produce cuando el usuario pasa por el flujo de vinculación de cuentas.
2. Intercambia un token de actualización de larga duración por un token de acceso de corta duración. Este intercambio se produce cuando Google necesita un nuevo token de acceso porque venció.

Elige un flujo de OAuth 2.0

Aunque el flujo implícito es más fácil de implementar, Google recomienda que los tokens de acceso emitidos por el flujo implícito nunca venzan. Esto se debe a que el usuario se ve obligado a vincular su cuenta de nuevo después de que un token caduque con el flujo implícito. Si necesitas el vencimiento del token por razones de seguridad, te recomendamos que uses el flujo de código de autorización en su lugar.

Pautas de diseño

En esta sección, se describen los requisitos de diseño y las recomendaciones para la pantalla del usuario que alojas en los flujos de vinculación de OAuth. Una vez que la app la llama, tu plataforma le muestra al usuario un acceso a la página de Google y a la pantalla de consentimiento de vinculación de la cuenta. Cuando el usuario da su consentimiento para vincular las cuentas, se lo redirige a la app de Google.

En esta figura, se muestran los pasos para que un usuario vincule su Cuenta de Google a tu sistema de autenticación. La primera captura de pantalla muestra vínculos iniciados por el usuario desde tu plataforma. En la segunda, se muestra el acceso del usuario a Google, mientras que la tercera muestra el consentimiento y la confirmación para vincular su Cuenta de Google con tu app. En la última captura de pantalla, se muestra una cuenta de usuario vinculada correctamente en Google app. — **Figura 1:** Cuenta de vinculación de usuarios que accede a Google y a las pantallas de consentimiento.

Requisitos

Debes comunicar que la cuenta del usuario se vinculará a Google, no a un producto de Google específico, como Google Home o el Asistente de Google.

Recomendaciones

Crea el proyecto

Para crear tu proyecto y usar la vinculación de cuentas, sigue estos pasos:

Go to the Google API Console.
Haz clic en Crear proyecto .
Ingrese un nombre o acepte la sugerencia generada.
Confirme o edite los campos restantes.
Haz clic en Crear .

Para ver su ID de proyecto:

Go to the Google API Console.
Encuentra tu proyecto en la tabla de la página de inicio. El ID del proyecto aparece en la columna ID .

Configura la pantalla de consentimiento de OAuth

El proceso de vinculación de cuentas de Google incluye una pantalla de consentimiento que indica a los usuarios la aplicación que solicita acceso a sus datos, qué tipo de datos están solicitando y las condiciones correspondientes. Deberás configurar la pantalla de consentimiento de OAuth antes de generar un ID de cliente de la API de Google.

Abre la página Pantalla de consentimiento de OAuth de la consola de APIs de Google.
Si se te solicita, selecciona el proyecto que acabas de crear.
En la página "Pantalla de consentimiento de OAuth", completa el formulario y haz clic en el botón "Guardar".

Nombre de la aplicación: Es el nombre de la aplicación que solicita el consentimiento. El nombre debe reflejar tu aplicación con exactitud y ser coherente con el nombre que los usuarios ven en otros lugares. El nombre de la aplicación se mostrará en la pantalla de consentimiento de la vinculación de cuentas.

Logotipo de la aplicación: Es una imagen en la pantalla de consentimiento que ayudará a los usuarios a reconocer tu app. El logotipo se muestra en la pantalla de consentimiento de vinculación de cuentas y en la configuración de la cuenta.

Correo electrónico de asistencia: Permite que los usuarios se comuniquen contigo si tienen preguntas sobre su consentimiento.

Alcances para las APIs de Google: los permisos permiten que tu aplicación acceda a los datos privados de Google de tu usuario. Para el caso de uso de la vinculación de Cuentas de Google, el alcance predeterminado (email, profile, openid) es suficiente; no necesitas agregar ningún alcance sensible. Por lo general, se recomienda solicitar alcances de forma incremental cuando se requiere acceso, en lugar de hacerlo de forma anticipada. Más información

Dominios autorizados: Para protegerlos a ti y a tus usuarios, Google solo permite que las aplicaciones que se autentiquen con OAuth usen dominios autorizados. Los vínculos de tus aplicaciones deben estar alojados en dominios autorizados. Más información

Vínculo a la página principal de la aplicación: Es la página principal de tu aplicación. Debe estar alojado en un dominio autorizado.

Vínculo a la Política de Privacidad de la aplicación: Se muestra en la pantalla de consentimiento de la vinculación de la Cuenta de Google. Debe estar alojado en un dominio autorizado.

Vínculo de las Condiciones del Servicio de la aplicación (opcional): Se debe alojar en un dominio autorizado.

Figura 1: Pantalla de consentimiento de vinculación de Cuentas de Google para una aplicación ficticia, Tunery
Revisa el "Estado de verificación" y, si es necesario verificar tu aplicación, haz clic en el botón "Enviar para verificación" a fin de enviarla para que se verifique. Consulta los requisitos de verificación de OAuth para obtener más información.

Implementa tu servidor OAuth

授权码流的的OAuth 2.0服务器实现由两个端点，通过HTTPS，你的服务使可用的。第一个端点是授权端点，它负责查找或获得用户对数据访问的同意。授权端点向尚未登录的用户显示登录 UI，并记录对请求访问的同意。第二个端点是令牌交换端点，用于获取加密字符串，称为令牌，授权用户访问您的服务。

当 Google 应用程序需要调用您的服务的某个 API 时，Google 会结合使用这些端点来获得您的用户的许可，以代表他们调用这些 API。

Google发起的一次OAuth 2.0授权码流会话流程如下：

Google 在用户的浏览器中打开您的授权端点。如果流程在 Action 的纯语音设备上开始，Google 会将执行转移到手机。
用户登录（如果尚未登录）并授予 Google 使用您的 API 访问其数据的权限（如果他们尚未授予权限）。
您的服务创建一个授权码，并返回给谷歌。为此，请将用户的浏览器重定向回 Google，并将授权代码附加到请求中。
谷歌发送授权代码，您的令牌交换终结，从而验证代码的真实性，并返回一个访问令牌和刷新令牌。访问令牌是一个短期令牌，您的服务接受它作为访问 API 的凭据。刷新令牌是一个长期存在的令牌，Google 可以存储它并在它们到期时使用它来获取新的访问令牌。
用户完成帐户关联流程后，从 Google 发送的每个后续请求都包含一个访问令牌。

处理授权请求

当您需要使用 OAuth 2.0 授权代码流执行帐户关联时，Google 会将用户发送到您的授权端点，并发送一个包含以下参数的请求：

授权端点参数
`client_id`	您分配给 Google 的客户 ID。
`redirect_uri`	您向其发送对此请求的响应的 URL。
`state`	传递回 Google 的簿记值在重定向 URI 中保持不变。
`scope`	可选：以空格分隔的集合，其指定谷歌正在请求授权的数据范围的字符串。
`response_type`	要在响应中返回的值的类型。对于的OAuth 2.0授权码流，响应类型总是`code` 。
`user_locale`	在谷歌帐户语言设置RFC5646格式，用于本地化用户的首选语言内容。

例如，如果您的授权端点可在https://myservice.example.com/auth ，请求看起来像下面这样：

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

对于处理登录请求的授权端点，请执行以下步骤：

验证client_id您分配给谷歌的客户ID匹配，并且该redirect_uri由谷歌为您服务提供的重定向URL匹配。这些检查对于防止授予对意外或配置错误的客户端应用程序的访问权限非常重要。如果你支持多种OAuth 2.0流程的，也确认response_type是code 。
检查用户是否已登录您的服务。如果用户未登录，请完成服务的登录或注册流程。
生成供 Google 用于访问您的 API 的授权代码。授权码可以是任何字符串值，但必须唯一代表用户、token所针对的客户端、授权码的过期时间，并且不能被猜到。您通常会发出大约 10 分钟后过期的授权代码。

确认URL指定由redirect_uri参数有以下形式：

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

重定向用户的浏览器由指定的URL redirect_uri参数。当你通过附加重定向包括刚刚生成授权码和原始未修正的状态值code和state参数。以下是所得的URL的一个示例：
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
```

处理令牌交换请求

您的服务的令牌交换端点负责两种令牌交换：

交换访问令牌和刷新令牌的授权代码
交换刷新令牌以获取访问令牌

令牌交换请求包括以下参数：

令牌交换端点参数
`client_id`	将请求源标识为 Google 的字符串。此字符串必须在您的系统中注册为 Google 的唯一标识符。
`client_secret`	您在 Google 上为您的服务注册的秘密字符串。
`grant_type`	被交换的代币类型。这是不是`authorization_code`或`refresh_token` 。
`code`	当`grant_type=authorization_code` ，这个参数是从您登录或令牌交换终结收到谷歌的代码。
`redirect_uri`	当`grant_type=authorization_code` ，该参数是在初始授权请求中使用的URL。
`refresh_token`	当`grant_type=refresh_token` ，这个参数是令牌从令牌交换终结收到谷歌的刷新。

交换访问令牌和刷新令牌的授权代码

在用户登录并且您的授权端点向 Google 返回一个短期授权代码后，Google 会向您的令牌交换端点发送请求，以交换访问令牌和刷新令牌的授权代码。

对于这些请求，价值grant_type是authorization_code ，和值code是您先前授予给谷歌授权码的值。以下是为访问令牌和刷新令牌交换授权代码的请求示例：

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

要为访问Exchange授权码令牌和刷新令牌，您的令牌交换终结响应POST通过执行以下步骤要求：

验证该client_id识别为授权原点，并且所述请求源client_secret预期值相匹配。
验证授权码是否有效且未过期，以及请求中指定的客户端 ID 是否与与授权码关联的客户端 ID 匹配。
确认URL中指定由redirect_uri参数是相同的初始授权请求中使用的值。
如果您无法验证所有的上述标准，则返回一个HTTP 400错误的请求错误与{"error": "invalid_grant"}作为身体。
否则，使用授权代码中的用户 ID 生成刷新令牌和访问令牌。这些令牌可以是任何字符串值，但它们必须唯一地代表令牌所针对的用户和客户端，并且不能被猜测。对于访问令牌，还要记录令牌的到期时间，通常是您发出令牌后的一个小时。刷新令牌不会过期。

返回以下JSON对象在HTTPS响应的主体：

{
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

Google 为用户存储访问令牌和刷新令牌，并记录访问令牌的到期时间。当访问令牌过期时，Google 使用刷新令牌从您的令牌交换端点获取新的访问令牌。

交换刷新令牌以获取访问令牌

当访问令牌过期时，Google 会向您的令牌交换端点发送请求，以将刷新令牌交换为新的访问令牌。

对于这些请求，价值grant_type被refresh_token ，和值refresh_token是令牌先前授予谷歌刷新的值。以下是将刷新令牌交换为访问令牌的请求示例：

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

要交换令牌的访问令牌刷新，您的令牌交换终结响应POST通过执行以下步骤要求：

验证client_id标识请求起源谷歌，那client_secret预期值相符。
验证刷新令牌是否有效，以及请求中指定的客户端 ID 是否与与刷新令牌关联的客户端 ID 匹配。
如果您无法验证所有的上述标准，则返回一个HTTP 400错误的请求错误与{"error": "invalid_grant"}作为身体。
否则，使用刷新令牌中的用户 ID 生成访问令牌。这些令牌可以是任何字符串值，但它们必须唯一地代表令牌所针对的用户和客户端，并且它们不能被猜测。对于访问令牌，还要记录令牌的到期时间，通常是在您发出令牌后的一个小时。

在 HTTPS 响应的正文中返回以下 JSON 对象：

{
"token_type": "Bearer",
"access_token": " ACCESS_TOKEN ",
"expires_in": SECONDS_TO_EXPIRATION
}

Manejar solicitudes de información de usuario

El punto final userinfo es un recurso protegido OAuth 2.0 que las reclamaciones de retorno sobre el usuario vinculado. La implementación y el alojamiento del punto final de userinfo es opcional, excepto en los siguientes casos de uso:

Vinculado cuenta Inicio de sesión con Google un toque.
Suscripción sin fricción en Android TV.

Una vez que el token de acceso se ha recuperado correctamente de su punto final de token, Google envía una solicitud a su punto final de información de usuario para recuperar información de perfil básica sobre el usuario vinculado.

encabezados de solicitud de punto final de userinfo
`Authorization header`	El token de acceso de tipo Bearer.

Por ejemplo, si su userinfo punto final está disponible en https://myservice.example.com/userinfo , una solicitud puede tener un aspecto como el siguiente:

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

Para que su punto final de userinfo maneje las solicitudes, siga los siguientes pasos:

Extraiga el token de acceso del encabezado de autorización y devuelva la información para el usuario asociado con el token de acceso.
Si el token de acceso no es válido, devuelve un error HTTP 401 no autorizado con el uso de la WWW-Authenticate encabezado de respuesta. A continuación se muestra un ejemplo de una respuesta de error userinfo:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
Si un 401 no autorizado, o cualquier otra respuesta de error sin éxito se devuelve durante el proceso de vinculación, el error será no recuperable, el token recuperada será descartado y el usuario tendrá para iniciar el proceso de vinculación nuevamente.

Si el token de acceso es válido, el retorno y la respuesta HTTP 200 con el siguiente objeto JSON en el cuerpo de la respuesta HTTPS:

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

Si su userinfo de punto final devuelve una respuesta de éxito HTTP 200, el recuperado token y reclamaciones se registran en contra de Google del usuario cuenta.

respuesta del punto final de userinfo
`sub`	Una identificación única que identifica al usuario en su sistema.
`email`	Dirección de correo electrónico del usuario.
`given_name`	Opcional: Nombre del usuario.
`family_name`	Opcional: Apellido del usuario.
`name`	Opcional: Nombre completo del usuario.
`picture`	Opcional: Foto del perfil de usuario.

Cómo validar la implementación

Puede validar su aplicación mediante el uso de la Zona de juegos OAuth 2.0 herramienta.

En la herramienta, siga los siguientes pasos:

Haga clic en Configuración de para abrir la ventana de configuración de OAuth 2.0.
En el campo de flujo de OAuth, seleccione el lado del cliente.
En el campo de OAuth puntos finales, seleccione Personalizar.
Especifique su punto final de OAuth 2.0 y el ID de cliente que asignó a Google en los campos correspondientes.
En la sección Paso 1, no seleccione ninguna alcances de Google. En su lugar, deje este campo en blanco o escriba un ámbito válido para su servidor (o una cadena arbitraria si no utiliza ámbitos OAuth). Cuando haya terminado, haga clic en Autorizar API.
En las secciones Paso 2 y el Paso 3, vaya a través del flujo de OAuth 2.0 y verificar que cada paso funciona como se pretende.

Puede validar su aplicación mediante el uso de la cuenta de Google Vinculación demostración herramienta.

En la herramienta, siga los siguientes pasos:

Haga clic en el Inicio de sesión con el botón de Google.
Elija la cuenta que desea vincular.
Ingrese la identificación del servicio.
Opcionalmente, ingrese uno o más ámbitos para los que solicitará acceso.
Haga clic en Inicio de demostración.
Cuando se le solicite, confirme que puede dar su consentimiento y rechazar la solicitud de vinculación.
Confirme que se le redirige a su plataforma.