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 to secure your application, you'll need to add the standalone crypto module. This is required for encrypting credentials when persisting Connection data. If you're already using Spring Security, there 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.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:

/**
* When a new provider is added to the app, register its {@link ConnectionFactory} here.
*/
@Bean
@Scope(value="singleton", proxyMode=ScopedProxyMode.INTERFACES)
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 for all users:

/**
 * The data store for connections across all users.
 */
@Bean
public UsersConnectionRepository usersConnectionRepository() {
    return new JdbcUsersConnectionRepository(dataSource, connectionFactoryLocator(), Encryptors.noOpText());
}

@Inject
private DataSource dataSource;

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

/**
 * A request-scoped bean that provides access to 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 for current user API bindings. Facebook is shown here:

/**
* A proxy to a request-scoped bean representing the current user's primary Facebook account.
*/
@Bean
@Scope(value="request", proxyMode=ScopedProxyMode.INTERFACES)	
public Facebook facebook() {
    return connectionRepository().findPrimaryConnection(Facebook.class).getApi();
}

Add ConnectController that allows users to connect to providers:

/**
 * The Spring MVC Controller that establishes connections to providers on behalf of users.
 */
@Bean
public ConnectController connectController() {
    return new ConnectController(environment.getProperty("application.secureUrl"),
        connectionFactoryLocator(), connectionRepository());
}

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

/**
 * The Spring MVC Controller that allows users to sign-in with their provider accounts.
 */
@Bean
public ProviderSignInController providerSignInController() {
    return new ProviderSignInController(environment.getProperty("application.secureUrl"),
        connectionFactoryLocator(), usersConnectionRepository(),
        connectionRepository(), new SimpleSignInAdapter());
}

3. Create Connect Views

Create a "connect" view that allows users to establish their first connection with a provider. A sample Facebook Connect view is shown, defined in /WEB-INF/views/connect/facebookConnect.jsp:

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

<form action="<c:url value="/connect/facebook" />" method="POST">
    <input type="hidden" name="scope" value="email,publish_stream,offline_access" />
    <button type="submit">Connect</button>
</form>

Create a "connected" view that allows users to manage their existing connections with a provider. A sample Facebook Connected view is shown, defined in /WEB-INF/views/connect/facebookConnected.jsp:

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

<form action="<c:url value="/connect/facebook" />" method="post">
    <button type="submit">Disconnect</button>	
    <input type="hidden" name="_method" value="DELETE" />
</form>

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 provider APIs 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 friends(Model model) {
        List<Reference> friends = facebook.friendOperations().getFriends();
        model.addAttribute("friends", friends);
        return "/facebook/friends";
    }
	
}

5. Enjoy using Spring Social!

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