OAuth 2.0 para apps de escritorio y dispositivos móviles

En este documento, se explica cómo se instalan las aplicaciones en dispositivos como teléfonos, tablets y computadoras usan extremos de OAuth 2.0 de Google para autorizar el acceso a APIs de Google.

OAuth 2.0 permite a los usuarios compartir datos específicos con una aplicación y, al mismo tiempo, mantiene nombres de usuario, contraseñas y otra información privada. Por ejemplo, una aplicación puede usar OAuth 2.0 para obtener permiso de que los usuarios almacenen archivos en sus unidades de Google Drive.

Las apps instaladas se distribuyen a los dispositivos individuales y se supone que estas apps no puede guardar secretos. Pueden acceder a las APIs de Google mientras el usuario está presente en la app o cuando La app se ejecuta en segundo plano.

Este flujo de autorización es similar al que se usa para aplicaciones de servidor web. La principal diferencia es que las aplicaciones instaladas deben abrir el navegador del sistema y suministrar un URI de redireccionamiento local para procesar del servidor de autorización de Google.

Alternativas

En el caso de las apps para dispositivos móviles, es posible que prefieras usar Acceso con Google para Android o iOS. El Acceso con Google las bibliotecas cliente manejan la autenticación y la autorización de usuarios, y pueden ser más fáciles de que el protocolo de nivel inferior descrito aquí.

Para apps que se ejecutan en dispositivos que no son compatibles con un navegador del sistema o que tienen entradas limitadas. como TVs, consolas de juegos, cámaras o impresoras, consulta OAuth 2.0 para TVs y Dispositivos o acceso en TVs y dispositivos de entrada limitados.

Bibliotecas y muestras

Recomendamos las siguientes bibliotecas y ejemplos para implementar el flujo de OAuth 2.0 que se describe en este documento:

• Biblioteca de AppAuth para Android
• Biblioteca de AppAuth para iOS
• OAuth para aplicaciones: Windows Ejemplos

Requisitos previos

Habilita las API para tu proyecto.

Cualquier aplicación que llame a las APIs de Google debe habilitarlas en el API Console

Para habilitar una API en tu proyecto, haz lo siguiente:

1. Open the API Library en Google API Console
2. If prompted, select a project, or create a new one.
3. El elemento API Library enumera todas las APIs disponibles, agrupadas por producto familia y popularidad. Si la API que quieres habilitar no está en la lista, usa la búsqueda para la encontrarás o haz clic en Ver todo en la familia de productos a la que pertenece.
4. Selecciona la API que deseas habilitar y, luego, haz clic en el botón Habilitar.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Crea credenciales de autorización

Cualquier aplicación que utilice OAuth 2.0 para acceder a las APIs de Google debe tener credenciales de autorización que identifican la aplicación en el servidor OAuth 2.0 de Google. Los siguientes pasos explican cómo crear credenciales para tu proyecto. Así, tus aplicaciones pueden usar las credenciales para acceder a las APIs que hayas habilitado para ese proyecto.

1. Go to the Credentials page.
2. Haz clic en Crear credenciales > ID de cliente de OAuth.
3. En las siguientes secciones se describen los tipos de clientes y los métodos de redireccionamiento que utiliza Google de autorización de Google. Elige el tipo de cliente recomendado para tu aplicación, asignar un nombre a tu cliente de OAuth y establecer los demás campos del formulario como lo que sea apropiado.

Identifica los permisos de acceso

Los permisos permiten que tu aplicación solo solicite acceso a los recursos que necesita, al tiempo que que les permite a los usuarios controlar el nivel de acceso que otorgan a tu aplicación. Por lo tanto, hay puede ser una relación inversa entre el número de alcances solicitados y la probabilidad de obtener el consentimiento del usuario.

Antes de que comiences a implementar la autorización de OAuth 2.0, te recomendamos que identifiques los alcances. a las que tu app necesitará permiso para acceder.

El documento Alcances de la API de OAuth 2.0 contiene una lista completa de permisos que puedes usar para acceder a las APIs de Google.

Obtén tokens de acceso de OAuth 2.0

Los siguientes pasos muestran cómo interactúa tu aplicación con el servidor OAuth 2.0 de Google para obtener el consentimiento de un usuario para realizar una solicitud a la API en nombre del usuario. Tu aplicación debe tener para poder ejecutar una solicitud a la API de Google que requiera la autorización del usuario.

Paso 1: Genera un verificador de código y un desafío

Google admite la clave de prueba para el intercambio de código (PKCE) para que el flujo de la app instalada sea más seguro. Se crea un verificador de código único para cada solicitud de autorización, y su valor transformado, llamado “code_challenge”, se envía al de autorización para obtener el código de autorización.

Crea el verificador de código

Un code_verifier es una cadena criptográfica aleatoria de alta entropía que usa el parámetro caracteres [A-Z] / [a-z] / [0-9] / "-" / "." /"_" / "~", con una longitud mínima de 43 caracteres y una longitud máxima de 128 caracteres.

El verificador de código debe tener suficiente entropía para que no sea práctico adivinar el valor.

Crea el desafío de código

Se admiten dos métodos para crear el desafío de código.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Paso 2: Envía una solicitud al servidor OAuth 2.0 de Google

Para obtener la autorización del usuario, envía una solicitud al servidor de autorización de Google a través de la página https://accounts.google.com/o/oauth2/v2/auth Este extremo controla la búsqueda de sesión activa, autentica al usuario y obtiene su consentimiento. Solo se puede acceder al extremo a través de SSL, y rechaza las conexiones HTTP (no SSL).

El servidor de autorización admite los siguientes parámetros de cadena de consulta para aplicaciones instaladas aplicaciones:

Ejemplos de URLs de autorización

Las pestañas a continuación muestran ejemplos de URLs de autorización para las diferentes opciones de URI de redireccionamiento.

Las URLs son idénticas, excepto por el valor del parámetro redirect_uri. Las URLs También contienen los parámetros obligatorios response_type y client_id. como el parámetro opcional state. Cada URL contiene saltos de línea y espacios para la legibilidad.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Paso 3: Google solicita el consentimiento del usuario

En este paso, el usuario decide si otorgará a tu aplicación el acceso solicitado. En este Google muestra una ventana de consentimiento con el nombre de tu aplicación y la API de Google. servicios a los que solicita permiso para acceder con las credenciales de autorización del usuario y un resumen de los permisos de acceso que se otorgarán. El el usuario puede dar su consentimiento para otorgar acceso a uno o más alcances solicitados por tu aplicación o rechazar la solicitud.

Tu aplicación no necesita hacer nada en esta etapa mientras espera la respuesta del Servidor OAuth 2.0 de Google que indica si se otorgó algún acceso Esa respuesta se explica en el siguiente paso.

Paso 4: Controla la respuesta del servidor de OAuth 2.0

La forma en que tu aplicación recibe la respuesta de autorización depende del esquema de URI de redireccionamiento que usa. Independientemente del esquema, contendrá un código de autorización (code) o un error (error). Por ejemplo, error=access_denied indica que el usuario rechazó la solicitud.

Si el usuario otorga acceso a tu aplicación, puedes intercambiar el código de autorización por un token de acceso y un token de actualización, como se describe en el paso siguiente.

Paso 5: Intercambia el código de autorización para actualizar y acceder tokens

Para intercambiar un código de autorización por un token de acceso, llama al https://oauth2.googleapis.com/token y establece los siguientes parámetros:

En el siguiente fragmento, se muestra una solicitud de muestra:

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Para responder a esta solicitud, Google muestra un objeto JSON que contiene un acceso de corta duración y uno de actualización.

La respuesta contiene los siguientes campos:

En el siguiente fragmento, se muestra una respuesta de muestra:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Llama a las APIs de Google

Luego de que la aplicación obtenga un token de acceso, puedes usarlo para realizar llamadas a un servicio en nombre de un proveedor de servicios de usuario si se otorgaron los permisos de acceso que requiere la API. Para ello, incluye el token de acceso en una solicitud a la API mediante una consulta access_token o un valor de encabezado HTTP Bearer Authorization. Cuando sea posible, se prefiere el encabezado HTTP, ya que las cadenas de consulta tienden a ser visibles en los registros del servidor. En la mayoría puedes usar una biblioteca cliente para configurar las llamadas a las APIs de Google (por ejemplo, cuando llamar a la API de Drive Files).

Puedes probar todas las APIs de Google y ver sus alcances en la OAuth 2.0 Playground.

Ejemplos de solicitudes GET de HTTP

Un llamado a la drive.files extremo (la API de Drive Files) con el HTTP Authorization: Bearer el encabezado podría verse de la siguiente manera. Ten en cuenta que debes especificar tu propio token de acceso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Esta es una llamada a la misma API para el usuario autenticado con access_token. Parámetro de cadena de consulta:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Ejemplos de curl

Puedes probar estos comandos con la aplicación de línea de comandos de curl. Este es un ejemplo que usa la opción de encabezado HTTP (preferida):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Como alternativa, la opción de parámetro de cadena de consulta:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Actualización de un token de acceso

Los tokens de acceso caducan periódicamente y se convierten en credenciales no válidas para una solicitud a la API relacionada. Tú puede actualizar un token de acceso sin pedirle permiso al usuario (incluso cuando (inexistente) si solicitaste acceso sin conexión a los permisos asociados con el token.

Para actualizar un token de acceso, tu aplicación envía un POST HTTPS solicitud al servidor de autorización de Google (https://oauth2.googleapis.com/token) que incluye los siguientes parámetros:

En el siguiente fragmento, se muestra una solicitud de muestra:

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Siempre que el usuario no haya revocado el acceso otorgado a la aplicación, el servidor de tokens devuelve un objeto JSON que contiene un token de acceso nuevo. En el siguiente fragmento, se muestra un ejemplo respuesta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Ten en cuenta que existen límites en la cantidad de tokens de actualización que se emitirán. un límite por una combinación de cliente y usuario y otra por usuario en todos los clientes. Debes guardar los tokens de actualización. en un almacenamiento a largo plazo y seguir usándolos mientras sean válidos. Si tu aplicación solicita demasiados tokens de actualización, se pueden alcanzar estos límites, en cuyo caso los tokens de actualización más antiguos dejará de funcionar.

Revoca un token

En algunos casos, es posible que el usuario desee revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso en Configuración de la cuenta. Consulta la Quitar Acceso al sitio o la aplicación de la sección de Sitios de terceros y apps con acceso a tu cuenta para obtener más información.

También es posible que una aplicación revoque de forma programática el acceso que se le otorgó. La revocación programática es importante en los casos en que un usuario anula la suscripción, quita aplicación o los recursos de API necesarios para una aplicación han cambiado considerablemente. En otras palabras, parte del proceso de eliminación pueden incluir una solicitud a la API para garantizar que los permisos anteriores otorgadas a la aplicación.

Para revocar un token de manera programática, la aplicación realiza una solicitud a https://oauth2.googleapis.com/revoke e incluye el token como parámetro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

El token puede ser de acceso o de actualización. Si el token es de acceso y tiene un token de actualización correspondiente, también se revocará el token de actualización.

Si la revocación se procesa correctamente, el código de estado HTTP de la respuesta es 200 Para las condiciones de error, se muestra el código de estado HTTP 400 junto con un código de error.

Lecturas adicionales

La práctica actual recomendada de IETF para OAuth 2.0 Las apps nativas establecen muchas de las prácticas recomendadas que se documentan aquí.