Ce document explique comment implémenter un gestionnaire de rappel d'autorisation OAuth 2.0 à l'aide de servlets Java via un exemple d'application Web qui affichera les tâches de l'utilisateur à l'aide de l'API Google Tasks. L'exemple d'application commence par demander l'autorisation d'accéder aux tâches Google de l'utilisateur, puis affiche les tâches de l'utilisateur dans la liste de tâches par défaut.
Audience
Ce document s'adresse aux personnes qui connaissent déjà les architectures d'applications Web Java et J2EE. Il est recommandé de connaître le flux d'autorisation OAuth 2.0.
Sommaire
Pour obtenir un échantillon entièrement fonctionnel, vous devez suivre plusieurs étapes:
- Déclarer des mappages de servlets dans le fichier web.xml
- Authentifier les utilisateurs sur votre système et leur demander l'autorisation d'accéder à ses tâches
- Écouter le code d'autorisation depuis le point de terminaison d'autorisation Google
- Échanger le code d'autorisation contre un jeton d'actualisation et un jeton d'accès
- Lire les tâches de l'utilisateur et les afficher
Déclarer les mappages de servlets dans le fichier web.xml
Nous allons utiliser deux servlets dans notre application:
- PrintTasksTitlesServlet (mappé sur /): point d'entrée de l'application qui gérera l'authentification de l'utilisateur et affichera les tâches de l'utilisateur.
- OAuthCodeCallbackHandlerServlet (mappé sur /oauth2callback): rappel OAuth 2.0 qui gère la réponse du point de terminaison d'autorisation OAuth
Vous trouverez ci-dessous le fichier web.xml qui mappe ces deux servlets aux URL de notre application:
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<servlet>
<servlet-name>PrintTasksTitles</servlet-name>
<servlet-class>com.google.oauthsample.PrintTasksTitlesServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>PrintTasksTitles</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
<servlet>
<servlet-name>OAuthCodeCallbackHandlerServlet</servlet-name>
<servlet-class>com.google.oauthsample.OAuthCodeCallbackHandlerServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>OAuthCodeCallbackHandlerServlet</servlet-name>
<url-pattern>/oauth2callback</url-pattern>
</servlet-mapping>
</web-app>
Fichier /WEB-INF/web.xml
Authentifier les utilisateurs sur votre système et leur demander l'autorisation d'accéder à ses tâches
L'utilisateur entre dans l'application via la racine "/" URL mappée sur le servlet PrintTaskListsTitlesServlet. Dans ce servlet, les tâches suivantes sont effectuées:
- Vérifie si l'utilisateur est authentifié sur le système
- Si l'utilisateur n'est pas authentifié, il est redirigé vers la page d'authentification.
- Si l'utilisateur est authentifié, nous vérifions si nous disposons déjà d'un jeton d'actualisation dans notre espace de stockage de données. Ce jeton est géré par le jeton OAuthTokenDao ci-dessous. Si aucun jeton d'actualisation n'est disponible pour l'utilisateur, cela signifie que celui-ci n'a pas encore autorisé l'application à accéder à ses tâches. Dans ce cas, l'utilisateur est redirigé vers le point de terminaison d'autorisation OAuth 2.0 de Google.
package com.google.oauthsample;
import ...
/**
* Simple sample Servlet which will display the tasks in the default task list of the user.
*/
@SuppressWarnings("serial")
public class PrintTasksTitlesServlet extends HttpServlet {
/**
* The OAuth Token DAO implementation, used to persist the OAuth refresh token.
* Consider injecting it instead of using a static initialization. Also we are
* using a simple memory implementation as a mock. Change the implementation to
* using your database system.
*/
public static OAuthTokenDao oauthTokenDao = new OAuthTokenDaoMemoryImpl();
public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
// Getting the current user
// This is using App Engine's User Service but you should replace this to
// your own user/login implementation
UserService userService = UserServiceFactory.getUserService();
User user = userService.getCurrentUser();
// If the user is not logged-in it is redirected to the login service, then back to this page
if (user == null) {
resp.sendRedirect(userService.createLoginURL(getFullRequestUrl(req)));
return;
}
// Checking if we already have tokens for this user in store
AccessTokenResponse accessTokenResponse = oauthTokenDao.getKeys(user.getEmail());
// If we don't have tokens for this user
if (accessTokenResponse == null) {
OAuthProperties oauthProperties = new OAuthProperties();
// Redirect to the Google OAuth 2.0 authorization endpoint
resp.sendRedirect(new GoogleAuthorizationRequestUrl(oauthProperties.getClientId(),
OAuthCodeCallbackHandlerServlet.getOAuthCodeCallbackHandlerUrl(req), oauthProperties
.getScopesAsString()).build());
return;
}
}
/**
* Construct the request's URL without the parameter part.
*
* @param req the HttpRequest object
* @return The constructed request's URL
*/
public static String getFullRequestUrl(HttpServletRequest req) {
String scheme = req.getScheme() + "://";
String serverName = req.getServerName();
String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort();
String contextPath = req.getContextPath();
String servletPath = req.getServletPath();
String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo();
String queryString = (req.getQueryString() == null) ? "" : "?" + req.getQueryString();
return scheme + serverName + serverPort + contextPath + servletPath + pathInfo + queryString;
}
}
Fichier PrintTasksTitlesservlet.java
Remarque: L'implémentation ci-dessus utilise certaines bibliothèques App Engine qui sont utilisées par souci de simplification. Si vous développez votre application pour une autre plate-forme, n'hésitez pas à réimplémenter l'interface UserService qui gère l'authentification des utilisateurs.
L'application utilise un DAO pour persister et accéder aux jetons d'autorisation de l'utilisateur. L'interface OAuthTokenDao et une implémentation fictive (en mémoire) OAuthTokenDaoMemoryImpl sont utilisées dans cet exemple:
package com.google.oauthsample;
import com.google.api.client.auth.oauth2.draft10.AccessTokenResponse;
/**
* Allows easy storage and access of authorization tokens.
*/
public interface OAuthTokenDao {
/**
* Stores the given AccessTokenResponse using the {@code username}, the OAuth
* {@code clientID} and the tokens scopes as keys.
*
* @param tokens The AccessTokenResponse to store
* @param userName The userName associated wit the token
*/
public void saveKeys(AccessTokenResponse tokens, String userName);
/**
* Returns the AccessTokenResponse stored for the given username, clientId and
* scopes. Returns {@code null} if there is no AccessTokenResponse for this
* user and scopes.
*
* @param userName The username of which to get the stored AccessTokenResponse
* @return The AccessTokenResponse of the given username
*/
public AccessTokenResponse getKeys(String userName);
}
Fichier OAuthTokenDao.java
package com.google.oauthsample;
import com.google.api.client.auth.oauth2.draft10.AccessTokenResponse;
...
/**
* Quick and Dirty memory implementation of {@link OAuthTokenDao} based on
* HashMaps.
*/
public class OAuthTokenDaoMemoryImpl implements OAuthTokenDao {
/** Object where all the Tokens will be stored */
private static Map tokenPersistance = new HashMap();
public void saveKeys(AccessTokenResponse tokens, String userName) {
tokenPersistance.put(userName, tokens);
}
public AccessTokenResponse getKeys(String userName) {
return tokenPersistance.get(userName);
}
}
Fichier OAuthTokenDaoMemoryImpl.java
De plus, les identifiants OAuth 2.0 de l'application sont stockés dans un fichier de propriétés. Vous pouvez aussi les avoir simplement comme constantes dans l'une de vos classes Java, même si vous voyez ici la classe OAuthProperties et le fichier oauth.properties utilisés dans l'exemple:
package com.google.oauthsample;
import ...
/**
* Object representation of an OAuth properties file.
*/
public class OAuthProperties {
public static final String DEFAULT_OAUTH_PROPERTIES_FILE_NAME = "oauth.properties";
/** The OAuth 2.0 Client ID */
private String clientId;
/** The OAuth 2.0 Client Secret */
private String clientSecret;
/** The Google APIs scopes to access */
private String scopes;
/**
* Instantiates a new OauthProperties object reading its values from the
* {@code OAUTH_PROPERTIES_FILE_NAME} properties file.
*
* @throws IOException IF there is an issue reading the {@code propertiesFile}
* @throws OauthPropertiesFormatException If the given {@code propertiesFile}
* is not of the right format (does not contains the keys {@code
* clientId}, {@code clientSecret} and {@code scopes})
*/
public OAuthProperties() throws IOException {
this(OAuthProperties.class.getResourceAsStream(DEFAULT_OAUTH_PROPERTIES_FILE_NAME));
}
/**
* Instantiates a new OauthProperties object reading its values from the given
* properties file.
*
* @param propertiesFile the InputStream to read an OAuth Properties file. The
* file should contain the keys {@code clientId}, {@code
* clientSecret} and {@code scopes}
* @throws IOException IF there is an issue reading the {@code propertiesFile}
* @throws OAuthPropertiesFormatException If the given {@code propertiesFile}
* is not of the right format (does not contains the keys {@code
* clientId}, {@code clientSecret} and {@code scopes})
*/
public OAuthProperties(InputStream propertiesFile) throws IOException {
Properties oauthProperties = new Properties();
oauthProperties.load(propertiesFile);
clientId = oauthProperties.getProperty("clientId");
clientSecret = oauthProperties.getProperty("clientSecret");
scopes = oauthProperties.getProperty("scopes");
if ((clientId == null) || (clientSecret == null) || (scopes == null)) {
throw new OAuthPropertiesFormatException();
}
}
/**
* @return the clientId
*/
public String getClientId() {
return clientId;
}
/**
* @return the clientSecret
*/
public String getClientSecret() {
return clientSecret;
}
/**
* @return the scopes
*/
public String getScopesAsString() {
return scopes;
}
/**
* Thrown when the OAuth properties file was not at the right format, i.e not
* having the right properties names.
*/
@SuppressWarnings("serial")
public class OAuthPropertiesFormatException extends RuntimeException {
}
}
Fichier OAuthProperties.java
Vous trouverez ci-dessous le fichier oauth.properties qui contient les identifiants OAuth 2.0 de votre application. Vous devez modifier vous-même les valeurs ci-dessous.
# Client ID and secret. They can be found in the APIs console. clientId=1234567890.apps.googleusercontent.com clientSecret=aBcDeFgHiJkLmNoPqRsTuVwXyZ # API scopes. Space separated. scopes=https://www.googleapis.com/auth/tasks
Fichier oauth.properties
L'ID client OAuth 2.0 et le code secret du client identifient votre application et permettent à l'API Tasks d'appliquer les filtres et les règles de quota définis pour votre application. Vous trouverez l'ID client et le code secret dans la console d'API Google. Une fois dans la console, procédez comme suit:
- Créez ou sélectionnez un projet.
- Activez l'API Tasks en définissant son état sur ON dans la liste des services.
- Sous Accès à l'API, créez un ID client OAuth 2.0, le cas échéant.
- Assurez-vous que l'URL du gestionnaire de rappel du code OAuth 2.0 du projet est enregistrée/ajoutée à la liste blanche dans les URI de redirection. Dans cet exemple de projet, vous devrez enregistrer https://www.example.com/oauth2callback si votre application Web est diffusée depuis le domaine https://www.example.com.
URI de redirection dans la console des API
Écouter le code d'autorisation à partir du point de terminaison d'autorisation Google
Si l'utilisateur n'a pas encore autorisé l'application à accéder à ses tâches et qu'il a donc été redirigé vers le point de terminaison d'autorisation OAuth 2.0 de Google, une boîte de dialogue d'autorisation s'affiche pour lui demander d'autoriser votre application à accéder à ses tâches:
Boîte de dialogue d'autorisation de Google
Après avoir accordé ou refusé l'accès, l'utilisateur est redirigé vers le gestionnaire de rappel du code OAuth 2.0 qui a été spécifié en tant que redirection/rappel lors de la création de l'URL d'autorisation Google:
new GoogleAuthorizationRequestUrl(oauthProperties.getClientId(),
OAuthCodeCallbackHandlerServlet.getOAuthCodeCallbackHandlerUrl(req), oauthProperties
.getScopesAsString()).build()
Le gestionnaire de rappel de code OAuth 2.0 (OAuthCodeCallbackHandlerServlet) gère la redirection à partir du point de terminaison Google OAuth 2.0. Il y a deux cas à gérer:
- L'utilisateur a accordé l'accès: analyse la requête pour obtenir le code OAuth 2.0 à partir des paramètres d'URL.
- L'utilisateur a refusé l'accès: affiche un message à l'attention de l'utilisateur
package com.google.oauthsample;
import ...
/**
* Servlet handling the OAuth callback from the authentication service. We are
* retrieving the OAuth code, then exchanging it for a refresh and an access
* token and saving it.
*/
@SuppressWarnings("serial")
public class OAuthCodeCallbackHandlerServlet extends HttpServlet {
/** The name of the Oauth code URL parameter */
public static final String CODE_URL_PARAM_NAME = "code";
/** The name of the OAuth error URL parameter */
public static final String ERROR_URL_PARAM_NAME = "error";
/** The URL suffix of the servlet */
public static final String URL_MAPPING = "/oauth2callback";
public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
// Getting the "error" URL parameter
String[] error = req.getParameterValues(ERROR_URL_PARAM_NAME);
// Checking if there was an error such as the user denied access
if (error != null && error.length > 0) {
resp.sendError(HttpServletResponse.SC_NOT_ACCEPTABLE, "There was an error: \""+error[0]+"\".");
return;
}
// Getting the "code" URL parameter
String[] code = req.getParameterValues(CODE_URL_PARAM_NAME);
// Checking conditions on the "code" URL parameter
if (code == null || code.length == 0) {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "The \"code\" URL parameter is missing");
return;
}
}
/**
* Construct the OAuth code callback handler URL.
*
* @param req the HttpRequest object
* @return The constructed request's URL
*/
public static String getOAuthCodeCallbackHandlerUrl(HttpServletRequest req) {
String scheme = req.getScheme() + "://";
String serverName = req.getServerName();
String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort();
String contextPath = req.getContextPath();
String servletPath = URL_MAPPING;
String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo();
return scheme + serverName + serverPort + contextPath + servletPath + pathInfo;
}
}
Fichier OAuthCodeCallbackHandlerCallback.java
Échanger le code d'autorisation contre un jeton d'actualisation et un jeton d'accès
Ensuite, OAuthCodeCallbackHandlerServlet échange le code Auth 2.0 contre une mise à jour et des jetons d'accès, le conserve dans le datastore et redirige l'utilisateur vers l'URL OAuthCodeCallbackHandlerServlet:
La syntaxe du code ajouté au fichier ci-dessous est mise en surbrillance, et le code existant est grisé.
package com.google.oauthsample; import ... /** * Servlet handling the OAuth callback from the authentication service. We are * retrieving the OAuth code, then exchanging it for a refresh and an access * token and saving it. */ @SuppressWarnings("serial") public class OAuthCodeCallbackHandlerServlet extends HttpServlet { /** The name of the Oauth code URL parameter */ public static final String CODE_URL_PARAM_NAME = "code"; /** The name of the OAuth error URL parameter */ public static final String ERROR_URL_PARAM_NAME = "error"; /** The URL suffix of the servlet */ public static final String URL_MAPPING = "/oauth2callback";/** URL vers laquelle rediriger l'utilisateur après avoir traité le rappel. Envisagez d'utiliser * L'enregistrement de ces informations dans un cookie avant de les rediriger vers le * URL d'autorisation si vous disposez de plusieurs URL vers lesquelles rediriger les utilisateurs. */ public statique final String REDIRECT_URL = "/"; /** Implémentation DAO du jeton OAuth. Envisagez de l’injecter au lieu de l’utiliser * Une initialisation statique. Nous utilisons aussi une simple implémentation de mémoire * à titre de simulation. Modifiez l'implémentation pour utiliser votre système de base de données. */ public statique OAuthTokenDao oauthTokenDao = new OAuthTokenDaoMemoryImpl();public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { // Getting the "error" URL parameter String[] error = req.getParameterValues(ERROR_URL_PARAM_NAME); // Checking if there was an error such as the user denied access if (error != null && error.length > 0) { resp.sendError(HttpServletResponse.SC_NOT_ACCEPTABLE, "There was an error: \""+error[0]+"\"."); return; } // Getting the "code" URL parameter String[] code = req.getParameterValues(CODE_URL_PARAM_NAME); // Checking conditions on the "code" URL parameter if (code == null || code.length == 0) { resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "The \"code\" URL parameter is missing"); return; }// Construire l'URL de la requête entrante String requestUrl = getOAuthCodeCallbackHandlerUrl(req); // Échanger le code contre des jetons OAuth AccessTokenResponse accessTokenResponse = ExchangeCodeForAccessAndRefreshTokens(code[0], requestUrl); // Obtenir l'utilisateur actuel // Vous utilisez le service User d'App Engine, mais vous devez le remplacer par // votre propre mise en œuvre des utilisateurs/connexions UserService userService = UserServiceFactory.getUserService() String email = userService.getCurrentUser().getEmail() // Enregistrer les jetons oauthTokenDao.saveKeys(accessTokenResponse, email); resp.sendRedirect(REDIRECT_URL); }/** * Construct the OAuth code callback handler URL. * * @param req the HttpRequest object * @return The constructed request's URL */ public static String getOAuthCodeCallbackHandlerUrl(HttpServletRequest req) { String scheme = req.getScheme() + "://"; String serverName = req.getServerName(); String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort(); String contextPath = req.getContextPath(); String servletPath = URL_MAPPING; String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo(); return scheme + serverName + serverPort + contextPath + servletPath + pathInfo; }/** * Échange le code donné contre un échange et un jeton d'actualisation. *. * @param code Le code obtenu par le service d'autorisation * @param currentUrl : URL du rappel. * @param oauthProperties Objet contenant la configuration OAuth * @return Objet contenant à la fois un jeton d'accès et un jeton d'actualisation * @déclenche une exception IOException */ public AccessTokenResponse ExchangeCodeForAccessAndRefreshTokens(String code, String currentUrl) throws IOException { HttpTransport httpTransport = new NetHttpTransport(); JacksonFactory jsonFactory = new JacksonFactory() // Chargement du fichier de configuration OAuth OAuthProperties oauthProperties = new OAuthProperties|| renvoyer new GoogleAuthorizationCodeGrant(httpTransport, jsonFactory, oauthProperties .getClientId(), oauthProperties.getClientSecret(), code, currentUrl).execute() } }Fichier OAuthCodeCallbackHandlerCallback.javaRemarque: L'implémentation ci-dessus utilise certaines bibliothèques App Engine qui sont utilisées par souci de simplification. Si vous développez votre application pour une autre plate-forme, n'hésitez pas à réimplémenter l'interface UserService qui gère l'authentification des utilisateurs.
Lire les tâches de l'utilisateur et les afficher
L'utilisateur a autorisé l'application à accéder à ses tâches. L'application dispose d'un jeton d'actualisation enregistré dans le datastore accessible via OAuthTokenDao. Le servlet PrintTaskListsTitlesServlet peut désormais utiliser ces jetons pour accéder aux tâches de l'utilisateur et les afficher:
La syntaxe du code ajouté au fichier ci-dessous est mise en surbrillance, et le code existant est grisé.
package com.google.oauthsample; import ... /** * Simple sample Servlet which will display the tasks in the default task list of the user. */ @SuppressWarnings("serial") public class PrintTasksTitlesServlet extends HttpServlet { /** * The OAuth Token DAO implementation, used to persist the OAuth refresh token. * Consider injecting it instead of using a static initialization. Also we are * using a simple memory implementation as a mock. Change the implementation to * using your database system. */ public static OAuthTokenDao oauthTokenDao = new OAuthTokenDaoMemoryImpl(); public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { // Getting the current user // This is using App Engine's User Service but you should replace this to // your own user/login implementation UserService userService = UserServiceFactory.getUserService(); User user = userService.getCurrentUser(); // If the user is not logged-in it is redirected to the login service, then back to this page if (user == null) { resp.sendRedirect(userService.createLoginURL(getFullRequestUrl(req))); return; } // Checking if we already have tokens for this user in store AccessTokenResponse accessTokenResponse = oauthTokenDao.getKeys(user.getEmail()); // If we don't have tokens for this user if (accessTokenResponse == null) { OAuthProperties oauthProperties = new OAuthProperties(); // Redirect to the Google OAuth 2.0 authorization endpoint resp.sendRedirect(new GoogleAuthorizationRequestUrl(oauthProperties.getClientId(), OAuthCodeCallbackHandlerServlet.getOAuthCodeCallbackHandlerUrl(req), oauthProperties .getScopesAsString()).build()); return; }// Imprimer les titres des listes de tâches de l'utilisateur dans la réponse resp.setContentType("text/plain"); resp.getWriter().append("Titres des listes de tâches pour l'utilisateur " + user.getEmail() + ":\n\n") printTasksTitles(accessTokenResponse, resp.getWriter(||)} /** * Construct the request's URL without the parameter part. * * @param req the HttpRequest object * @return The constructed request's URL */ public static String getFullRequestUrl(HttpServletRequest req) { String scheme = req.getScheme() + "://"; String serverName = req.getServerName(); String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort(); String contextPath = req.getContextPath(); String servletPath = req.getServletPath(); String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo(); String queryString = (req.getQueryString() == null) ? "" : "?" + req.getQueryString(); return scheme + serverName + serverPort + contextPath + servletPath + pathInfo + queryString; }/** * Utilise l'API Google Tasks pour récupérer la liste des tâches des utilisateurs dans * liste de tâches. *. * @param accessTokenResponse Objet AccessTokenResponse OAuth 2.0 * contenant le jeton d'accès et un jeton d'actualisation. * @param génère le rédacteur de flux de sortie pour exécuter la liste des tâches en tant que titres. * @return Une liste des titres des tâches des utilisateurs dans la liste de tâches par défaut. * @déclenche une exception IOException */ public void printTasksTitles(AccessTokenResponse accessTokenResponse, Writer output) throws IOException { // Initialiser le service Tasks HttpTransport transport = new NetHttpTransport(); JsonFactory jsonFactory = new JacksonFactory() OAuthProperties oauthProperties = new OAuthProperties|| GoogleAccessProtectedResource accessProtectedResource = new GoogleAccessProtectedResource( accessTokenResponse.accessToken, transport, jsonFactory, oauthProperties.getClientId(), oauthProperties.getClientSecret(), accessTokenResponse.refreshToken); Service Tasks = new Tasks(transport, accessProtectedResource, jsonFactory); // Utiliser le service de l'API Tasks initialisé pour interroger la liste des listes de tâches com.google.api.services.tasks.model.Tasks tasks = service.tasks.list("@default").execute(); for (Task task : tasks.items) { output.append(task.title + "\n />") } } }Fichier PrintTasksTitlesservlet.javaLa liste des tâches de l'utilisateur s'affiche:
Les tâches de l'utilisateurExemple d'application
Le code de cet exemple d'application peut être téléchargé ici. N'hésitez pas à la consulter.