Quick Start

The following steps will get you up and running with Spring Social in your web application. It assumes that you're familiar with Spring Dependency Injection concepts, Spring MVC, and Spring Java Configuration. It also assumes that you will be adding Spring Social to a Spring 3.1 application.

1. Add Spring Social Dependencies

Before you can use Spring Social, you must add the library and its required dependencies to your project.

Core and Web Modules

First, add the core and web modules to your project:

<dependency>
    <groupId>org.springframework.social</groupId>
    <artifactId>spring-social-core</artifactId>
    <version>${spring-social.version}</version>
</dependency>

<dependency>
    <groupId>org.springframework.social</groupId>
    <artifactId>spring-social-web</artifactId>
    <version>${spring-social.version}</version>
</dependency>

Provider Modules

Next, add the provider modules for the providers you wish to integrate into your application. Facebook is shown as an example below:

<dependency>
    <groupId>org.springframework.social</groupId>
    <artifactId>spring-social-facebook</artifactId>
    <version>${spring-social-facebook.version}</version>
</dependency>

Spring Security Crypto Module (Optional)

If you're not already using Spring Security 3.1 to secure your application, you'll need to add the standalone crypto module. This is required for OAuth1 request signing and encrypting credentials when persisting Connection data. If you're already using Spring Security 3.1, there is nothing for you to do because the crypto library comes included.

<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-crypto</artifactId>
    <version>${spring-security-crypto.version}</version>
</dependency>

2. Configure Spring Social

Create a @Configuration class:

/**
 * Spring Social Configuration.
 */
@Configuration
public class SocialConfig {

}

Add a ConnectionFactoryLocator that has registered the providers your app connects to:

@Bean
public ConnectionFactoryLocator connectionFactoryLocator() {
    ConnectionFactoryRegistry registry = new ConnectionFactoryRegistry();
    registry.addConnectionFactory(new FacebookConnectionFactory(environment.getProperty("facebook.clientId"),
        environment.getProperty("facebook.clientSecret")));
    return registry;
}

@Inject
private Environment environment;

Add a UsersConnectionRepository for persisting Connection data across all users:

@Bean
public UsersConnectionRepository usersConnectionRepository() {
    JdbcUsersConnectionRepository repository = new JdbcUsersConnectionRepository(dataSource, 
        connectionFactoryLocator(), Encryptors.noOpText());
    repository.setConnectionSignUp(new SimpleConnectionSignUp());
    return repository;
}

@Inject
private DataSource dataSource;

Add a ConnectionRepository for managing the current user's connections:

@Bean
@Scope(value="request", proxyMode=ScopedProxyMode.INTERFACES)
public ConnectionRepository connectionRepository() {
    User user = SecurityContext.getCurrentUser();
    return usersConnectionRepository().createConnectionRepository(user.getId());
}

Add one or more request-scoped beans representing current user API bindings. Facebook is shown here:

@Bean
@Scope(value="request", proxyMode=ScopedProxyMode.INTERFACES)	
public Facebook facebook() {
    return connectionRepository().getPrimaryConnection(Facebook.class).getApi();
}

Add a ProviderSignInController that allows users to sign-in using their provider accounts:

@Bean
public ProviderSignInController providerSignInController() {
    return new ProviderSignInController(connectionFactoryLocator(), usersConnectionRepository(),
        new SimpleSignInAdapter());
}

3. Create Views

Create a "signin" view that allows users to sign-in with their provider account:

<%@ page session="false" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>

<form action="<c:url value="/signin/facebook" />" method="POST">
    <button type="submit">Sign in with Facebook</button>
</form>

4. Invoke APIs

Finally, @Inject references to API bindings into the objects that need them. An example @Controller that retrieves the current user's facebook friends is shown below:

@Controller
public class HomeController {

    private final Facebook facebook;

    @Inject
    public HomeController(Facebook facebook) {
        this.facebook = facebook;
    }
	
    @RequestMapping(value="/", method=RequestMethod.GET)
    public String home(Model model) {
        List<Reference> friends = facebook.friendOperations().getFriends();
        model.addAttribute("friends", friends);
        return "home";
    }
	
}

5. Enjoy using Spring Social!

A executable version of this quickstart is available as a sample application. It includes the full SocialConfig source code you may plug into your own application. A Spring Framework 3.0.5 compatible version is also available.

Refer to the reference documentation, additional samples, and Greenhouse for more information on using Spring Social.