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

6 августа 2021 г. · 5 мин. чтения

1. Введение

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

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

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

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

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

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

ScribeJava состоит из ядра и модуля API , последний включает в себя набор внешних API (Google, GitHub, Twitter и т. д.) и основной артефакт:

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-apis</artifactId>
    <version>latest-version</version>
</dependency>

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

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-core</artifactId>
    <version>latest-version</version>
</dependency>

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

3. `Сервис OAuth`

Основной частью библиотеки является абстрактный класс 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 , предоставленные сервером авторизации.

Также мы можем установить область запроса и обратный вызов , на который сервер авторизации должен перенаправить пользователя в конце потока авторизации.

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

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

3.1. HTTP-клиент

Более того, библиотека позволяет нам выбирать, какой HTTP-клиент использовать:

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

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

<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-httpclient-okhttp</artifactId>
    <version>latest-version</version>
</dependency>

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

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

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

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

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

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

FileOutputStream debugFile = new FileOutputStream("debug");

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

4. Поток OAuth 1.0

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

В этом примере мы собираемся получить токен доступа с API Twitter и использовать его для выполнения запроса.

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

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

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

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

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

Следовательно, мы используем oauthVerifier для получения 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);

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

5. Поток OAuth 2.0

Поток OAuth 2.0 мало чем отличается от OAuth 1.0. Чтобы объяснить эти варианты, мы собираемся получить токен доступа с API Google.

Точно так же, как мы это делали в потоке 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();

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

Точно так же мы должны перенаправить пользователя на authUrl и взять параметр кода в 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);

В конце концов, чтобы сделать запрос , мы получаем accessToken с помощью метода getAccessToken() .

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

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

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

Предположим, у нас есть сервер авторизации OAuth 2.0 с предоставлением пароля. В этом случае мы можем реализовать DefaultApi20 , чтобы получить токен доступа :

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("foreach_api_key")
  .apiSecret("foreach_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.

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

1. Введение​

2. Зависимости​

3. Сервис OAuth​

3.1. HTTP-клиент​

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

4. Поток OAuth 1.0​

5. Поток OAuth 2.0​

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

7. Заключение​