In the previous chapter, you learned how Spring Social's Service Provider 'Connect' Framework can be used to manage user connections between your application and external service providers. In this chapter, you'll learn how to control the connect flow in a web application environment.

Spring Social's spring-social-web module includes ConnectController, a Spring MVC controller that works with ServiceProviders to coordinate the connection flow. ConnectController takes care of redirecting the user to the service provider for authorization and responding to the callback after authorization. At each step, ConnectController delegates to a ServiceProvider to handle the finer details such as obtaining a request token and creating connections.

Because ConnectController collaborates with ServiceProviders to establish connections, you'll first need to register one or more ServiceProvider implementations as beans in the Spring context. ConnectController will discover any bean of type ServiceProvider in the Spring context and delegate to it as requested by users of your application.

The following configuration class registers ServiceProvider implementations for Twitter, Facebook, and TripIt using Spring's Java configuration style:

package org.springframework.social.showcase.config.connect;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.social.facebook.connect.FacebookServiceProvider;
import org.springframework.social.tripit.connect.TripItServiceProvider;
import org.springframework.social.twitter.connect.TwitterServiceProvider;

@Configuration
public class ServiceProviderConfig {

    @Bean
    public TwitterServiceProvider twitter(@Value("${twitter.consumerKey}") String consumerKey,
            @Value("${twitter.consumerSecret}") String consumerSecret, ConnectionRepository connectionRepository) {
        return new TwitterServiceProvider(consumerKey, consumerSecret, connectionRepository);
    }

    @Bean
    public FacebookServiceProvider facebook(@Value("${facebook.appId}") String appId,
            @Value("${facebook.appSecret}") String appSecret, ConnectionRepository connectionRepository) {
        return new FacebookServiceProvider(appId, appSecret, connectionRepository);
    }

    @Bean
    public TripItServiceProvider tripit(@Value("${tripit.consumerKey}") String consumerKey,
            @Value("${tripit.consumerSecret}") String consumerSecret, ConnectionRepository connectionRepository) {
        return new TripItServiceProvider(consumerKey, consumerSecret, connectionRepository);
    }

}
		

Each ServiceProvider should be configured with the client key and secret that were assigned to it when the application was registered with the service provider. Because the consumer key and secret may be different across environments (e.g., test, production, etc) it is recommended that these values be externalized. Here, the consumer key and secret are provided to the twitter() method as placeholder variables to be resolved by Spring's property placeholder support.

ServiceProviders are also given a ConnectionRepository at construction. When managing connections, a ServiceProvider needs a place to store those connections. Therefore, a ServiceProvider delegates to a ConnectionRepository for persisting connections. Spring Social supports JDBC-based connection storage with JdbcConnectionRepository, which itself is constructed with a DataSource and a TextEncryptor:.

package org.springframework.social.showcase.config.connect;

import javax.sql.DataSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.social.connect.jdbc.JdbcConnectionRepository;
import org.springframework.social.connect.support.ConnectionRepository;
import org.springframework.security.crypto.encrypt.TextEncryptor;

@Configuration
public class ConnectionRepositoryConfig {

    @Bean
    public ConnectionRepository connectionRepository(DataSource dataSource, TextEncryptor textEncryptor) {
        return new JdbcConnectionRepositoy(dataSource, textEncryptor);
    }

}
		

JdbcConnectionRepository uses a TextEncryptor to encrypt the credentials (e.g., access tokens and secrets) obtained during authorization when writing them to the database. Spring Security 3.1 makes a few useful text encryptors available via static factory methods in its Encryptors class. For example, a no-op text encryptor is useful at development time and can be configured like this:

package org.springframework.social.showcase.config.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.security.crypto.encrypt.Encryptors;
import org.springframework.security.crypto.encrypt.TextEncryptor;

@Configuration
@Profile("dev")
public class DevEncryptionConfig {

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

}
		

Notice that this configuration class is annotated with @Profile("dev"). Spring 3.1 introduced the profile concept where certain beans will only be created when certain profiles are active. Here, the @Profile annotation ensures that this TextEncryptor will only be created when "dev" is an active profile. For production-time purposes, a stronger text encryptor is recommended and can be created when the "production" profile is active:

package org.springframework.social.showcase.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.security.crypto.encrypt.Encryptors;
import org.springframework.security.crypto.encrypt.TextEncryptor;

@Configuration
@Profile("production")
public class ProductionEncryptionConfig {

    @Bean
    public TextEncryptor textEncryptor(@Value("${security.encryptPassword}") String password,
            @Value("${security.encryptSalt}") String salt) {
        return Encryptors.queryableText(password, salt);
    }

}
		

<?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">
	
    <!-- Configure a Twitter service provider -->
    <bean class="org.springframework.social.twitter.connect.TwitterServiceProvider">
        <constructor-arg value="${twitter.consumerKey}" />
        <constructor-arg value="${twitter.consumerSecret}" />
        <constructor-arg ref="connectionRepository" />
    </bean>

    <!-- Configure a Facebook service provider -->
    <bean class="org.springframework.social.facebook.connect.FacebookServiceProvider">
        <constructor-arg value="${facebook.appId}" />
        <constructor-arg value="${facebook.appSecret}" />
        <constructor-arg ref="connectionRepository" />
    </bean>
	
    <!-- Configure a TripIt service provider -->
    <bean class="org.springframework.social.tripit.connect.TripItServiceProvider">
        <constructor-arg value="${tripit.consumerKey}" />
        <constructor-arg value="${tripit.consumerSecret}" />
        <constructor-arg ref="connectionRepository" />
    </bean>

    <!-- Configure a connection repository through which account-to-provider connections will be stored -->	
    <bean id="connectionRepository" class="org.springframework.social.connect.jdbc.JdbcConnectionRepository">
        <constructor-arg ref="dataSource" />
        <constructor-arg ref="textEncryptor" />
    </bean>
    
</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="production">
        <bean id="textEncryptor" class="org.springframework.security.crypto.encrypt.Encryptors" factory-method="queryableText">
            <constructor-arg value="${security.encryptPassword}" />
            <constructor-arg value="${security.encryptSalt}" />
        </bean>
    </beans>

</beans>
			

With one or more ServiceProvider beans configured, ConnectController will be able to coordinate the connection process for those providers. ConnectController is a Spring MVC controller and can be configured as a bean in your application's Spring MVC configuration as follows:

package org.springframework.social.showcase.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.social.web.connect.ConnectController;
import org.springframework.stereotype.Component;

@Configuration
public class ConnectControllerConfig {

    @Bean
    public ConnectController connectController(@Value("${application.url}") String applicationUrl) {
        return new ConnectController(applicationUrl);
    }
	
}
		

Again, if you prefer Spring's XML-based configuration, then you can configure ConnectController like this:

<bean class="org.springframework.social.web.connect.ConnectController">
    <constructor-arg value="${application.url}" />
</bean>
		

In either case, ConnectController is constructed with the base URL for the application. ConnectController will use this URL to construct callback URLs used in the authorization flow. Since the base URL of an application will be different between environments, it is recommended that you externalize it. Here the URL is specified as a placeholder variable.

ConnectController supports authorization flows for either OAuth 1 or OAuth 2, relying on ServiceProviders to handle the specifics for each protocol. ConnectController will discover ServiceProviders as beans in the Spring context. It will select a specific ServiceProvider to use by matching the provider's ID with the URL path. The path pattern that ConnectController handles is "/connect/{providerId}". Therefore, if ConnectController is handling a request for "/connect/twitter", then the ServiceProvider whose getId() returns "twitter" will be used.

The flow that ConnectController follows is slightly different, depending on which authorization protocol is supported by the service provider. For OAuth 2-based providers, the flow is as follows:

For an OAuth 1 provider, the flow is very similar, with only a subtle difference in how the callback is handled:

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

4.3.2 Initiating the connection flow

To kick off the connection flow, the application should POST to /connect/{providerId}. Continuing with the Twitter example, the JSP 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.

Authorization scope

In the previous example of authorizing an application to interact with a user's Facebook profile, you notice that the application is only requesting access to the user's basic profile information. But there's much more that an application can do on behalf of a user with Facebook than simply harvest their profile data. For example, how can an application gain authorization to post to a user's Facebook wall?

OAuth 2 authorization may optionally include a scope parameter that indicates the type of authorization being requested. On the provider, the "scope" parameter should be passed along on the authorization URL. In the case of Facebook, that means that the Facebook authorization URL pattern should be as follows:

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

ConnectController accepts a "scope" parameter at authorization and passes its value along to the provider's authorization URL. For example, to request permission to post to a user's Facebook wall, the connect form might look like this:

<form action="<c:url value="/connect/twitter" />" method="POST">
    <input type="hidden" name="scope" value="publish_stream,offline_access" />
    <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>
				

The hidden "scope" field contains the scope values to be passed along to Facebook's authorization URL. In this case, "publish_stream" requests permission to post to a user's wall. In addition, "offline_access" requests permission to access Facebook on behalf of a user even when the user isn't using the application.

Note

OAuth 2 access tokens typically expire after some period of time. Per the OAuth 2 specification, an application may continue accessing a provider after a token expires by using a refresh token to either renew an expired access token or receive a new access token (all without troubling the user to re-authorize the application). Facebook does not currently support refresh tokens. Moreover, Facebook access tokens expire after about 2 hours. So, to avoid having to ask your users to re-authorize ever 2 hours, the best way to keep a long-lived access token is to request "offline_access".

When asking for "publish_stream,offline_access" authorization, the user will be prompted with the following authorization page from Facebook:

Scope values are provider-specific, so check with the service provider's documentation for the available scopes. Facebook scopes are documented at http://developers.facebook.com/docs/authentication/permissions.

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

In the course of creating a connection with a service provider, you may want to inject additional functionality into the connection flow. For instance, perhaps you'd like to automatically post a tweet to a user's Twitter timeline immediately upon creating the connection.

ConnectController may be configured with one or more connection interceptors that it will call at points in the connection flow. These interceptors are defined by the ConnectInterceptor interface:

public interface ConnectInterceptor<S> {

    void preConnect(ServiceProvider<S> provider, WebRequest request);

    void postConnect(ServiceProvider<S> provider, ServiceProviderConnection<S> connection, WebRequest request);
}
		

The preConnect() method will be called by ConnectController just before redirecting the browser to the provider's authorization page. postConnect() will be called immediately after a connection has been established between the member account and the provider profile.

For example, suppose that after a connection is made, you want to immediately tweet that connection to the user's Twitter timeline. To accomplish that, you might write the following connection interceptor:

package org.springframework.social.showcase.twitter;
import org.springframework.social.connect.ServiceProvider;
import org.springframework.social.connect.ServiceProviderConnection;
import org.springframework.social.twitter.DuplicateTweetException;
import org.springframework.social.twitter.TwitterOperations;
import org.springframework.social.web.connect.ConnectInterceptor;
import org.springframework.util.StringUtils;
import org.springframework.web.context.request.WebRequest;

public class TweetAfterConnectInterceptor implements ConnectInterceptor<TwitterOperations> {

    public void preConnect(ServiceProvider<TwitterOperations> provider, WebRequest request) {
        // nothing to do
    }

    public void postConnect(ServiceProvider<TwitterOperations> provider, ServiceProviderConnection<TwitterOperations> connection, WebRequest request) {
        connection.getServiceApi().updateStatus("I've connected with the Spring Social Showcase!");
    }

}
		

This interceptor can then be injected into ConnectController when it is created:

@Bean
public ConnectController connectController(@Value("${application.url}") String applicationUrl) {
    ConnectController controller = new ConnectController(applicationUrl);
    controller.addInterceptor(new TweetAfterConnectInterceptor());
    return controller;
}
		

Or, as configured in XML:

<bean class="org.springframework.social.web.connect.ConnectController">
    <constructor-arg value="http://localhost:8080/myapplication" />
    <property name="interceptors">
        <list>
            <bean class="org.springframework.social.showcase.twitter.TweetAfterConnectInterceptor" />
        </list>
    </property>
</bean>
		

Note that the interceptors property is a list and can take as many interceptors as you'd like to wire into it. When it comes time for ConnectController to call into the interceptors, it will only invoke the interceptor methods for those interceptors accept service operations type matching the service provider's operations type. In the example given here, only connections made through a service provider whose operation type is TwitterOperations will trigger the interceptor's methods.