Guide pour ScribeJava

Guide de ScribeJava

1. introduction

Dans ce didacticiel, nous allons examiner la bibliothèqueScribeJava.

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 la prise en charge immédiate de toutes les principales API OAuth 1.0 et 2.0. De plus, si nous devons travailler avec une API non 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 quel client utiliser. En effet, ScribeJava supporte plusieurs clients HTTP:

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

2. Les dépendances

ScribeJava is organized into a core and APIs module, ce dernier comprend un ensemble d'API externes (Google, GitHub, Twitter, etc.) et l'artefact de base:


    com.github.scribejava
    scribejava-apis
    latest-version

Si nous n'avons besoin que de classes principales sans aucune API externe, nous devons extraire uniquement le module principal:


    com.github.scribejava
    scribejava-core
    latest-version

Les dernières versions peuvent être trouvées àMaven repository.

3. OAuthService

The main part of the library is the abstract class OAuthService qui contient tous les paramètres nécessaires pour gérer correctement la "prise de contact" de l'OAuth.

Selon la version du protocole, nous utiliserons les classes concrètesOauth10Service ouOauth20Service respectivement pourOAuth 1.0 etOAuth 2.0.

Afin de construire les implémentations deOAuthService, la bibliothèque fournit unServiceBuilder:

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

Nous devrions définir les jetonsapi_key etapi_secret fournis par le serveur d'autorisation.

De plus, nous pouvons définir lesscope de la requête et lescallback 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 leOAuthService en appelant la méthodebuild() 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 ScribeJavaGitHub.

3.1. Client HTTP

De plus,the library allows us to choose which HTTP Client to use:

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 àMaven repository.

3.2. Mode débogage

De plus,there’s a debug mode we can use to help us troubleshooting:

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

Nous devons simplement appeler la méthodedebug(). Le débogage affichera àSystem.out des informations pertinentes.

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

FileOutputStream debugFile = new FileOutputStream("debug");

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

4. Flux OAuth 1.0

Voyons maintenant comment gérer un flux OAuth1.

Dans cet exemple,we’re going to get an access token with the Twitter APIs and we’ll use it to make a request.

Tout d'abord, nous devons construire lesOauth10Service, 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 leOAuth10Service, we peut obtenir unrequestToken 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 versauthUrl et d'obtenir leoauthVerifier fourni par la page.

Par conséquent, nous utilisons leoauthVerifier t pour obtenir leaccessToken:

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

Enfin, nous pouvons créer une requête en utilisant l'objetOAuthRequest et y ajouter le jeton avec la méthodesignRequest():

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

Response response = service.execute(request);

A la suite de l'exécution de cerequest, nous obtenons un objetResponse.

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,we’re going to get an access token with Google APIs.

De la même manière, nous l'avons fait dans le flux OAuth 1.0, nous devons construire lesOAuthService et obtenir lesauthUrl, mais cette fois nous allons utiliser une instanceOAuth20Service:

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

String authUrl = service.getAuthorizationUrl();

Notez que, dans ce cas, nous devons fournir lesscope de la demande et lescallback auxquels nous serons contactés à la fin du flux d'autorisation.

De même, nous devons rediriger l'utilisateur versauthUrl et prendre le paramètrecode dans l'url du callback:

OAuth2AccessToken accessToken = service.getAccessToken(code);

OAuthRequest request = new OAuthRequest(Verb.GET, "https://www.googleapis.com/oauth2/v1/userinfo?alt=json");
service.signRequest(accessToken, request);

Response response = service.execute(request);

En fin de compte, pour faire lesrequest, nous obtenons la méthodeaccessToken withgetAccessToken().

6. API personnalisées

Nous devrons probablement travailler avec une API qui n'est pas prise en charge par ScribeJava. Dans ces circonstances,the library allows us to implement our own APIs.

La seule chose que nous devons faire est de fournir une implémentation deDefaultApi10 ouDefaultApi20 class.

Imaginons que nous ayons un serveur d’autorisation OAuth 2.0 avec octroi de mot de passe. Dans ce cas, nous pouvons implémenter lesDefaultApi20 pour pouvoir prendre unaccess token:

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 "http://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("example_api_key")
  .apiSecret("example_api_secret")
  .scope("read write")
  .build(MyApi.instance());

OAuth2AccessToken token = service.getAccessTokenPasswordGrant(username, password);

OAuthRequest request = new OAuthRequest(Verb.GET, "http://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 fournies par ScribeJava.

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 disponiblesover on GitHub.

TOC