Clone wiki

oauth-2.0 / Client

Leeloo OAuth 2.0 client in 5 minutes:

Getting OAuth 2.0 access token in your Java application

This example shows how to receive an access token from Facebook. It should work similarly with other OAuth 2.0 compatible implementations. See for the list of current OAuth 2.0 server implementations.

You can also run a sample client app available at: Client Tutorial

or go through the following steps:

1. Add Leeloo client to your classpath:

  • add Maven dependency:


or download distribution bundle

2. Build OAuth End User Authorization Request

Create the End User Authorization Request by providing end-user authorization URI at the Authorization Server (e.g. Facebook), your application's client id and a redirect URI, in order to receive the authorization code.

         OAuthClientRequest request = OAuthClientRequest

The above code will produce an OAuth request where all the parameters are encoded in the URL query. You can obtain the generated URL by calling this method:


For example, in a Java Servlet, you would execute the following code:

    protected void doGet(HttpServletRequest servletRequest, HttpServletResponse servletResponse)
        throws ServletException, IOException {

   OAuthClientRequest request;

   // ... omitted code ...



The user is redirected to Facebook (the authorization page, to be exact), which asks the user which permission they would like to grant to your application. The user simply needs to click Allow.

3. Get Authorization Code from redirect URI

After the user grants permission for your client application, then Facebook redirects the user to: (recall step Step 2), with request parameter similar to: code=2.89e3QEvryHUOHPe9YMqpeA.3600.1285585200-1556050396|5CUsytnAALwWALAUUM8KHlJVNpQ.

OAuthAuthzResponse oar = OAuthAuthzResponse.oauthCodeAuthzResponse(request);
String code = oar.getCode();

4. Exchange OAuth code for an access token

OAuthClientRequest request = OAuthClientRequest

            //create OAuth client that uses custom http client under the hood 
            OAuthClient oAuthClient = new OAuthClient(new URLConnectionClient());

            //Facebook is not fully compatible with OAuth 2.0 draft 10, access token response is
            //application/x-www-form-urlencoded, not json encoded so we use dedicated response class for that
            //Custom response classes are an easy way to deal with oauth providers that introduce modifications to
            //OAuth 2.0 specification
            GitHubTokenResponse oAuthResponse = oAuthClient.accessToken(request, GitHubTokenResponse.class);

            String accessToken = oAuthResponse.getAccessToken();
            String expiresIn = oAuthResponse.getExpiresIn();

Now you can store the accessToken and an optional refreshToken.

For a fully working code see oauth-demo included in the package!


Additional features

  • Provide custom response readers

Leeloo is extensible and you can provide your own custom response classes that can handle responses from providers that introduce modifications to the core OAuth 2.0 specification. For example, you providers can read access tokens from application/x-www-form-urlencoded instead of json encoded body.

Just create your own class that extends:


and pass it as one of the oAuthClient.accessToken(); parameters.

  • Use your own HTTP client

OAuthClient can use different java http clients with customized configurations like timeouts, connection pools, etc. in order communicate with authorization servers and receive access tokens. Leeloo provides an exemplar implementation of the URLConnection client and Apache's HttpClient 4.

You can easily write your own HTTP client by extending: