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:
- com.google.api.client.googleapis.auth.oauth2 (desde google-api-client)
- com.google.api.client.googleapis.extensions.appengine.auth.oauth2 (de google-api-client-appengine)
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:
- AppEngineDataStoreFactory: Conserva la credencial mediante la API de almacén de datos de Google App Engine.
- MemoryDataStoreFactory: "Conserva" la credencial en la memoria, lo que solo es útil como almacenamiento a corto plazo durante la vida útil del proceso.
- FileDataStoreFactory: Conserva la credencial en un archivo.
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:
- El usuario final accede a tu aplicación. Deberás asociar ese usuario con un ID de usuario que sea único para tu aplicación.
- Llama a AuthorizationCodeFlow.loadCredential(String)) según el ID del usuario para verificar si ya se conocen las credenciales del usuario final. Si es así, terminamos.
- Si no es así, llama a AuthorizationCodeFlow.newAuthorizationUrl() y dirige el navegador del usuario final a una página de autorización para otorgar a tu aplicación acceso a los datos protegidos.
- El servidor de autorización de Google redireccionará el navegador de nuevo a la URL de redireccionamiento especificada por tu aplicación, junto con un parámetro de consulta
code
. Usa el parámetrocode
para solicitar un token de acceso con AuthorizationCodeFlow.newTokenRequest(String)). - Usa AuthorizationCodeFlow.createAndStoreCredential(TokenResponse, String)) a fin de almacenar y obtener una credencial para acceder a los recursos protegidos.
Como alternativa, si no estás usando GoogleAuthorizationCodeFlow, puedes usar las clases de nivel inferior:
- Usa DataStore.get(String) para cargar la credencial desde la tienda según el ID de usuario.
- Usa GoogleAuthorizationCodeRequestUrl para dirigir el navegador a la página de autorización.
- Usa AuthorizationCodeResponseUrl para procesar la respuesta de autorización y analizar el código de autorización.
- Utiliza GoogleAuthorizationCodeTokenRequest para solicitar un token de acceso y, posiblemente, un token de actualización.
- Crea una GoogleCredential nueva y almacénala con DataStore.set(String, V).
- Accede a los recursos protegidos con
GoogleCredential
. Los tokens de acceso vencidos se actualizarán automáticamente con el token de actualización (si corresponde). Asegúrate de usar DataStoreCredentialRefreshListener y configurarlo para la credencial con GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener).
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:
- 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.
- 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
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; } }