OAuth 2.0 y la biblioteca cliente de Google OAuth para Java

Descripción general

Propósito: En este documento, se describen las funciones genéricas de OAuth 2.0 que ofrece la biblioteca cliente de Google OAuth para Java. Puedes usar estas funciones para la autenticación y autorización de cualquier servicio de Internet.

Si deseas obtener instrucciones para usar GoogleCredential y realizar la autorización de OAuth 2.0 con los servicios de Google, consulta Cómo usar OAuth 2.0 con la biblioteca cliente de la API de Google para Java.

Resumen: OAuth 2.0 es una especificación estándar que permite a los usuarios finales autorizar de forma segura una aplicación cliente para que acceda a recursos protegidos del servidor. Además, en la especificación del token portador de OAuth 2.0, se explica cómo acceder a esos recursos protegidos con un token de acceso otorgado durante el proceso de autorización del usuario final.

Para obtener más información, consulta la documentación de Javadoc de los siguientes paquetes:

Registro de clientes

Antes de usar la biblioteca cliente de Google OAuth para Java, es probable que debas registrar tu aplicación con un servidor de autorización para recibir un ID de cliente y un secreto del cliente. (Para obtener información general sobre este proceso, consulta la especificación de registro de clientes).

Credenciales y tienda de credenciales

La credencial es una clase auxiliar de OAuth 2.0 con seguridad de subprocesos para acceder a recursos protegidos por medio de un token de acceso. Cuando se usa un token de actualización, Credential también actualiza el token de acceso cuando este vence mediante el token de actualización. Por ejemplo, si ya tienes un token de acceso, puedes realizar una solicitud de la siguiente manera:

  public static HttpResponse executeGet(
      HttpTransport transport, JsonFactory jsonFactory, String accessToken, GenericUrl url)
      throws IOException {
    Credential credential =
        new Credential(BearerToken.authorizationHeaderAccessMethod()).setAccessToken(accessToken);
    HttpRequestFactory requestFactory = transport.createRequestFactory(credential);
    return requestFactory.buildGetRequest(url).execute();
  }

La mayoría de las aplicaciones deben conservar el token de acceso y el token de actualización de la credencial para evitar un redireccionamiento futuro a la página de autorización en el navegador. La implementación de CredentialStore en esta biblioteca dejó de estar disponible y se quitará en versiones futuras. La alternativa es usar las interfaces DataStoreFactory y DataStore con StoredCredential, que proporciona la biblioteca cliente HTTP de Google para Java.

Puedes usar una de las siguientes implementaciones que proporciona la biblioteca:

Usuarios de Google App Engine:

AppEngineCredentialStore dejó de estar disponible y se quitará.

Te recomendamos que uses AppEngineDataStoreFactory con StoredCredential. Si tienes credenciales almacenadas de la forma anterior, puedes usar los métodos auxiliares agregados migrateTo(AppEngineDataStoreFactory) o migrateTo(DataStore) para realizar la migración.

Usa DataStoreCredentialRefreshListener y configúralo 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. El protocolo de este flujo se especifica en la especificación de otorgamiento de códigos de autorización.

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

Como alternativa, si no usas AuthorizationCodeFlow, puedes usar las clases de nivel inferior:

Flujo de código de autorización del servlet

Esta biblioteca proporciona clases auxiliares de servlet para simplificar significativamente el flujo de código de autorización para casos de uso 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 encargarte del acceso de usuario para tu aplicación web y extraer un ID de usuario.

Código de muestra:

public class ServletSample 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 AuthorizationCodeFlow.Builder(BearerToken.authorizationHeaderAccessMethod(),
        new NetHttpTransport(),
        new JacksonFactory(),
        new GenericUrl("https://server.example.com/token"),
        new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw"),
        "s6BhdRkqt3",
        "https://server.example.com/authorize").setCredentialDataStore(
            StoredCredential.getDefaultDataStore(
                new FileDataStoreFactory(new File("datastoredir"))))
        .build();
  }

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

public class ServletCallbackSample 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 AuthorizationCodeFlow.Builder(BearerToken.authorizationHeaderAccessMethod(),
        new NetHttpTransport(),
        new JacksonFactory(),
        new GenericUrl("https://server.example.com/token"),
        new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw"),
        "s6BhdRkqt3",
        "https://server.example.com/authorize").setCredentialDataStore(
            StoredCredential.getDefaultDataStore(
                new FileDataStoreFactory(new File("datastoredir"))))
        .build();
  }

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

Flujo de código de autorización 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 del servlet, con la excepción de que podemos aprovechar la API de usuarios para Java de Google App Engine. El usuario debe acceder para que se habilite la API de Users para Java. Si quieres obtener información sobre cómo redireccionar a los usuarios a una página de acceso si aún no accedieron, consulta Seguridad y autenticación (en web.xml).

La principal diferencia con el caso del servlet es que proporcionas subclases concretas de AbstractAppEngineAuthorizationCodeServlet y AbstractAppEngineAuthorizationCodeCallbackServlet (de google-oauth-client-appengine). Extienden las clases abstractas de servlet y, luego, implementan el método getUserId por ti con la API de usuarios de Java. AppEngineDataStoreFactory (de la biblioteca cliente HTTP de Google para Java) es una buena opción para conservar la credencial con la API de Google App Engine Data Store.

Código de muestra:

public class AppEngineSample extends AbstractAppEngineAuthorizationCodeServlet {

  @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 AuthorizationCodeFlow.Builder(BearerToken.authorizationHeaderAccessMethod(),
        new UrlFetchTransport(),
        new JacksonFactory(),
        new GenericUrl("https://server.example.com/token"),
        new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw"),
        "s6BhdRkqt3",
        "https://server.example.com/authorize").setCredentialStore(
            StoredCredential.getDefaultDataStore(AppEngineDataStoreFactory.getDefaultInstance()))
        .build();
  }
}

public class AppEngineCallbackSample extends AbstractAppEngineAuthorizationCodeCallbackServlet {

  @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 AuthorizationCodeFlow.Builder(BearerToken.authorizationHeaderAccessMethod(),
        new UrlFetchTransport(),
        new JacksonFactory(),
        new GenericUrl("https://server.example.com/token"),
        new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw"),
        "s6BhdRkqt3",
        "https://server.example.com/authorize").setCredentialStore(
            StoredCredential.getDefaultDataStore(AppEngineDataStoreFactory.getDefaultInstance()))
        .build();
  }
}

Flujo de código de autorización de la línea de comandos

Código de ejemplo simplificado tomado de dailymotion-cmdline-sample:

/** Authorizes the installed application to access user's protected data. */
private static Credential authorize() throws Exception {
  OAuth2ClientCredentials.errorIfNotSpecified();
  // set up authorization code flow
  AuthorizationCodeFlow flow = new AuthorizationCodeFlow.Builder(BearerToken
      .authorizationHeaderAccessMethod(),
      HTTP_TRANSPORT,
      JSON_FACTORY,
      new GenericUrl(TOKEN_SERVER_URL),
      new ClientParametersAuthentication(
          OAuth2ClientCredentials.API_KEY, OAuth2ClientCredentials.API_SECRET),
      OAuth2ClientCredentials.API_KEY,
      AUTHORIZATION_SERVER_URL).setScopes(Arrays.asList(SCOPE))
      .setDataStoreFactory(DATA_STORE_FACTORY).build();
  // authorize
  LocalServerReceiver receiver = new LocalServerReceiver.Builder().setHost(
      OAuth2ClientCredentials.DOMAIN).setPort(OAuth2ClientCredentials.PORT).build();
  return new AuthorizationCodeInstalledApp(flow, receiver).authorize("user");
}

private static void run(HttpRequestFactory requestFactory) throws IOException {
  DailyMotionUrl url = new DailyMotionUrl("https://api.dailymotion.com/videos/favorites");
  url.setFields("id,tags,title,url");

  HttpRequest request = requestFactory.buildGetRequest(url);
  VideoFeed videoFeed = request.execute().parseAs(VideoFeed.class);
  ...
}

public static void main(String[] args) {
  ...
  DATA_STORE_FACTORY = new FileDataStoreFactory(DATA_STORE_DIR);
  final Credential credential = authorize();
  HttpRequestFactory requestFactory =
      HTTP_TRANSPORT.createRequestFactory(new HttpRequestInitializer() {
        @Override
        public void initialize(HttpRequest request) throws IOException {
          credential.initialize(request);
          request.setParser(new JsonObjectParser(JSON_FACTORY));
        }
      });
  run(requestFactory);
  ...
}

Flujo de cliente basado en el navegador

Estos son los pasos típicos del flujo de cliente basado en el navegador que se especifica en la especificación de otorgamiento implícito:

  • Con BrowserClientRequestUrl, redirecciona el navegador del usuario final a la página de autorización en la que el usuario final puede otorgar a la aplicación acceso a sus datos protegidos.
  • Usa una aplicación de JavaScript para procesar el token de acceso que se encuentra en el fragmento de URL en el URI de redireccionamiento que está registrado en el servidor de autorización.

Ejemplo de uso para una aplicación web:

public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
  String url = new BrowserClientRequestUrl(
      "https://server.example.com/authorize", "s6BhdRkqt3").setState("xyz")
      .setRedirectUri("https://client.example.com/cb").build();
  response.sendRedirect(url);
}

Cómo detectar un token de acceso vencido

Según la especificación del portador de OAuth 2.0, cuando se llama al servidor para acceder a un recurso protegido con un token de acceso vencido, el servidor suele responder con un código de estado HTTP 401 Unauthorized como el siguiente:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Bearer realm="example",
                     error="invalid_token",
                     error_description="The access token expired"

Sin embargo, parece que hay mucha flexibilidad en la especificación. Para obtener más información, consulta la documentación del proveedor de OAuth 2.0.

Un enfoque alternativo es verificar el parámetro expires_in en la respuesta del token de acceso. Especifica la duración en segundos del token de acceso otorgado, que suele ser de una hora. Sin embargo, es posible que el token de acceso no caduque al final de ese período y que el servidor continúe permitiendo el acceso. Por eso, por lo general, recomendamos esperar un código de estado 401 Unauthorized, en lugar de suponer que el token venció en función del tiempo transcurrido. Como alternativa, puedes intentar actualizar un token de acceso poco antes de que venza y, si el servidor de tokens no está disponible, seguir usando el token de acceso hasta que recibas un 401. Esta es la estrategia que se usa de forma predeterminada en Credencial.

Otra opción es obtener un nuevo token de acceso antes de cada solicitud, pero eso requiere una solicitud HTTP adicional al servidor de tokens cada vez, por lo que es probable que sea una mala opción en términos de velocidad y uso de red. Lo ideal es almacenar el token de acceso en un almacenamiento seguro y persistente para minimizar las solicitudes de tokens de acceso nuevos de una aplicación. (Sin embargo, para las aplicaciones instaladas, el almacenamiento seguro es un problema difícil).

Ten en cuenta que un token de acceso puede dejar de ser válido por motivos distintos del vencimiento, por ejemplo, si el usuario revocó el token de forma explícita, por lo que debes asegurarte de que tu código de manejo de errores sea sólido. Una vez que hayas detectado que un token ya no es válido, por ejemplo, si venció o se revocó, debes quitar el token de acceso de tu almacenamiento. En Android, por ejemplo, debes llamar a AccountManager.invalidateAuthToken.