Google APIs: cómo utilizar OAuth 2.0 para acceder

[Fuente: https://developers.google.com/accounts/docs/OAuth2?hl=es#scenarios]

Las APIs de Google utilizan el OAuth 2.0 protocol para autenticación y autorización. Goolgle dispone de varios flujos OAuth 2.0 que cubren todos los escenarios típicos, véase : web server , Javascript , dispositivo , aplicación instalada y servidor – servidor.

OAuth 2.0 es un protocolo relativamente simple y un programador puede integrar con Google’s OAuth 2.0 endpoints sin demasiado esfuerzo. Como pincelada introductoria, hay que registrar la aplicación con Google , redirigir el navegador a una URL , parsear el token de la respuesta , y enviar el token al servicio de Google API que desees.

Este artículo es una introducción a los escenarios OAuth 2.0 que Google soporta y proporciona enlaces a contenidos con más información.

Dadas las implicaciones de seguridad de acceder a la implementación correcta , recomendamos encarecidamente a los programadores utilizar las librerías OAuth 2.0 cuando interaccionan con Google’s OAuth 2.0 endpoints (ver Client libraries pars más info). Proximamente , más características serán añadidas a estas librerías.

Contents

  1. Basic Steps
  2. Simple Example
  3. Scenarios
    1. Login
    2. Web Server Applications
    3. Client-side Applications
    4. Installed Applications
    5. Devices
    6. Service Accounts
  4. Client Libraries

Pasos Básicos

Las aplicaciones siguen el mismo patrón básico cuando acceden a cualquier API de Google utilizando OAuth 2.0. A alto nivel, siempre se dan los siguientes 4 pasos:

1. Registrar la aplicación

Todas las aplicaciones que accedan al Google API deben estar registradas a través de la APIs Console.El resultado de este proceso de registro es un conjunto de valores que son conocidos tanto por Google como por tu aplicación (es decir , el client-id , el client-secret , los Javascript origins , la redirect-uri, etc). Por ejemplo: una aplicación Javascript no requiere un secret, pero una aplicación en servidor web sí.

2. Obtener el Token de acceso desde un Google Authorization Server

Antes de que tu aplicación pueda acceder a Google API , debe obtener un token de acceso que garantice el acceso al API. Un solo token de acceso puede autorizarte varios grados de acceso a multiples APIs. El conjunto de recursos y poeraciones permitidos por un token de acceso se controla durante la petición del token de acceso via una variable parámetro llamada ‘scope‘. Varios scopes pueden ser solicitados en una petición.

Hay varias formas de hacer una petición, y varia en función del tipo de aplicación que se está desarrollando. Por ejemplo: una aplicación Javascript puede solicitar un token de acceso utilizando un browser redirect a Google , mientras que una aplicación instalada en un dispositivo que no tiene browser utiliza peticiones web service.

La petición requiere que el usuario se logue en Google. Después de logarse , el usuario verá el permiso solicitado por la aplicación y será preguntado si quiere autorizar esos permisos a esa aplicación. Este proceso se llama “consentimiento del usuario“.

Si el usuario autoriza esos permisos a tu aplicación , a tu aplicación le será enviado un token de acceso o un código de autorización (el cual es utilizado para obtener un token de acceso). Si el usuario no autoriza permisos a tu aplicación , el Google Authorization Server retorna un error.

3. Enviar el Token de Acceso a un API

Después de que una aplicación ha obtenido el token de acceso, puede enviar el token de acceso en una petición a cualquier API de Google. Los tokens de acceso son válidos sólo para un conjunto de operaciones y recursos descritos en la petición del token. Por ejemplo:if an access token is issued for the Google+ API, it will not grant access to the Google Contacts API. It may, however, be sent to the Google+ API multiple times for similar operations.

Los tokens de acceso son enviados al API de Google en la HTTP Authorization header,o como un parámetro de la querystring (if HTTP header operations are not available).

4. Refresca el Token de Acceso  (opcional)

Los tokens de acceso tiene un tiempo de vida limitado, en algunos casos, una aplicación necesita acceso al Google API más allá del tiempo de un solo token de acceso. Cuando éste es el caso, tu aplicación puede obtener lo que se llama un token de refresco. Un token de refresco te permite obtener nuevos token de acceso.

Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.

Ejemplo simple

A continuación un ejemplo trivial de cómo utilizar Google’s OAuth 2.0 endpoint para obtener acceso al API de Google. It’s a Python web application running on App Engine. The flow of the example is fairly straightforward:

  1. Cuando la aplicación se carga , muestra al usuario el enlace “Login”
  2. Cuando el usuario hace click en Login, le será solicitado el login en Google y le pedirá que dé autorización de información básica  de la cuenta a la aplicación (consentimiento del usuario)
  3. Si el usuario concede los permisos, la aplicación recibe un token de acceso
  4. Una vez que tiene el token de acceso, la aplicación presenta el token de acceo al Google API que proporciona la información básica de la cuenta.(https://www.googleapis.com/oauth2/v1/userinfo)
  5. La aplicación renderiza le información básica de la cuenta en una tabla simple

Try it out for yourself!

Scenarios

Login

El login de usuario es siempre una parte esencial para acceder a la mayoría de las apis de Google. Tu aplicación puede utilizar el sistema de autenticación de Google para delegar la autenticación y obtención del perfil a Google.

La secuencia de login comienza redireccionando el navegador (popup , o página web normal si es necesario) a una url de Google con un conjunto de parámetros en la query string. Será Google el que se encargue de seleccionar la sesión correcta (el usuario puede haberse logado previamente con múltiples identidades) , aceptar y validar las credenciales del usuario y el one-time-password (si la cuenta lo requiere) , obteniendo consentimiento para proporcionar información básica del perfil, así como retornar un token de acceso OAuth 2.0 a tu aplicación.

El resultado de la secuencia de autenticación del usuario es un token de acceso OAuth 2.0, con el que ya puedes obtener información del perfil del usuario invocando al UserInfo Google API.

La información retornada del servicio de UserInfo puede ser utilizada durante el registro del usuario lo que minimiza los datos que el usuario tiene que introducir en el registro.

Además está el beneficio añadido de que tu site no tiene que mantener usuarios / contraseña en un almacenamiento seguro.

Para más información Login documentation.

Web Server Applications

Los servidores de Autorización OAuth2.0 de Google soportan aplicaciones web de servidor (es decir PHP , Java , Python , Ruby, ASP.NET,etc) . Esta secuencia comienza redireccionando el navegador (popup , o página completa si es necesario) a un url de Google con un conjunto de parámetros en la query string que indican el API y el tipo de acceso que nuestra aplicación solicita. Como en otros escenarios, Google se encarga de autenticar al usuario, selección de la sesiones que tenga ya guardadas el usuario y del consentimiento, pero el resultado de la secuencia en este caso es un “authorization code”. Después de recibir el código de autorización , la aplicación puede intercambiar el código por un código de acceso y un refresh token.

La aplicación puede acceder al Google API después de que se reciba el token de acceso.

Para más información -> Web Server documentation.

Client-side Applications

The Google OAuth 2.0 Authorization Server supports JavaScript applications (JavaScript running in a browser). Like the other scenarios, this one begins by redirecting a browser (popup, or full-page if needed) to a Google URL with a set of query string parameters that indicate the type of Google API access the application requires. Google handles the user authentication, session selection, and user consent. The result is an access token. The client should then validate the token. After validation, the client includes the access token in a Google API request.

For more information, see the Client-side documentation.

Installed Application

The Google OAuth 2.0 Authorization Server supports desktop and mobile applications (e.g. Android, Windows, Mac OS, iOS, Blackberry, etc.). These applications, in general, cannot keep secrets.

The sequence for installed applications is similar to the one shown in the Web Server section, but there are three exceptions:

  1. When registering the application, you specify that the application is an Installed application. This results in a different value for the redirect_uri parameter.
  2. The client_id and client_secret obtained during registration are embedded in the source code of your application. In this context, the client_secret is obviously not treated as a secret.
  3. The authorization code is returned to your application differently.

This sequence begins by redirecting a browser (either a browser embedded in the application or the system browser) to a Google URL with a set of query parameters that indicate the type of Google API access the application requires. Like other scenarios, Google handles the user authentication, session selection, and user consent. The result of the sequence is an authorization code. Your application can choose to have the authorization code returned in the title of the web page or to a http://localhost port. Once the application receives the authorization code, it can exchange the code for an access token and a refresh token.

After the application has received the access and refresh tokens, it may store the refresh token for future use, and use the access token to access a Google API. Once the access token expires, the application obtains a new one with the refresh token.

For more information, see the Installed Application documentation.

Devices

The Google OAuth 2.0 Authorization Server supports applications that run on devices with limited input capabilities (e.g. game consoles, video cameras, printers). In these cases, the user must have separate access to a computer or device with richer input capabilities. The user will first interact with application on the limited device, obtain an URL and a code from the device, then switch to a device or computer with richer input capabilities and launch a browser. Once in a browser, the user will navigate to the URL specified on the device, authenticate, and enter the code.

The sequence begins with the application making a request to a Google URL for a new code. The response contains several parameters, including the URL and code that should be shown to the user. The application should present these values to the user, and begin polling a Google URL at a specified interval. The response to a message in this polling sequence indicates whether or not the user has approved access. After the user approves access (via another computer or device), the response contains an access and refresh token.

After the application has received the access and refresh tokens, it may store the refresh token for future use, and use the access token to access a Google API. Once the access token expires, the application obtains a new one with the refresh token.

For more information, see the Device documentation.

Cuentas de Servicio (Service Accounts)

Varios APIs de Google actuan desde el lado de una aplicación y no acceden a información del usuario. Ejemplos de estos APIs son por ejemplo el API de Predicciones y el Google Cloud Storage.Cuando una aplicación accede a Google Cloud Storage, la aplicación necesita probar su propia identidad antes de realizar operaciones en la nube así que necesita obtener la aprobación del usuario.

Hay también una opción para que una aplicación pueda solicitar acceso delegado a un recurso en entornos de enterprise. El Google’s OAuth 2.0 Authorization Server soporta estos tipos de aplicaciones, y esta sección describe cómo una aplicación puede probar su identidad antes de acceso a un Google API compatible.

El mecanismo de esta interacción requiere que las aplicaciones se creen de forma criptográfica unos JSON Web Tokens (JWTs). Se recomienda también en este caso a los programadores que para esto utilicen un librería. Escribir este código sin el uso de una librería que abstraiga la creación de token y el firmado es muy dado a errores que pueden tener un impacto severo en la seguridad de tus aplicaciones. Para una lista librerias que soportan  este flujo , ver  OAuth 2.0 Service Accounts documentation

Esta secuencia comienza con la creación de una Service Account. Puedes crear una en la Google APIs console, o si estás utilizando Google App Engine, se crea una automáticamente cuando arrancas la aplicación GAE. Durante la creación de la Service Account en la Google APIs Console se te preguntará para descargarte una private key. Estate seguro de guardar esta private key en un lugar seguro. After the Service Account has been created, you will also have access to the client ID associated with the private key. You will need both when coding your application.

After obtaining the client ID and private key from the Google APIs Console, create a JWT and sign it with the private key, and construct an access token request in the appropriate format. Your application then sends the token request to the Google OAuth 2.0 Authorization Server and an access token will be returned. The application can access the API only after receiving the access token. When the access token expires, the application repeats the process.

For more information, see the Service Account documentation.

Client libraries

The following client libraries make implementing OAuth 2.0 even simpler by integrating with popular frameworks: