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