TOC

Руководство по ScribeJava

Руководство по ScribeJava

1. Вступление

В этом руководстве мы рассмотрим библиотекуScribeJava.

ScribeJava - это простой клиент OAuth для Java, который помогает управлять потоком OAuth.

Главной особенностью библиотеки является то, что она поддерживает все основные API OAuth 1.0 и 2.0 "из коробки". Более того, если нам придется работать с API, который не поддерживается, библиотека предоставляет несколько классов для реализации наших API OAuth.

Еще одной важной особенностью является то, что можно выбрать, какой клиент использовать. Действительно, ScribeJava поддерживает несколько HTTP-клиентов:

Кроме того, библиотека является поточно-ориентированной и Java7-совместимой, поэтому мы можем использовать ее в устаревших средах.

2. зависимости

ScribeJava is organized into a core and APIs module, последний включает набор внешнего API (Google, GitHub, Twitter и т. д.) и основной артефакт: 


    com.github.scribejava
    scribejava-apis
    latest-version

В случае, если нам нужны только базовые классы без какого-либо внешнего API, мы должны извлечь только основной модуль: 


    com.github.scribejava
    scribejava-core
    latest-version

Последние версии можно найти наMaven repository.

3. OAuthServiceс

The main part of the library is the abstract class OAuthService, который содержит все параметры, необходимые для правильного управления «рукопожатием» OAuth.

В зависимости от версии протокола мы будем использовать конкретные классыOauth10Service илиOauth20Service соответственно дляOAuth 1.0 иOAuth 2.0.

Для создания реализацийOAuthService библиотека предоставляетServiceBuilder: 

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

Мы должны установить токеныapi_key иapi_secret, предоставленные сервером авторизации.

Кроме того, мы можем установитьscope запроса иcallback, на которые сервер авторизации должен перенаправить пользователя в конце потока авторизации.

Обратите внимание, что в зависимости от версии протокола не все параметры являются обязательными.

Наконец, мы должны создатьOAuthService, вызывающий методbuild() и передав ему экземпляр API, который мы хотим использовать. Мы можем найти полный список поддерживаемых API на ScribeJavaGitHub.

3.1. HTTP-клиент

Кроме того,the library allows us to choose which HTTP Client to use: 

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

После, конечно, мы включили необходимые зависимости, для предыдущего примера: 


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

Последние версии можно найти наMaven repository.

3.2. Режим отладки

Кроме того,there’s a debug mode we can use to help us troubleshooting: 

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

Нам просто нужно вызвать методdebug(). Отладка выведет вSystem.out некоторую важную информацию.

Кроме того, если мы хотим использовать другой вывод, есть другой метод, который принимаетOutputStream для отправки отладочной информации по адресу: 

FileOutputStream debugFile = new FileOutputStream("debug");

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

4. OAuth 1.0 Flow

Теперь давайте сосредоточимся на том, как обрабатывать поток OAuth1.

В этом примереwe’re going to get an access token with the Twitter APIs and we’ll use it to make a request.

Прежде всего, мы должны построитьOauth10Service, как мы видели ранее, используя построитель: 

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

Когда у нас естьOAuth10Service, we, мы можем получитьrequestToken и использовать его для получения URL-адреса авторизации: 

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

На этом этапе необходимо перенаправить пользователя наauthUrl и получитьoauthVerifier , предоставленный страницей.

Следовательно, мы используемoauthVerifier to для полученияaccessToken: 

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

Наконец, мы можем создать запрос с использованием объектаOAuthRequest и добавить к нему токен с помощью методаsignRequest(): 

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);

В результате выполнения этогоrequest мы получаем объектResponse.

5. OAuth 2.0 Flow

Поток OAuth 2.0 не сильно отличается от OAuth 1.0. Чтобы объяснить эти вариации,we’re going to get an access token with Google APIs.

Таким же образом, как и в потоке OAuth 1.0, мы должны построитьOAuthService и получитьauthUrl,, но на этот раз мы будем использовать экземплярOAuth20Service: 

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();

Обратите внимание, что в этом случае нам необходимо предоставитьscope запроса иcallback, с которыми с нами свяжутся в конце процесса авторизации.

Точно так же мы должны перенаправить пользователя наauthUrl и взять параметрcode в URL-адресе обратного вызова: 

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);

В конце концов, чтобы сделатьrequest, мы получаем методaccessToken withgetAccessToken().

6. Пользовательские API

Вероятно, нам придется работать с API, который не поддерживается ScribeJava. В этих условияхthe library allows us to implement our own APIs.

Единственное, что нам нужно сделать, это предоставить реализацию классаDefaultApi10 илиDefaultApi20 .

Представим, что у нас есть сервер авторизации OAuth 2.0 с предоставлением пароля. В этом случае мы можем реализоватьDefaultApi20 так, чтобы мы могли взятьaccess 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;
    }
}

Таким образом, мы можем получить токен доступа аналогично тому, как мы делали это раньше: 

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. Заключение

В этой статье мы рассмотрели наиболее полезные классы, которые ScribeJava предоставляет с полки.

Мы узнали, как обрабатывать потоки OAuth 1.0 и OAuth 2.0 с помощью внешних API. Мы также узнали, как настроить библиотеку для использования наших собственных API.

Как обычно, все примеры кода, показанные в этом руководстве, доступныover on GitHub.

Related