Spring Social Reference Manual

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

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

<repository>
    <id>org.springframework.maven.milestone</id>
    <name>Spring Maven Milestone Repository</name>
    <url>http://maven.springframework.org/milestone</url>
</repository>
		

<repository>
    <id>org.springframework.maven.snapshot</id>
    <name>Spring Maven Snapshot Repository</name>
    <url>http://maven.springframework.org/snapshot</url>
</repository>
		

In addition to modules that make up the core Spring Social project, there are a number of provider-specific client modules that are released separately that provide connectivity and API bindings to popular SaaS providers. These client modules are listed in Table 1.2, “Spring Social Client Modules”.

All of these modules are optional, depending on the connectivity needs of your application. For instance, if your application will connect with Facebook, you'll want to add the Facebook module to your project:

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

Note that each of the client modules will progress and release on a different schedule than Spring Social. Consequently, the version numbers for any given client module may not align with Spring Social or any other client module.

Refer to each client module's reference documentation for details on connectivity and the API binding.

Spring Social requires Java 1.5 or greater.

The Spring Social web support requires Java Servlet 2.5 or greater (Tomcat 6+).

Spring Social depends on RestTemplate provided by the core Spring Framework in the spring-web module. It requires Spring Framework version 3.0.5 or above. Spring Framework 3.1 is recommended to take advantage of several RestTemplate improvements.

If you are using Spring Social with Spring Framework 3.0.5 or >, make sure you explicitly add the spring-web dependency to your build:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>3.0.6.RELEASE</version>
</dependency>
			

Maven's dependency management favors "nearest" dependencies, so your project's definition of the spring-web dependency will override Spring Social's transitive dependency on the recommended 3.1 version.

Gradle, on the other hand, favors the newest dependency. If you're using Gradle to build your project, you'll need to also set the dependency's force property to true to force Gradle to resolve your chosen version of Spring:

dependencies { 
    compile ("org.springframework:spring-web:3.0.6.RELEASE") { force=true }
}
			

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 OAuth1 request signing and encrypting credentials when persisting Connection data. If you're already using Spring Security, 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>3.1.0.RC3</version>
</dependency>
	  		

Spring Social has an optional dependency on Apache HttpComponents. If the HttpComponents HttpClient library is present, it will use it as the HTTP client (which is generally recommended). Otherwise, it will fall back on standard J2SE facilities.

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.1.2</version>
</dependency>
	  		

Although shown here to depend on version 4.1.1 of the HttpClient library, Spring Social can also with with 4.0.X versions of HttpClient.

Spring Social's provider API bindings rely on the Jackson JSON Processor to map JSON responses to Java objects. Each binding, such as Facebook or Twitter, transitively depends on Jackson 1.8.5, so there's nothing special to do to add Jackson to your project's Maven or Gradle build.

OAuth 2 is rapidly becoming a preferred authorization protocol, and is used by major service providers such as Facebook, Github, Foursquare, Gowalla, and 37signals. In Spring Social, a OAuth2ConnectionFactory is used to establish connections with a OAuth2-based service provider:

public class OAuth2ConnectionFactory<A> extends ConnectionFactory<A> {

    public OAuth2Operations getOAuthOperations();

    public Connection<A> createConnection(AccessGrant accessGrant);

    public Connection<A> createConnection(ConnectionData data);

}
				

getOAuthOperations() returns an API to use to conduct the authorization flow, or "OAuth Dance", with a service provider. The result of this flow is an AccessGrant that can be used to establish a connection with a local user account by calling createConnection. The OAuth2Operations interface is shown below:

public interface OAuth2Operations {

    String buildAuthorizeUrl(GrantType grantType, OAuth2Parameters parameters);

    String buildAuthenticateUrl(GrantType grantType, OAuth2Parameters parameters);

    AccessGrant exchangeForAccess(String authorizationCode, String redirectUri, 
        MultiValueMap<String, String> additionalParameters);

    AccessGrant refreshAccess(String refreshToken, String scope, 
            MultiValueMap<String, String> additionalParameters);

}
			

Callers are first expected to call buildAuthorizeUrl(GrantType, OAuth2Parameters) to construct the URL to redirect the user to for connection authorization. Upon user authorization, the authorizationCode returned by the provider should be exchanged for an AccessGrant. The AccessGrant should then used to create a connection. This flow is illustrated below:

As you can see, there is a back-and-forth conversation that takes place between the application and the service provider to grant the application access to the provider account. This exchange, commonly known as the "OAuth Dance", follows these steps:

The example code below shows use of a FacebookConnectionFactory to create a connection to Facebook using the OAuth2 server-side flow illustrated above. Here, FacebookConnectionFactory is a subclass of OAuth2ConnectionFactory:

FacebookConnectionFactory connectionFactory = 
    new FacebookConnectionFactory("clientId", "clientSecret");
OAuth2Operations oauthOperations = connectionFactory.getOAuthOperations();
OAuth2Parameters params = new OAuth2Parameters();
params.setRedirectUri("https://my-callback-url");
String authorizeUrl = oauthOperations.buildAuthorizeUrl(GrantType.AUTHORIZATION_CODE, params);
response.sendRedirect(authorizeUrl);

// upon receiving the callback from the provider:
AccessGrant accessGrant = oauthOperations.exchangeForAccess(authorizationCode, "https://my-callback-url", null);
Connection<Facebook> connection = connectionFactory.createConnection(accessGrant);
				

The following example illustrates the client-side "implicit" authorization flow also supported by OAuth2. The difference between this flow and the server-side "authorization code" flow above is the provider callback directly contains the access grant (no additional exchange is necessary). This flow is appropriate for clients incapable of keeping the access grant credentials confidential, such as a mobile device or JavaScript-based user agent.

FacebookConnectionFactory connectionFactory = 
    new FacebookConnectionFactory("clientId", "clientSecret");
OAuth2Operations oauthOperations = connectionFactory.getOAuthOperations();
OAuth2Parameters params = new OAuth2Parameters();
params.setRedirectUri("https://my-callback-url");
String authorizeUrl = oauthOperations.buildAuthorizeUrl(GrantType.IMPLICIT_GRANT, params);
response.sendRedirect(authorizeUrl);

// upon receiving the callback from the provider:
AccessGrant accessGrant = new AccessGrant(accessToken);
Connection<Facebook> connection = connectionFactory.createConnection(accessGrant);
				

OAuth 1 is the previous version of the OAuth protocol. It is more complex OAuth 2, and sufficiently different that it is supported separately. Twitter, Linked In, and TripIt are some of the well-known ServiceProviders that use OAuth 1. In Spring Social, the OAuth1ConnectionFactory allows you to create connections to a OAuth1-based Service Provider:

public class OAuth1ConnectionFactory<A> extends ConnectionFactory<A> {

    public OAuth1Operations getOAuthOperations();

    public Connection<A> createConnection(OAuthToken accessToken);

    public Connection<A> createConnection(ConnectionData data);

}
			

Like a OAuth2-based provider, getOAuthOperations() returns an API to use to conduct the authorization flow, or "OAuth Dance". The result of the OAuth 1 flow is an OAuthToken that can be used to establish a connection with a local user account by calling createConnection. The OAuth1Operations interface is shown below:

public interface OAuth1Operations {

    OAuthToken fetchRequestToken(String callbackUrl, 
        MultiValueMap<String, String> additionalParameters);

    String buildAuthorizeUrl(String requestToken, OAuth1Parameters parameters);

    String buildAuthenticateUrl(String requestToken, OAuth1Parameters parameters);

    OAuthToken exchangeForAccessToken(AuthorizedRequestToken requestToken, 
        MultiValueMap<String, String> additionalParameters);

}
			

Callers are first expected to call fetchNewRequestToken(String) to obtain a temporary token from the ServiceProvider to use during the authorization session. Next, callers should call buildAuthorizeUrl(String, OAuth1Parameters) to construct the URL to redirect the user to for connection authorization. Upon user authorization, the authorized request token returned by the provider should be exchanged for an access token. The access token should then used to create a connection. This flow is illustrated below:

The example code below shows use of a TwitterConnectionFactory to create a connection to Facebook using the OAuth1 server-side flow illustrated above. Here, TwitterConnectionFactory is a subclass of OAuth1ConnectionFactory:

TwitterConnectionFactory connectionFactory = 
    new TwitterConnectionFactory("consumerKey", "consumerSecret");
OAuth1Operations oauthOperations = connectionFactory.getOAuthOperations();
OAuthToken requestToken = oauthOperations.fetchRequestToken("https://my-callback-url", null);
String authorizeUrl = oauthOperations.buildAuthorizeUrl(requestToken, OAuth1Parameters.NONE);
response.sendRedirect(authorizeUrl);

// upon receiving the callback from the provider:
OAuthToken accessToken = oauthOperations.exchangeForAccessToken(
    new AuthorizedRequestToken(requestToken, oauthVerifier), null);
Connection<Twitter> connection = connectionFactory.createConnection(accessToken);
				

As you will see in subsequent sections of this reference guide, Spring Social provides infrastructure for establishing connections to one or more providers in a dynamic, self-service manner. For example, one client application may allow users to connect to Facebook, Twitter, and LinkedIn. Another might integrate Github and Pivotal Tracker. To make the set of connectable providers easy to manage and locate, Spring Social provides a registry for centralizing connection factory instances:

ConnectionFactoryRegistry registry = new ConnectionFactoryRegistry();
registry.addConnectionFactory(new FacebookConnectionFactory("clientId", "clientSecret"));
registry.addConnectionFactory(new TwitterConnectionFactory("consumerKey", "consumerSecret"));
registry.addConnectionFactory(new LinkedInConnectionFactory("consumerKey", "consumerSecret"));	
			

This registry implements a locator interface that other objects can use to lookup connection factories dynamically:

public interface ConnectionFactoryLocator {

    ConnectionFactory<?> getConnectionFactory(String providerId);

    <A> ConnectionFactory<A> getConnectionFactory(Class<A> apiType);
	
    Set<String> registeredProviderIds();

}	
			

Example usage of a ConnectionFactoryLocator is shown below:

// generic lookup by providerId
ConnectionFactory<?> connectionFactory = locator.getConnectionFactory("facebook");

// typed lookup by service api type
ConnectionFactory<Facebook> connectionFactory = locator.getConnectionFactory(Facebook.class);	
			

public interface ConnectionRepository {

    MultiValueMap<String, Connection<?>> findAllConnections();
	
    List<Connection<?>> findConnections(String providerId);

    <A> List<Connection<A>> findConnections(Class<A> apiType);

    MultiValueMap<String, Connection<?>> findConnectionsToUsers(
        MultiValueMap<String, String> providerUserIds);

    Connection<?> getConnection(ConnectionKey connectionKey);

    <A> Connection<A> getConnection(Class<A> apiType, String providerUserId);	

    <A> Connection<A> getPrimaryConnection(Class<A> apiType);

    <A> Connection<A> findPrimaryConnection(Class<A> apiType);
	
    void addConnection(Connection<?> connection);

    void updateConnection(Connection<?> connection);

    void removeConnections(String providerId);

    void removeConnection(ConnectionKey connectionKey);

}
		

public interface UsersConnectionRepository {

    String findUserIdWithConnection(Connection<?> connection);

    Set<String> findUserIdsConnectedTo(String providerId, Set<String> providerUserIds);

    ConnectionRepository createConnectionRepository(String userId);

}
		

Spring Social provides a JdbcUsersConnectionRepository implementation capable of persisting connections to a RDBMS. The database schema designed to back this repository is defined as follows:

create table UserConnection (userId varchar(255) not null,
    providerId varchar(255) not null,
    providerUserId varchar(255),
    rank int not null,
    displayName varchar(255),
    profileUrl varchar(512),
    imageUrl varchar(512),
    accessToken varchar(255) not null,					
    secret varchar(255),
    refreshToken varchar(255),
    expireTime bigint,
    primary key (userId, providerId, providerUserId));
create unique index UserConnectionRank on UserConnection(userId, providerId, rank);
  			

For convenience is bootstrapping the schema from a running application, this schema definition is available in the spring-social-core module as a resource at the path /org/springframework/social/connect/jdbc/JdbcUsersConnectionRepository.sql.

The implementation also provides support for encrypting authorization credentials so they are not stored in plain-text.

The example code below demonstrates construction and usage of a JdbcUsersConnectionRepository:

// JDBC DataSource pointing to the DB where connection data is stored
DataSource dataSource = ...;

// locator for factories needed to construct Connections when restoring from persistent form
ConnectionFactoryLocator connectionFactoryLocator = ...;

// encryptor of connection authorization credentials
TextEncryptor encryptor = ...;

UsersConnectionRepository usersConnectionRepository =
    new JdbcUsersConnectionRepository(dataSource, connectionFactoryLocator, encryptor);

// create a connection repository for the single-user 'kdonald'
ConnectionRepository repository = usersConnectionRepository.createConnectionRepository("kdonald");

// find kdonald's primary Facebook connection
Connection<Facebook> connection = repository.findPrimaryConnection(Facebook.class);
			

We recommend the code for a new Spring Social client module reside within the org.springframework.social.{providerId} base package, where {providerId} is a unique identifier you assign to the service provider you are adding support for. Consider some of the providers already supported by the framework as examples:

Within the base package, we recommend the following subpackage structure:

You can see this recommended structure in action by reviewing one of the other client modules such as spring-social-twitter:

Here, the central service API type, Twitter, is located in the api package along with its supporting operations types and data transfer object types. The primary implementation of that interface, TwitterTemplate, is located in the api.impl package (along with other package-private impl types have that been excluded from this view). Finally, the connect package contains the implementations of various connect SPIs that enable connections to Twitter to be established and persisted.

API developers retain full control over the design and implementation of their Java bindings. That said, we offer several design guidelines in an effort to improve overall consistency and quality:

API developers are free to implement their Java API binding with whatever REST/HTTP client they see fit. That said, Spring Social's existing API bindings such as spring-social-twitter all use Spring Framework's RestTemplate in conjunction with the Jackson JSON ObjectMapper and Apache HttpComponents HTTP client. RestTemplate is a popular REST client that provides a uniform object mapping interface across a variety of data exchange formats (JSON, XML, etc). Jackson is the leading Java-based JSON marshalling technology. Apache HttpComponents has proven to be the most robust HTTP client (if it is not available on the classpath Spring Social will fallback to standard J2SE facilities, however). To help promote consistency across Spring Social's supported bindings, we do recommend you consider these implementation technologies (and please let us know if they do not meet your needs).

Spring Social has adopted a convention where each API implementation class is named "{ProviderId}Template" e.g. TwitterTemplate. We favor this convention unless there is a good reason to deviate from it. As discussed in the previous section, we recommend keeping implementation types separate from the public API types. We also recommend keeping internal implementation details package-private.

The way in which an API binding implementation is constructed will vary based on the API's authorization protocol. For APIs secured with OAuth1, the consumerKey, consumerSecret, accessToken, and accessTokenSecret will be required for construction:

public TwitterTemplate(String consumerKey, String consumerSecret, String accessToken, 
    String accessTokenSecret) { ... }
				

For OAuth2, only the access token should be required:

public FacebookTemplate(String accessToken) { ... }
				

Each request made to the API server needs to be signed with the authorization credentials provided during construction of the binding. This signing process consists of adding an "Authorization" header to each client request before it is executed. For OAuth1, the process is quite complicated, and is used to support an elaborate request signature verification algorithm between the client and server. For OAuth2, it is a lot simpler, but does still vary across the various drafts of the OAuth2 specification.

To encapsulate this complexity, for each authorization protocol Spring Social provides a ApiTemplate base class you may extend from to construct a pre-configured RestTemplate instance that performs the request signing for you. For OAuth1:

public class TwitterTemplate extends AbstractOAuth1ApiBinding {
    public TwitterTemplate(String consumerKey, String consumerSecret, String accessToken, 
            String accessTokenSecret) {
        super(consumerKey, consumerSecret, accessToken, accessTokenSecret);
    }
}			

An OAuth2 example:

public class FacebookTemplate extends AbstractOAuth2ApiBinding {
    public FacebookTemplate(String accessToken) {
        super(accessToken);
    }
}
				

Once configured as shown above, you simply implement call getRestTemplate() and implement the various API operations. The existing Spring Social client modules all invoke their RestTemplate instances in a standard manner:

public TwitterProfile getUserProfile() {
    return getRestTemplate().getForObject(buildUri("account/verify_credentials.json"),
        TwitterProfile.class);
}
				

A note on RestTemplate usage: we do favor the RestTemplate methods that accept a URI object instead of a uri String. This ensures we always properly encode client data submitted in URI query parameters, such as screen_name below:

public TwitterProfile getUserProfile(String screenName) {
    return getRestTemplate().getForObject(buildUri("users/show.json", 
        Collections.singletonMap("screen_name", screenName)), TwitterProfile.class);
}
				

For complete implementation examples, consult the source of the existing API bindings included in Spring Social. The spring-social-twitter and spring-social-facebook modules provide particularly good references.

As part of the spring-social-test module, Spring Social includes a framework for unit testing API bindings. This framework consists of a "MockRestServiceServer" that can be used to mock out API calls to the remote service provider. This allows for the development of independent, performant, automated unit tests that verify client API binding and object mapping behavior.

To use, first create a MockRestServiceServer against the RestTemplate instance used by your API implementation:

TwitterTemplate twitter = new TwitterTemplate("consumerKey", "consumerSecret", "accessToken",
    "accessTokenSecret");
MockRestServer mockServer = MockRestServiceServer.createServer(twitter.getRestTemplate());
			

Then, for each test case, record expectations about how the server should be invoked and answer what it should respond with:

@Test
public void getUserProfile() {
    HttpHeaders responseHeaders = new HttpHeaders();
    responseHeaders.setContentType(MediaType.APPLICATION_JSON);
    
    mockServer.expect(requestTo("https://api.twitter.com/1/account/verify_credentials.json"))
        .andExpect(method(GET))
        .andRespond(withResponse(jsonResource("verify-credentials"), responseHeaders));

    TwitterProfile profile = twitter.userOperations().getUserProfile();
    assertEquals(161064614, profile.getId());
    assertEquals("kdonald", profile.getScreenName());
}
			

In the example above the response body is written from a verify-credentials.json file located in the same package as the test class:

private Resource jsonResource(String filename) {
    return new ClassPathResource(filename + ".json", getClass());
}
			

The content of the file should mirror the content the remote service provider would return, allowing the client JSON deserialization behavior to be fully tested:

{
    "id":161064614,
    "screen_name":"kdonald"
}
			

For complete test examples, consult the source of the existing API bindings included in Spring Social. The spring-social-twitter and spring-social-facebook modules provide particularly good references.

If you are adding support for a popular service provider, chances are a Java binding to the provider's API may already exist. For example, the Twitter4j library has been around for awhile and provides a complete binding to Twitter's API. Instead of developing your own binding, you may simply wish to integrate what already exists. Spring Social's connect framework has been carefully designed to support this scenario.

To integrate an existing API binding, simply note the binding's primary API interface and implementation. For example, in Twitter4j the main API interface is named "Twitter" and instances are constructed by a TwitterFactory. You can always construct such an API instance directly, and you'll see in the following sections how to expose an instance as part of a Connection.

To implement an OAuth2-based ServiceProvider, first create a subclass of AbstractOAuth2ServiceProvider named {ProviderId}ServiceProvider. Parameterize <A> to be the Java binding to the ServiceProvider's's API. Define a single constructor that accepts an clientId and clientSecret. Finally, implement getApi(String) to return a new API instance.

See org.springframework.social.facebook.connect.FacebookServiceProvider as an example OAuth2ServiceProvider:

public final class FacebookServiceProvider extends AbstractOAuth2ServiceProvider<Facebook> {

    public FacebookServiceProvider(String clientId, String clientSecret) {
        super(new OAuth2Template(clientId, clientSecret,
            "https://graph.facebook.com/oauth/authorize",
            "https://graph.facebook.com/oauth/access_token"));
    }

    public Facebook getApi(String accessToken) {
        return new FacebookTemplate(accessToken);
    }

}
			

In the constructor, you should call super, passing up the configured OAuth2Template that implements OAuth2Operations. The OAuth2Template will handle the "OAuth dance" with the provider, and should be configured with the provided clientId and clientSecret, along with the provider-specific authorizeUrl and accessTokenUrl.

Some providers support provider sign-in (see Chapter 5, Signing in with Service Provider Accounts) through an authentication URL that is distinct from the authorization URL. Using the OAuth2Template constructor as shown above will assume that the authentication URL is the same as the authorization URL. But you may specify a different authentication URL by using OAuth2Template's other constructor. Facebook does not have a separate authentication URL, but for the sake of the example, suppose that Facebook's authentication URL is "https://graph.facebook.com/oauth/authenticate". The following implementation of the FacebookServiceProvider constructor configures the OAuth2Template for that case:

public FacebookServiceProvider(String clientId, String clientSecret) {
    super(new OAuth2Template(clientId, clientSecret,
        "https://graph.facebook.com/oauth/authorize",
        "https://graph.facebook.com/oauth/authenticate",
        "https://graph.facebook.com/oauth/access_token"));
}
			

In getApi(String), you should construct your API implementation, passing it the access token needed to make authorized requests for protected resources.

To implement an OAuth1-based ServiceProvider, first create a subclass of AbstractOAuth1ServiceProvider named {ProviderId}ServiceProvider. Parameterize <A> to be the Java binding to the ServiceProvider's API. Define a single constructor that accepts a consumerKey and consumerSecret. Finally, implement getApi(String, String) to return a new API instance.

See org.springframework.social.twitter.connect.TwitterServiceProvider as an example OAuth1ServiceProvider:

public final class TwitterServiceProvider extends AbstractOAuth1ServiceProvider<Twitter> {

    public TwitterServiceProvider(String consumerKey, String consumerSecret) {
        super(consumerKey, consumerSecret, new OAuth1Template(consumerKey, consumerSecret, 
            "https://twitter.com/oauth/request_token",
            "https://twitter.com/oauth/authorize",
            "https://twitter.com/oauth/authenticate",
            "https://twitter.com/oauth/access_token"));
    }

    public Twitter getApi(String accessToken, String secret) {
        return new TwitterTemplate(getConsumerKey(), getConsumerSecret(), accessToken, secret);
    }

}
			

In the constructor, you should call super, passing up the the consumerKey, secret, and configured OAuth1Template. The OAuth1Template will handle the "OAuth dance" with the provider. It should be configured with the provided consumerKey and consumerSecret, along with the provider-specific requestTokenUrl, authorizeUrl, authenticateUrl, and accessTokenUrl. The authenticateUrl parameter is optional and may be left out if the provider doesn't have an authentication URL that is different than the authorization URL.

As you can see here, OAuth1Template is constructed with Twitter's authentication URL (used for provider sign-in; see Chapter 5, Signing in with Service Provider Accounts), which is distinct from their authorization URL. Some providers don't have separate URLs for authentication and authorization. In those cases, you can use OAuth1Template's other constructor which doesn't take the authentication URL as a parameter. For example, here's how the TwitterServiceProvider constructor would look without configuring the authentication URL:

public TwitterServiceProvider(String consumerKey, String consumerSecret) {
    super(consumerKey, consumerSecret, new OAuth1Template(consumerKey, consumerSecret, 
        "https://twitter.com/oauth/request_token",
        "https://twitter.com/oauth/authorize",
        "https://twitter.com/oauth/access_token"));
}
			

In getApi(String, String), you should construct your API implementation, passing it the four tokens needed to make authorized requests for protected resources.

Create a subclass of OAuth2ConnectionFactory<A> named {ProviderId}ConnectionFactory and parameterize A to be the Java binding to the service provider's API. Define a single constructor that accepts a clientId and clientSecret. Within the constructor call super, passing up the assigned providerId, a new {ProviderId}ServiceProvider instance configured with the clientId/clientSecret, and a new {Provider}Adapter instance.

See org.springframework.social.facebook.connect.FacebookConnectionFactory as an example OAuth2ConnectionFactory:

public class FacebookConnectionFactory extends OAuth2ConnectionFactory<Facebook> {
    public FacebookConnectionFactory(String clientId, String clientSecret) {
        super("facebook", new FacebookServiceProvider(clientId, clientSecret), new FacebookAdapter());
    }
}
			

Create a subclass of OAuth1ConnectionFactory<A> named {ProviderId}ConnectionFactory and parameterize A to be the Java binding to the service provider's API. Define a single constructor that accepts a consumerKey and consumerSecret. Within the constructor call super, passing up the assigned providerId, a new {ProviderId}ServiceProvider instance configured with the consumerKey/consumerSecret, and a new {Provider}Adapter instance.

See org.springframework.social.twitter.connect.TwitterConnectionFactory as an example OAuth1ConnectionFactory:

public class TwitterConnectionFactory extends OAuth1ConnectionFactory<Facebook> {
    public TwitterConnectionFactory(String consumerKey, String consumerSecret) {
        super("twitter", new TwitterServiceProvider(consumerKey, consumerSecret), new TwitterAdapter());
    }
}
			

Consult the source and JavaDoc API for ConnectionFactory and its subclasses more information, examples, and advanced customization options.

@Configuration
public class SocialConfig {

}
			

@Configuration
public class SocialConfig {

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

    @Inject
    private Environment environment;
	
}

@Configuration
public class SocialConfig {

    @Bean
    @Scope(value="request", proxyMode=ScopedProxyMode.INTERFACES)
    public ConnectionRepository connectionRepository(
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication == null) {
            throw new IllegalStateException("Unable to get a ConnectionRepository: no user signed in");
        }
        return usersConnectionRepository().createConnectionRepository(authentication.getName());
    }
	
}
		

@Configuration
public class SocialConfig {

    @Bean
    public UsersConnectionRepository usersConnectionRepository() {
        return new JdbcUsersConnectionRepository(dataSource, connectionFactoryLocator(), 
            textEncryptor);
    }

    @Inject
    private DataSource dataSource;

    @Inject
    private TextEncryptor textEncryptor;	
}
		

@Configuration
public class SecurityConfig {

    @Configuration
    @Profile("dev")
    static class Dev {

        @Bean
        public TextEncryptor textEncryptor() {
            return Encryptors.noOpText();
        }

    }

}
		

@Configuration
public class SecurityConfig {

    @Configuration
    @Profile("prod")
    static class Prod {

        @Bean
        public TextEncryptor textEncryptor() {
            return Encryptors.queryableText(environment.getProperty("security.encryptPassword"),
                environment.getProperty("security.encryptSalt"));
        }

        @Inject
        private Environment environment;

    }

}
		

Up to this point, the connection support configuration has been done using Spring's Java-based configuration style. But you can configure it in either Java configuration or XML. Here's the XML equivalent of the ConnectionFactoryRegistry configuration:

<bean id="connectionFactoryLocator" 
      class="org.springframework.social.connect.support.ConnectionFactoryRegistry">
    <property name="connectionFactories">
        <list>
            <bean class="org.springframework.social.twitter.connect.TwitterConnectionFactory">
                <constructor-arg value="${twitter.consumerKey}" />
                <constructor-arg value="${twitter.consumerSecret}" />				
            </bean>
            <bean class="org.springframework.social.facebook.connect.FacebookConnectionFactory">
                <constructor-arg value="${facebook.clientId}" />
                <constructor-arg value="${facebook.clientSecret}" />				
            </bean>
        </list>
    </property>
</bean>
			

This is functionally equivalent to the Java-based configuration of ConnectionFactoryRegistry shown before.

Here's an XML equivalent of the JdbcUsersConnectionRepository and ConnectionRepository configurations shown before:

<bean id="usersConnectionRepository" 
      class="org.springframework.social.connect.jdbc.JdbcUsersConnectionRepository">
    <constructor-arg ref="dataSource" />
    <constructor-arg ref="connectionFactoryLocator" />
    <constructor-arg ref="textEncryptor" />
</bean>

<bean id="connectionRepository" factory-method="createConnectionRepository" 
      factory-bean="usersConnectionRepository" scope="request">
    <constructor-arg value="#{request.userPrincipal.name}" />
    <aop:scoped-proxy proxy-target-class="false" />
</bean>
			

Likewise, here is the equivalent configuration of the TextEncryptor beans:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans 
        http://www.springframework.org/schema/beans/spring-beans-3.1.xsd">

    <beans profile="dev">
        <bean id="textEncryptor" class="org.springframework.security.crypto.encrypt.Encryptors" 
            factory-method="noOpText" />
    </beans>
	
    <beans profile="prod">
        <bean id="textEncryptor" class="org.springframework.security.crypto.encrypt.Encryptors" 
                factory-method="text">
            <constructor-arg value="${security.encryptPassword}" />
            <constructor-arg value="${security.encryptSalt}" />
        </bean>
    </beans>

</beans>
			

Just like the Java-based configuration, profiles are used to select which of the text encryptors will be created.

@Configuration
public class SocialConfig {

    @Bean
    public ConnectController connectController() {
        return new ConnectController(connectionFactoryLocator(), 
            connectionRepository());
    }
    
}
		

<bean class="org.springframework.social.connect.web.ConnectController">
    <!-- relies on by-type autowiring for the constructor-args -->
</bean>
		

@Configuration
public class SocialConfig {

    @Bean
    public ConnectController connectController() {
        ConnectController controller = new ConnectController(
            connectionFactoryLocator(), connectionRepository());
        controller.setApplicationUrl(environment.getProperty("application.url");
        return controller;
    }
    
}
		

<bean class="org.springframework.social.connect.web.ConnectController">
    <!-- relies on by-type autowiring for the constructor-args -->
    <property name="applicationUrl" value="${application.url}" />
</bean>
		

Before the connection flow starts in earnest, a web application may choose to show a page that offers the user information on their connection status. This page would offer them the opportunity to create a connection between their account and their social profile. ConnectController can display such a page if the browser navigates to /connect/{provider}.

For example, to display a connection status page for Twitter, where the provider name is "twitter", your application should provide a link similar to this:

<a href="<c:url value="/connect/twitter" />">Connect to Twitter</a>
			

ConnectController will respond to this request by first checking to see if a connection already exists between the user's account and Twitter. If not, then it will with a view that should offer the user an opportunity to create the connection. Otherwise, it will respond with a view to inform the user that a connection already exists.

The view names that ConnectController responds with are based on the provider's name. In this case, since the provider name is "twitter", the view names are "connect/twitterConnect" and "connect/twitterConnected".

Optionally, you may choose to display a page that shows connection status for all providers. In that case, the link might look like this:

<a href="<c:url value="/connect" />">Your connections</a>
			

The view name that ConnectController responds with for this URL is "connect/status".

To kick off the connection flow, the application should POST to /connect/{providerId}. Continuing with the Twitter example, a JSP view resolved from "connect/twitterConnect" might include the following form:

<form action="<c:url value="/connect/twitter" />" method="POST">
    <p>You haven't created any connections with Twitter yet. Click the button to create
       a connection between your account and your Twitter profile. 
       (You'll be redirected to Twitter where you'll be asked to authorize the connection.)</p>
    <p><button type="submit"><img src="<c:url value="/resources/social/twitter/signin.png" />"/>
    </button></p>
</form>
			

When ConnectController handles the request, it will redirect the browser to the provider's authorization page. In the case of an OAuth 1 provider, it will first fetch a request token from the provider and pass it along as a parameter to the authorization page. Request tokens aren't used in OAuth 2, however, so instead it passes the application's client ID and redirect URI as parameters to the authorization page.

For example, Twitter's authorization URL has the following pattern:

https://twitter.com/oauth/authorize?oauth_token={token}

If the application's request token were "vPyVSe"^[1], then the browser would be redirected to https://twitter.com/oauth/authorize?oauth_token=vPyVSe and a page similar to the following would be displayed to the user (from Twitter)^[2]:

In contrast, Facebook is an OAuth 2 provider, so its authorization URL takes a slightly different pattern:

https://graph.facebook.com/oauth/authorize?client_id={clientId}&redirect_uri={redirectUri}

Thus, if the application's Facebook client ID is "0b754" and it's redirect URI is "http://www.mycoolapp.com/connect/facebook", then the browser would be redirected to https://graph.facebook.com/oauth/authorize?client_id=0b754&redirect_uri=http://www.mycoolapp.com/connect/facebook and Facebook would display the following authorization page to the user:

If the user clicks the "Allow" button to authorize access, the provider will redirect the browser back to the authorization callback URL where ConnectController will be waiting to complete the connection.

The behavior varies from provider to provider when the user denies the authorization. For instance, Twitter will simply show a page telling the user that they denied the application access and does not redirect back to the application's callback URL. Facebook, on the other hand, will redirect back to the callback URL with error information as request parameters.

After the user agrees to allow the application have access to their profile on the provider, the provider will redirect their browser back to the application's authorization URL with a code that can be exchanged for an access token. For OAuth 1.0a providers, the callback URL is expected to receive the code (known as a verifier in OAuth 1 terms) in an oauth_verifier parameter. For OAuth 2, the code will be in a code parameter.

ConnectController will handle the callback request and trade in the verifier/code for an access token. Once the access token has been received, the OAuth dance is complete and the application may use the access token to interact with the provider on behalf of the user. The last thing that ConnectController does is to hand off the access token to the ServiceProvider implementation to be stored for future use.

To delete a connection via ConnectController, submit a DELETE request to "/connect/{provider}".

In order to support this through a form in a web browser, you'll need to have Spring's HiddenHttpMethodFilter configured in your application's web.xml. Then you can provide a disconnect button via a form like this:

<form action="<c:url value="/connect/twitter" />" method="post">
  <div class="formInfo">
    <p>
      Spring Social Showcase is connected to your Twitter account.
      Click the button if you wish to disconnect.
    </p>
  </div>
  <button type="submit">Disconnect</button>	
  <input type="hidden" name="_method" value="delete" />
</form>
			

When this form is submitted, ConnectController will disconnect the user's account from the provider. It does this by calling the disconnect() method on each of the Connections returned by the provider's getConnections() method.

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

<bean class="org.springframework.social.connect.signin.web.ProviderSignInController">
    <!-- relies on by-type autowiring for the constructor-args -->    
</bean>
		

@Bean
public ProviderSignInController providerSignInController() {
    ProviderSignInController controller = new ProviderSignInController(connectionFactoryLocator(), 
        usersConnectionRepository(), new SimpleSignInAdapter());
    controller.setApplicationUrl(environment.getProperty("application.url"));
    return controller;
}
		

<bean class="org.springframework.social.connect.signin.web.ProviderSignInController">
    <!-- relies on by-type autowiring for the constructor-args -->    
    <property name="applicationUrl" value="${application.url}" />
</bean>
		

As shown in the Java-based configuration above, ProviderSignInController depends on a handful of other objects to do its job.

When using XML configuration, it isn't necessary to explicitly configure these constructor arguments because ProviderSignInController's constructor is annotated with @Inject. Those dependencies will be given to ProviderSignInController via autowiring. You'll still need to make sure they're available as beans in the Spring application context so that they can be autowired.

You should have already configured most of these dependencies when setting up connection support (in the previous chapter). But when used with ProviderSignInController, you should configure them to be created as scoped proxies:

@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")));
            
    registry.addConnectionFactory(new TwitterConnectionFactory(
        environment.getProperty("twitter.consumerKey"),
        environment.getProperty("twitter.consumerSecret")));
            
    return registry;
}

@Bean
@Scope(value="singleton", proxyMode=ScopedProxyMode.INTERFACES)
public UsersConnectionRepository usersConnectionRepository() {
    return new JdbcUsersConnectionRepository(dataSource, connectionFactoryLocator(), textEncryptor);
}
			

In the event that the sign in attempt fails, the sign in attempt will be stored in the session to be used to present a sign-up page to the user (see Section 5.3, “Signing up after a failed sign in”). By configuring ConnectionFactoryLocator and UsersConnectionRepository as scoped proxies, it enables the proxies to be carried along with the sign in attempt in the session rather than the actual objects themselves.

The SignInAdapter is exclusively used for provider sign in and so a SignInAdapter bean will need to be added to the configuration. But first, you'll need to write an implementation of the SignInAdapter interface.

The SignInAdapter interface is defined as follows:

public interface SignInAdapter {
    void signIn(String userId, Connection<?> connection, NativeWebRequest request);
}
			

The signIn() method takes the local application user's user ID normalized as a String. No other credentials are necessary here because by the time this method is called the user will have signed into the provider and their connection with that provider has been used to prove the user's identity. Implementations of this interface should use this user ID to authenticate the user to the application.

Different applications will implement security differently, so each application must implement SignInAdapter in a way that fits its unique security scheme. For example, suppose that an application's security is based on Spring Security and simply uses a user's account ID as their principal. In that case, a simple implementation of SignInAdapter might look like this:

@Service
public class SpringSecuritySignInAdapter implements SignInAdapter {
    public void signIn(String localUserId, Connection<?> connection, NativeWebRequest request) {
        SecurityContextHolder.getContext().setAuthentication(
            new UsernamePasswordAuthenticationToken(localUserId, null, null));
    }
}
			

With ProviderSignInController and a SignInAdapter configured, the backend support for provider sign in is in place. The last thing to do is to add a sign in button to your application that will kick off the authentication flow with ProviderSignInController.

For example, the following HTML snippet adds a "Signin with Twitter" button to a page:

<form id="tw_signin" action="<c:url value="/signin/twitter"/>" method="POST">
  <button type="submit">
    <img src="<c:url value="/resources/social/twitter/sign-in-with-twitter-d.png"/>" />
  </button>
</form>
			

Notice that the path used in the form's action attribute maps to the first step in ProviderSignInController's flow. In this case, the provider is identified as "twitter".

Clicking this button will trigger a POST request to "/signin/twitter", kicking off the Twitter sign in flow. If the user has not yet signed into Twitter, the user will be presented with the following page from Twitter:

After signing in, the flow will redirect back to the application to complete the sign in process.

By default, the sign up URL is "/signup", relative to the application root. You can override that default by setting the signUpUrl property on the controller. For example, the following configuration of ProviderSignInController sets the sign up URL to "/register":

@Bean
public ProviderSignInController providerSignInController() {
    ProviderSignInController controller = new ProviderSignInController(connectionFactoryLocator(), 
        usersConnectionRepository(), new SimpleSignInAdapter());
    controller.setSignUpUrl("/register");
    return controller;
}
			

Or to set the sign up URL using XML configuration:

<bean class="org.springframework.social.connect.signin.web.ProviderSignInController">
    <property name="signUpUrl" value="/register" />
</bean>
			

Before redirecting to the sign up page, ProviderSignInController collects some information about the authentication attempt. This information can be used to prepopulate the sign up form and then, after successful sign up, to establish a connection between the new account and the provider account.

To prepopulate the sign up form, you can fetch the user profile data from a connection retrieved from ProviderSignInUtils.getConnection(). For example, consider this Spring MVC controller method that setups up the sign up form with a SignupForm to bind to the sign up form:

@RequestMapping(value="/signup", method=RequestMethod.GET)
public SignupForm signupForm(WebRequest request) {
    Connection<?> connection = ProviderSignInUtils.getConnection(request);
    if (connection != null) {
        return SignupForm.fromProviderUser(connection.fetchUserProfile());
    } else {
        return new SignupForm();
    }
}
			

If ProviderSignInUtils.getConnection() returns a connection, that means there was a failed provider sign in attempt that can be completed if the user registers to the application. In that case, a SignupForm object is created from the user profile data obtained from the connection's fetchUserProfile() method. Within fromProviderUser(), the SignupForm properties may be set like this:

public static SignupForm fromProviderUser(UserProfile providerUser) {
    SignupForm form = new SignupForm();
    form.setFirstName(providerUser.getFirstName());
    form.setLastName(providerUser.getLastName());
    form.setUsername(providerUser.getUsername());
    form.setEmail(providerUser.getEmail());
    return form;
}
			

Here, the SignupForm is created with the user's first name, last name, username, and email from the UserProfile. In addition, UserProfile also has a getName() method which will return the user's full name as given by the provider.

The availability of UserProfile's properties will depend on the provider. Twitter, for example, does not provide a user's email address, so the getEmail() method will always return null after a sign in attempt with Twitter.

After the user has successfully signed up in your application a connection can be created between the new local user account and their provider account. To complete the connection call ProviderSignInUtils.handlePostSignUp(). For example, the following method handles the sign up form submission, creates an account and then calls ProviderSignInUtils.handlePostSignUp() to complete the connection:

@RequestMapping(value="/signup", method=RequestMethod.POST)
public String signup(@Valid SignupForm form, BindingResult formBinding, WebRequest request) {
    if (formBinding.hasErrors()) {
        return null;
    }
    Account account = createAccount(form, formBinding);
    if (account != null) {
        SignInUtils.signin(account.getUsername());
        ProviderSignInUtils.handlePostSignUp(account.getUsername(), request);
        return "redirect:/";
    }
    return null;
}
			

To enable implicit sign up, you must create an implementation of the ConnectionSignUp interface and inject an instance of that ConnectionSignUp to the connection repository. The ConnectionSignUp interface is simple, with only a single method to implement:

public interface ConnectionSignUp {
    String execute(Connection<?> connection);
}
			

The execute() method is given a Connection that it can use to retrieve information about the user. It can then use that information to create a new local application user and return the new local user ID. For example, the following implementation fetches the user's provider profile and uses it to create a new account:

public class AccountConnectionSignUp implements ConnectionSignUp {

    private final AccountRepository accountRepository;

    public AccountConnectionSignUp(AccountRepository accountRepository) {
        this.accountRepository = accountRepository;
    }

    public String execute(Connection<?> connection) {
        UserProfile profile = connection.fetchUserProfile();
        Account account = createAccount(profile);
        return account != null ? account.getUsername() : null;
    }

    private Account createAccount(UserProfile profile) {
        if (profile == null || profile.getUsername() == null) {
            return null;
        }
        Account account = new Account(profile.getUsername(), profile.getFirstName(), profile.getLastName());
        accountRepository.createAccount(account);
        return account;
    }
	
}
			

If execute() returns null, then it indicates that the user could not be implicitly signed up. In that case, ProviderSignInController's explicit sign up flow will be in effect and the browser will be redirected to the sign up form.

Once you've written a ConnectionSignUp for your application, you'll need to inject it into the UsersConnectionRepository. In Java-based configuration:

@Bean
@Scope(value="singleton", proxyMode=ScopedProxyMode.INTERFACES) 
public UsersConnectionRepository usersConnectionRepository(AccountRepository accountRepository) {
    JdbcUsersConnectionRepository repository = new JdbcUsersConnectionRepository(
        dataSource, connectionFactoryLocator(), Encryptors.noOpText());
    repository.setConnectionSignUp(new AccountConnectionSignUp(accountRepository));
    return repository;
}