Guide de ScribeJava

1. Introduction

Dans ce tutoriel, nous allons examiner la bibliothèque ScribeJava.

ScribeJava est un client OAuth simple pour Java qui permet de gérer le flux OAuth.

La principale caractéristique de la bibliothèque est qu'elle prend en charge toutes les principales API OAuth 1.0 et 2.0 prêtes à l'emploi. De plus, si nous devons travailler avec une API qui n'est pas prise en charge, la bibliothèque fournit quelques classes pour implémenter nos API OAuth.

Une autre caractéristique importante est qu'il est possible de choisir quelle utilisation client. En effet, ScribeJava prend en charge plusieurs clients HTTP:

  • Client Http Async
  • OkHttp
  • Apache HttpComponents HttpClient

De plus, la bibliothèque est compatible avec les threads et Java7, nous pouvons donc l'utiliser dans des environnements hérités.

2. Dépendances

ScribeJava est organisé en un module de base et d'API , ce dernier comprend un ensemble d'API externes (Google, GitHub, Twitter, etc.) et l'artefact de base:

 com.github.scribejava scribejava-apis latest-version 

Au cas où nous n'aurions besoin que de classes principales sans API externe, nous devons tirer uniquement le module principal:

 com.github.scribejava scribejava-core latest-version 

Les dernières versions peuvent être trouvées dans le référentiel Maven.

3. OAuthService

La partie principale de la bibliothèque est la classe abstraite OAuthService qui contient tous les paramètres nécessaires pour gérer correctement la «prise de contact» de OAuth.

Selon la version du protocole, nous utiliserons les classes concrètes Oauth10Service ou Oauth20Service respectivement pour OAuth 1.0 et OAuth 2.0.

Afin de construire les implémentations OAuthService , la bibliothèque fournit un ServiceBuilder:

OAuthService service = new ServiceBuilder("api_key") .apiSecret("api_secret") .scope("scope") .callback("callback") .build(GoogleApi20.instance());

Nous devrions définir les jetons api_key et api_secret fournis par le serveur d'autorisation.

De plus, nous pouvons définir la portée de la requête et le rappel vers lesquels le serveur d'autorisation doit rediriger l'utilisateur à la fin du flux d'autorisation.

Notez que selon la version du protocole, tous les paramètres ne sont pas obligatoires.

Enfin, nous devons construire le OAuthService en appelant la méthode build () et en lui passant une instance des API que nous voulons utiliser. Nous pouvons trouver une liste complète des API prises en charge sur ScribeJava GitHub.

3.1. Client HTTP

De plus, la bibliothèque nous permet de choisir quel client HTTP utiliser:

ServiceBuilder builder = new ServiceBuilder("api_key") .httpClient(new OkHttpHttpClient());

Après, bien sûr, nous avons inclus les dépendances requises, pour l'exemple précédent:

 com.github.scribejava scribejava-httpclient-okhttp latest-version 

Les dernières versions peuvent être trouvées dans le référentiel Maven.

3.2. Mode débogage

De plus, il existe un mode de débogage que nous pouvons utiliser pour nous aider à résoudre les problèmes:

ServiceBuilder builder = new ServiceBuilder("api_key") .debug();

Nous devons simplement appeler la méthode debug () . Debug affichera à System.out des informations pertinentes.

De plus, si nous voulons utiliser une sortie différente, il existe une autre méthode qui accepte un OutputStream pour envoyer les informations de débogage à:

FileOutputStream debugFile = new FileOutputStream("debug"); ServiceBuilder builder = new ServiceBuilder("api_key") .debug() .debugStream(debugFile);

4. OAuth 1.0 Flow

Concentrons-nous maintenant sur la façon de gérer un flux OAuth1.

Dans cet exemple, nous allons obtenir un jeton d'accès avec les API Twitter et nous l'utiliserons pour faire une demande.

Tout d'abord, nous devons construire le Oauth10Service , comme nous l'avons vu précédemment, en utilisant builder:

OAuth10aService service = new ServiceBuilder("api_key") .apiSecret("api_secret") .build(TwitterApi.instance());

Une fois que nous avons le OAuth10Service, nous pouvons obtenir un requestToken et l'utiliser pour obtenir l'URL d'autorisation:

OAuth1RequestToken requestToken = service.getRequestToken(); String authUrl = service.getAuthorizationUrl(requestToken);

À ce stade, il est nécessaire de rediriger l'utilisateur vers authUrl et d'obtenir le oauthVerifier fourni par la page.

Par conséquent, nous utilisons le oauthVerifier pour obtenir le accessToken :

OAuth1AccessToken accessToken = service.getAccessToken(requestToken,oauthVerifier);

Enfin, nous pouvons créer une requête à l'aide de l' objet OAuthRequest et y ajouter le jeton avec la méthode signRequest () :

OAuthRequest request = new OAuthRequest(Verb.GET, "//api.twitter.com/1.1/account/verify_credentials.json"); service.signRequest(accessToken, request); Response response = service.execute(request);

À la suite de l'exécution de cette demande , nous obtenons un objet Response .

5. Flux OAuth 2.0

Le flux OAuth 2.0 n'est pas très différent de OAuth 1.0. Afin d'expliquer ces variations, nous allons obtenir un jeton d'accès avec les API Google.

De la même manière que nous l'avons fait dans le flux OAuth 1.0, nous devons construire le OAuthService et obtenir l' authUrl , mais cette fois, nous utiliserons une instance OAuth20Service :

OAuth20Service service = new ServiceBuilder("api_key") .apiSecret("api_secret") .scope("//www.googleapis.com/auth/userinfo.email") .callback("//localhost:8080/auth") .build(GoogleApi20.instance()); String authUrl = service.getAuthorizationUrl();

Notez que, dans ce cas, nous devons fournir la portée de la demande et le rappel auquel nous serons contactés à la fin du flux d'autorisation.

De même, nous devons rediriger l'utilisateur vers authUrl et prendre le paramètre de code dans l'url du rappel:

OAuth2AccessToken accessToken = service.getAccessToken(code); OAuthRequest request = new OAuthRequest(Verb.GET, "//www.googleapis.com/oauth2/v1/userinfo?alt=json"); service.signRequest(accessToken, request); Response response = service.execute(request);

En fin de compte , afin de faire la demande , nous obtenons la accessToken avec getAccessToken () méthode.

6. API personnalisées

Nous devrons probablement travailler avec une API qui n'est pas prise en charge par ScribeJava. Dans ces circonstances, la bibliothèque nous permet de mettre en œuvre nos propres API .

La seule chose que nous devons faire est de fournir une implémentation de la classe DefaultApi10 ou DefaultApi20 .

Imaginons que nous ayons un serveur d'autorisation OAuth 2.0 avec octroi de mot de passe. Dans ce cas, nous pouvons implémenter le DefaultApi20 afin que nous puissions prendre un jeton d'accès :

public class MyApi extends DefaultApi20 { public MyApi() {} private static class InstanceHolder { private static final MyApi INSTANCE = new MyApi(); } public static MyApi instance() { return InstanceHolder.INSTANCE; } @Override public String getAccessTokenEndpoint() { return "//localhost:8080/oauth/token"; } @Override protected String getAuthorizationBaseUrl() { return null; } }

Ainsi, nous pouvons obtenir un jeton d'accès de la même manière que précédemment:

OAuth20Service service = new ServiceBuilder("baeldung_api_key") .apiSecret("baeldung_api_secret") .scope("read write") .build(MyApi.instance()); OAuth2AccessToken token = service.getAccessTokenPasswordGrant(username, password); OAuthRequest request = new OAuthRequest(Verb.GET, "//localhost:8080/me"); service.signRequest(token, request); Response response = service.execute(request);

7. Conclusion

Dans cet article, nous avons examiné les classes les plus utiles que ScribeJava fournit dans le commerce.

Nous avons appris à gérer les flux OAuth 1.0 et OAuth 2.0 avec des API externes. Nous avons également appris à configurer la bibliothèque afin d'utiliser nos propres API.

Comme d'habitude, tous les exemples de code présentés dans ce didacticiel sont disponibles à l'adresse over sur GitHub.