In this tutorial, we will be building a service that integrates with GitHub. We’ll start right from generating the basic project template, and finish off with a Service that loads, saves, and hits actions on the GitHub API.

The tutorial will assume you are using IntelliJ IDEA Ultimate Edition, and have Maven 3 and JDK 8 or higher installed.

Creating the Service base

Follow the instruction on the Building a Service page to get the base structure of your Service set up.

Building the Describe response

Every Service needs to return a Describe response from its /metadata endpoint. This response tells ManyWho what the Service supports (i.e. Database, Identity, Logic, Files and Social). The Java SDK provides a simple Builder class so it’s super easy to create a Describe response.

  1. Open up DescribeController from inside the controllers package
  2. Our GitHub Service will provide the following:
    • Database (for loading a list of user repositories)
    • Identity (for logging into a flow using GitHub)
    • Logic (for forking a repository)
  3. Add a call to setProvidesIdentity(true) inside the describe() method, so it looks like this:

Create a GitHub application

We’ll need an application on GitHub so that we can authorize users through OAuth2 and make calls on their behalf. You can create a new application on GitHub for free here, and make sure the Callback URL is Make a note of the generated Client ID and Client Secret, as we’ll need them later.

Adding Authentication (Identity)

As the GitHub API is built around authorizing calls using OAuth2, we’ll integrate an identity provider into our Service that ManyWho can use to log into a Flow, which means that we can make calls on behalf of the logged in user without having to store tokens anywhere, or ask them for their password.

Creating the OAuth2 Provider

Each service that integrates with OAuth2 for authorization needs to have a Provider class, that gives the SDK’s OAuth2 library the correct secrets and where to request tokens.

  1. Create a new package inside called oauth2.
  2. Inside this new package, create a class called GitHubProvider.
  3. Make the new class extend AbstractOauth2Provider, which is a base class in the SDK for creating a provider in services that implement OAuth2.
  4. Press Ctrl+I then Enter to implement the required methods from the interface.
  5. Fill in the details based on this example:

Creating the AuthService

  1. Create a new package inside called services.
  2. Inside this new package, create a class called AuthService, and paste in the following code:

Basically, in the code we just pasted, the authenticateWithGitHub() method will be called from inside the AuthController (which we’ll create in a minute), it calls out to the GitHub API to fetch the logged in user (using the GitHub Java library) and it returns an AuthenticatedWhoResult object that contains all of the logged-in user’s information ready to be used inside a flow.

Finally, we’ll need to add the AuthService into the application binder, so that it can be injected into other classes by Jersey:

  1. Open ApplicationBinder in the root of the main package (
  2. Inside the configure() method, add a new line that binds any calls to AuthService to an instance of AuthService, like so:

Creating the AuthController

  1. Create a new class in the controllers package called AuthController.
  2. Make the new class extend AbstractOauth2Controller, which is a base controller class in the ManyWho SDK for Services that wish to implement authorization using OAuth2.
  3. Press Ctrl+I then Enter to implement the required authentication() method.
  4. Press Alt+Insert then click Constructor to implement the required constructor that inherits from the AbstractOauth2Controller class.
  5. Now add a new field of type AuthService called authService, and annotate it with the @Inject annotation (so Jersey will automatically supply an instance into the class at runtime).
  6. Finally, add a new method called authentication that returns an AuthenticatedWhoResult, and takes a single AuthenticationCredentials parameter.
  7. Inside this method, return the result of a call to authService.authenticateWithGitHub(oauth2Provider, getOauthService(), authenticationCredentials);
  8. Your AuthController class should now look like this: