Guia para ScribeJava

1. Introdução

Neste tutorial, vamos dar uma olhada na bibliotecaScribeJava.

ScribeJava é um cliente OAuth simples para Java que ajuda a gerenciar o fluxo OAuth.

O principal recurso da biblioteca é que ele suporta todas as principais APIs OAuth 1.0 e 2.0 prontas para uso. Além disso, se tivermos que trabalhar com uma API que não é compatível, a biblioteca fornece algumas classes para implementar nossas APIs OAuth.

Outra característica importante é que é possível escolher qual cliente usar. De fato, o ScribeJava suporta vários clientes HTTP:

Além disso, a biblioteca é segura para threads e compatível com Java7, para que possamos usá-la em ambientes legados.

2. Dependências

ScribeJava is organized into a core and APIs module, o último inclui um conjunto de API externa (Google, GitHub, Twitter, etc) e o artefato principal:


    com.github.scribejava
    scribejava-apis
    latest-version

Caso precisemos apenas de classes principais sem nenhuma API externa, precisamos extrair apenas o módulo principal:


    com.github.scribejava
    scribejava-core
    latest-version

As versões mais recentes podem ser encontradas emMaven repository.

3. OAuthService

The main part of the library is the abstract class OAuthService que contém todos os parâmetros necessários para gerenciar corretamente o 'handshake' do OAuth.

Dependendo da versão do protocolo, usaremosOauth10Service ouOauth20Service classes concretas, respectivamente, paraOAuth 1.0eOAuth 2.0.

Para construir as implementações deOAuthService, a biblioteca fornece umServiceBuilder:

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

Devemos definir os tokensapi_keyeapi_secret fornecidos pelo servidor de autorização.

Além disso, podemos definir oscope da solicitação e ocallback para o qual o servidor de autorização deve redirecionar o usuário no final do fluxo de autorização.

Observe que, dependendo da versão do protocolo, nem todos os parâmetros são obrigatórios.

Finalmente, temos que construir oOAuthService chamando o métodobuild() e passando para ele uma instância das APIs que queremos usar. Podemos encontrar uma lista completa das APIs com suporte em ScribeJavaGitHub.

3.1. Cliente HTTP

Além disso,the library allows us to choose which HTTP Client to use:

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

Depois, é claro, incluímos as dependências necessárias, para o exemplo anterior:


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

As versões mais recentes podem ser encontradas emMaven repository.

3.2. Modo de depuração

Além disso,there’s a debug mode we can use to help us troubleshooting:

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

Simplesmente temos que chamar o métododebug(). A depuração produzirá paraSystem.out algumas informações relevantes.

Além disso, se quisermos usar uma saída diferente, há outro método que aceita umOutputStream para enviar as informações de depuração para:

FileOutputStream debugFile = new FileOutputStream("debug");

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

4. Fluxo OAuth 1.0

Agora vamos nos concentrar em como lidar com um fluxo OAuth1.

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

Em primeiro lugar, temos que construirOauth10Service, como vimos anteriormente, usando o builder:

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

Assim que tivermosOAuth10Service, we, podemos obter umrequestTokene usá-lo para obter o URL de autorização:

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

Nesse ponto, é necessário redirecionar o usuário paraauthUrle obter ooauthVerifier distribuído pela página.

Portanto, usamos ooauthVerifier para obter oaccessToken:

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

Finalmente, podemos criar uma solicitação usando o objetoOAuthRequest e adicionar o token a ele com o métodosignRequest():

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

Como resultado da execução desserequest, obtemos um objetoResponse.

5. Fluxo OAuth 2.0

O fluxo do OAuth 2.0 não é muito diferente do OAuth 1.0. Para explicar essas variações,we’re going to get an access token with Google APIs.

Da mesma forma que fizemos no fluxo OAuth 1.0, temos que construirOAuthServicee obterauthUrl,, mas desta vez usaremos uma instânciaOAuth20Service:

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

Observe que, nesse caso, precisamos fornecer oscope da solicitação e ocallback para o qual seremos contatados no final do fluxo de autorização.

Da mesma forma, temos que redirecionar o usuário paraauthUrle pegar o parâmetrocode no url do retorno de chamada:

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

No final, para fazer orequest, obtemos o métodoaccessToken withgetAccessToken().

6. APIs personalizadas

Provavelmente teremos que trabalhar com uma API que não é compatível com ScribeJava. Nessas circunstâncias,the library allows us to implement our own APIs.

A única coisa que precisamos fazer é fornecer uma implementação deDefaultApi10 ouDefaultApi20 class.

Vamos imaginar que temos um servidor de autorização OAuth 2.0 com concessão de senha. Nesse caso, podemos implementarDefaultApi20 para que possamos pegar umaccess 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;
    }
}

Assim, podemos obter um token de acesso de maneira semelhante à que fizemos antes:

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. Conclusão

Neste artigo, vimos as classes mais úteis que o ScribeJava fornece de prateleira.

Aprendemos como lidar com os fluxos OAuth 1.0 e OAuth 2.0 com APIs externas. Também aprendemos como configurar a biblioteca para usar nossas próprias APIs.

Como de costume, todos os exemplos de código mostrados neste tutorial estão disponíveisover on GitHub.

TOC

Guia para ScribeJava