Usa OAuth 2.0 con la biblioteca cliente de las APIs de Google para Java

Descripción general

Propósito: En este documento, se explica cómo usar la clase de utilidad GoogleCredential para autorizar a OAuth 2.0 con los servicios de Google. Para obtener información sobre las funciones genéricas de OAuth 2.0 que proporcionamos, consulta OAuth 2.0 y la biblioteca cliente de Google OAuth para Java.

Resumen: Si quieres acceder a los datos protegidos almacenados en los servicios de Google, usa OAuth 2.0 para la autorización. Las APIs de Google admiten flujos de OAuth 2.0 para diferentes tipos de aplicaciones cliente. En todos estos flujos, la aplicación cliente solicita un token de acceso que está asociado solo con tu aplicación cliente y con el propietario de los datos protegidos a los que se accede. El token de acceso también está asociado con un alcance limitado que define el tipo de datos a los que tiene acceso tu aplicación cliente (por ejemplo, "Administra tus tareas"). Un objetivo importante de OAuth 2.0 es proporcionar un acceso seguro y conveniente a los datos protegidos, a la vez que se minimiza el impacto potencial si se roba un token de acceso.

Los paquetes de OAuth 2.0 de la biblioteca cliente de la API de Google para Java se basan en la Biblioteca cliente de Google OAuth 2.0 para Java de uso general.

Para obtener información detallada, consulta la documentación de Javadoc para los siguientes paquetes:

Consola de API de Google

Antes de acceder a las API de Google, debes configurar un proyecto en la Consola de API de Google para fines de autenticación y facturación, ya sea que tu cliente sea una aplicación instalada, una aplicación para dispositivos móviles, un servidor web o un cliente que se ejecute en el navegador.

Para obtener instrucciones sobre cómo configurar tus credenciales correctamente, consulta la Ayuda de la Consola de API.

Credencial

GoogleCredential

GoogleCredential es una clase de ayuda segura para subprocesos de OAuth 2.0 que permite acceder a recursos protegidos mediante un token de acceso. Por ejemplo, si ya tienes un token de acceso, puedes realizar una solicitud de la siguiente manera:

GoogleCredential credential = new GoogleCredential().setAccessToken(accessToken);
Plus plus = new Plus.builder(new NetHttpTransport(),
                             GsonFactory.getDefaultInstance(),
                             credential)
    .setApplicationName("Google-PlusSample/1.0")
    .build();

Identidad de Google App Engine

Esta credencial alternativa se basa en la API de Java de App Identity de Google App Engine. A diferencia de la credencial en la que una aplicación cliente solicita acceso a los datos de un usuario final, la API de App Identity proporciona acceso a los propios datos de la aplicación cliente.

Usa AppIdentityCredential (de google-api-client-appengine). Esta credencial es mucho más simple porque Google App Engine se encarga de todos los detalles. Solo especificas el permiso de OAuth 2.0 que necesitas.

Ejemplo de código tomado de urlshortener-robots-appengine-sample:

static Urlshortener newUrlshortener() {
  AppIdentityCredential credential =
      new AppIdentityCredential(
          Collections.singletonList(UrlshortenerScopes.URLSHORTENER));
  return new Urlshortener.Builder(new UrlFetchTransport(),
                                  GsonFactory.getDefaultInstance(),
                                  credential)
      .build();
}

Almacén de datos

Por lo general, los tokens de acceso tienen una fecha de vencimiento de 1 hora. Después de esa fecha, se mostrará un error si intentas usarlos. GoogleCredential se encarga de "actualizar" automáticamente el token, lo que simplemente significa obtener un token de acceso nuevo. Esto se hace mediante un token de actualización de larga duración, que se suele recibir junto con el token de acceso si usas el parámetro access_type=offline durante el flujo de código de autorización (consulta GoogleAuthorizationCodeFlow.Builder.setAccessType(String)).

La mayoría de las aplicaciones necesitarán conservar el token de acceso de la credencial o el de actualización. Para conservar el acceso de la credencial o los tokens de actualización, puedes proporcionar tu propia implementación de DataStoreFactory con StoredCredential, o puedes usar una de las siguientes implementaciones que proporciona la biblioteca:

Usuarios de AppEngine: AppEngineCredentialStore está obsoleta y se quitará pronto. Te recomendamos que uses AppEngineDataStoreFactory con StoredCredential. Si tienes credenciales almacenadas en el modo anterior, puedes usar los métodos auxiliares agregados migrationTo(AppEngineDataStoreFactory) o MigrateTo(DataStore) para realizar la migración.

Puedes usar DataStoreCredentialRefreshListener y configurarlo para la credencial con GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener).

Flujo de código de autorización

Usa el flujo de código de autorización para permitir que el usuario final otorgue a tu aplicación acceso a sus datos protegidos en las APIs de Google. El protocolo para este flujo se especifica en Otorgamiento de código de autorización.

Este flujo se implementa con GoogleAuthorizationCodeFlow. Estos son los pasos:

Como alternativa, si no estás usando GoogleAuthorizationCodeFlow, puedes usar las clases de nivel inferior:

Cuando configures tu proyecto en la Consola de API de Google, deberás seleccionar entre diferentes credenciales, según el flujo que utilices. Para obtener más detalles, consulta Cómo configurar OAuth 2.0 y Situaciones de OAuth 2.0. A continuación, se muestran fragmentos de código para cada uno de los flujos.

Aplicaciones de servidor web

El protocolo para este flujo se explica en Usa OAuth 2.0 para aplicaciones de servidor web.

Esta biblioteca proporciona clases auxiliares de servlet para simplificar significativamente el flujo de código de autorización en casos prácticos básicos. Solo debes proporcionar subclases concretas de AbstractAuthorizationCodeServlet y AbstractAuthorizationCodeCallbackServlet (de google-oauth-client-servlet) y agregarlas a tu archivo web.xml. Ten en cuenta que aún debes administrar el acceso del usuario a tu aplicación web y extraer un ID del usuario.

public class CalendarServletSample extends AbstractAuthorizationCodeServlet {

  @Override
  protected void doGet(HttpServletRequest request, HttpServletResponse response)
      throws IOException {
    // do stuff
  }

  @Override
  protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException {
    GenericUrl url = new GenericUrl(req.getRequestURL().toString());
    url.setRawPath("/oauth2callback");
    return url.build();
  }

  @Override
  protected AuthorizationCodeFlow initializeFlow() throws IOException {
    return new GoogleAuthorizationCodeFlow.Builder(
        new NetHttpTransport(), GsonFactory.getDefaultInstance(),
        "[[ENTER YOUR CLIENT ID]]", "[[ENTER YOUR CLIENT SECRET]]",
        Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory(
        DATA_STORE_FACTORY).setAccessType("offline").build();
  }

  @Override
  protected String getUserId(HttpServletRequest req) throws ServletException, IOException {
    // return user ID
  }
}

public class CalendarServletCallbackSample extends AbstractAuthorizationCodeCallbackServlet {

  @Override
  protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential)
      throws ServletException, IOException {
    resp.sendRedirect("/");
  }

  @Override
  protected void onError(
      HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse)
      throws ServletException, IOException {
    // handle error
  }

  @Override
  protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException {
    GenericUrl url = new GenericUrl(req.getRequestURL().toString());
    url.setRawPath("/oauth2callback");
    return url.build();
  }

  @Override
  protected AuthorizationCodeFlow initializeFlow() throws IOException {
    return new GoogleAuthorizationCodeFlow.Builder(
        new NetHttpTransport(), GsonFactory.getDefaultInstance()
        "[[ENTER YOUR CLIENT ID]]", "[[ENTER YOUR CLIENT SECRET]]",
        Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory(
        DATA_STORE_FACTORY).setAccessType("offline").build();
  }

  @Override
  protected String getUserId(HttpServletRequest req) throws ServletException, IOException {
    // return user ID
  }
}

Aplicaciones de Google App Engine

El flujo de código de autorización en App Engine es casi idéntico al flujo de código de autorización de servlet, excepto que podemos aprovechar la API de usuarios de Java de Google App Engine. El usuario debe haber accedido para que se habilite la API de Java de usuarios. Si quieres obtener información sobre cómo redireccionar a los usuarios a una página de acceso si aún no lo hicieron, consulta Seguridad y autenticación (en web.xml).

La diferencia principal con respecto al caso del servlet es que proporcionas subclases concretas de AbstractAppEngineAuthorizationCodeServlet y AbstractAppEngineAuthorizationCodeCallbackServlet (de google-oauth-client-appengine. Extienden las clases abstractas de servlet y, además, implementan el método getUserId por ti mediante la API de Java de usuarios. AppEngineDataStoreFactory (de google-http-client-appengine) es una buena opción para conservar la credencial con la API de almacén de datos de Google App Engine.

Ejemplo tomado (ligeramente modificado) de calendar-appengine-sample:

public class CalendarAppEngineSample extends AbstractAppEngineAuthorizationCodeServlet {

  @Override
  protected void doGet(HttpServletRequest request, HttpServletResponse response)
      throws IOException {
    // do stuff
  }

  @Override
  protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException {
    return Utils.getRedirectUri(req);
  }

  @Override
  protected AuthorizationCodeFlow initializeFlow() throws IOException {
    return Utils.newFlow();
  }
}

class Utils {
  static String getRedirectUri(HttpServletRequest req) {
    GenericUrl url = new GenericUrl(req.getRequestURL().toString());
    url.setRawPath("/oauth2callback");
    return url.build();
  }

  static GoogleAuthorizationCodeFlow newFlow() throws IOException {
    return new GoogleAuthorizationCodeFlow.Builder(HTTP_TRANSPORT, JSON_FACTORY,
        getClientCredential(), Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory(
        DATA_STORE_FACTORY).setAccessType("offline").build();
  }
}

public class OAuth2Callback extends AbstractAppEngineAuthorizationCodeCallbackServlet {

  private static final long serialVersionUID = 1L;

  @Override
  protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential)
      throws ServletException, IOException {
    resp.sendRedirect("/");
  }

  @Override
  protected void onError(
      HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse)
      throws ServletException, IOException {
    String nickname = UserServiceFactory.getUserService().getCurrentUser().getNickname();
    resp.getWriter().print("<h3>" + nickname + ", why don't you want to play with me?</h1>");
    resp.setStatus(200);
    resp.addHeader("Content-Type", "text/html");
  }

  @Override
  protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException {
    return Utils.getRedirectUri(req);
  }

  @Override
  protected AuthorizationCodeFlow initializeFlow() throws IOException {
    return Utils.newFlow();
  }
}

Para obtener una muestra adicional, consulta storage-serviceaccount-appengine-sample.

Cuentas de servicio

GoogleCredential también admite cuentas de servicio. A diferencia de la credencial en la que una aplicación cliente solicita acceso a los datos de un usuario final, las cuentas de servicio proporcionan acceso a los propios datos de la aplicación cliente. La aplicación cliente firma la solicitud de un token de acceso con una clave privada descargada desde la Consola de API de Google.

Ejemplo de código tomado de plus-serviceaccount-cmdline-sample:

HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
...
// Build service account credential.

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(PlusScopes.PLUS_ME));
// Set up global Plus instance.
plus = new Plus.Builder(httpTransport, jsonFactory, credential)
    .setApplicationName(APPLICATION_NAME).build();
...

Para obtener una muestra adicional, consulta storage-serviceaccount-cmdline-sample.

Robo de identidad

También puedes usar el flujo de la cuenta de servicio para actuar en nombre de un usuario en un dominio que te pertenezca. Esto es muy similar al flujo de la cuenta de servicio anterior, pero además llamas a GoogleCredential.Builder.setServiceAccountUser(String).

Aplicaciones instaladas

Este es el flujo de código de autorización de la línea de comandos que se describe en Cómo usar OAuth 2.0 para aplicaciones instaladas.

Fragmento de ejemplo de plus-cmdline-sample:

public static void main(String[] args) {
  try {
    httpTransport = GoogleNetHttpTransport.newTrustedTransport();
    dataStoreFactory = new FileDataStoreFactory(DATA_STORE_DIR);
    // authorization
    Credential credential = authorize();
    // set up global Plus instance
    plus = new Plus.Builder(httpTransport, JSON_FACTORY, credential).setApplicationName(
        APPLICATION_NAME).build();
   // ...
}

private static Credential authorize() throws Exception {
  // load client secrets
  GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(JSON_FACTORY,
      new InputStreamReader(PlusSample.class.getResourceAsStream("/client_secrets.json")));
  // set up authorization code flow
  GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder(
      httpTransport, JSON_FACTORY, clientSecrets,
      Collections.singleton(PlusScopes.PLUS_ME)).setDataStoreFactory(
      dataStoreFactory).build();
  // authorize
  return new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user");
}

Aplicaciones del cliente

Para usar el flujo de cliente basado en el navegador descrito en Usa OAuth 2.0 para aplicaciones del cliente, por lo general, debes seguir estos pasos:

  1. Redirecciona al usuario final en el navegador a la página de autorización con GoogleBrowserClientRequestUrl para otorgar a tu aplicación de navegador acceso a los datos protegidos del usuario final.
  2. Usa la biblioteca cliente de la API de Google para JavaScript a fin de procesar el token de acceso que se encuentra en el fragmento de la URL en el URI de redireccionamiento registrado en la Consola de API de Google.

Ejemplo de uso para una aplicación web:

public void doGet(HttpServletRequest request, HttpServletResponse response)throws IOException {
  String url = new GoogleBrowserClientRequestUrl("812741506391.apps.googleusercontent.com",
      "https://oauth2.example.com/oauthcallback", Arrays.asList(
          "https://www.googleapis.com/auth/userinfo.email",
          "https://www.googleapis.com/auth/userinfo.profile")).setState("/profile").build();
  response.sendRedirect(url);
}

Android

@Beta

Qué biblioteca usar con Android:

Si estás desarrollando para Android y la API de Google que quieres usar se incluye en la biblioteca de Servicios de Google Play, úsala para obtener el mejor rendimiento y una mejor experiencia. Si la API de Google que quieres usar con Android no forma parte de la biblioteca de Servicios de Google Play, puedes usar la biblioteca cliente de las APIs de Google para Java, que admite Android 4.0 (Ice Cream Sandwich) (o versiones posteriores) y que se describe aquí. La compatibilidad con Android en la biblioteca cliente de la API de Google para Java es @Beta.

Información general:

A partir de Eclair (SDK 2.1), las cuentas de usuario se administran en un dispositivo Android mediante el administrador de cuentas. El SDK administra de forma centralizada todas las autorizaciones de aplicaciones para Android con AccountManager. Especificas el alcance de OAuth 2.0 que necesita tu aplicación y se mostrará un token de acceso para usar.

El alcance de OAuth 2.0 se especifica a través del parámetro authTokenType como oauth2: más el alcance. Por ejemplo:

oauth2:https://www.googleapis.com/auth/tasks

Esto especifica el acceso de lectura/escritura a la API de Google Tasks. Si necesitas varios alcances de OAuth 2.0, usa una lista separada por espacios.

Algunas APIs tienen parámetros authTokenType especiales que también funcionan. Por ejemplo, "Administra tus tareas" es un alias para el ejemplo de authtokenType que se muestra arriba.

También debes especificar la clave de API en la Consola de API de Google. De lo contrario, el token que te proporciona AccountManager solo te proporciona una cuota anónima, que suele ser muy baja. En cambio, si especificas una clave de API, obtendrás una cuota gratuita más alta y, de manera opcional, podrás configurar la facturación para un uso superior.

Ejemplo de fragmento de código tomado de tasks-android-sample:

com.google.api.services.tasks.Tasks service;

@Override
public void onCreate(Bundle savedInstanceState) {
  credential =
      GoogleAccountCredential.usingOAuth2(this, Collections.singleton(TasksScopes.TASKS));
  SharedPreferences settings = getPreferences(Context.MODE_PRIVATE);
  credential.setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null));
  service =
      new com.google.api.services.tasks.Tasks.Builder(httpTransport, jsonFactory, credential)
          .setApplicationName("Google-TasksAndroidSample/1.0").build();
}

private void chooseAccount() {
  startActivityForResult(credential.newChooseAccountIntent(), REQUEST_ACCOUNT_PICKER);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  switch (requestCode) {
    case REQUEST_GOOGLE_PLAY_SERVICES:
      if (resultCode == Activity.RESULT_OK) {
        haveGooglePlayServices();
      } else {
        checkGooglePlayServicesAvailable();
      }
      break;
    case REQUEST_AUTHORIZATION:
      if (resultCode == Activity.RESULT_OK) {
        AsyncLoadTasks.run(this);
      } else {
        chooseAccount();
      }
      break;
    case REQUEST_ACCOUNT_PICKER:
      if (resultCode == Activity.RESULT_OK && data != null && data.getExtras() != null) {
        String accountName = data.getExtras().getString(AccountManager.KEY_ACCOUNT_NAME);
        if (accountName != null) {
          credential.setSelectedAccountName(accountName);
          SharedPreferences settings = getPreferences(Context.MODE_PRIVATE);
          SharedPreferences.Editor editor = settings.edit();
          editor.putString(PREF_ACCOUNT_NAME, accountName);
          editor.commit();
          AsyncLoadTasks.run(this);
        }
      }
      break;
  }
}