Spring Social Reference

At very minimum, you’ll need the core module in your application’s classpath:

To let Spring Social handle the back-and-forth authorization handshake between your web application and a service provider, you’ll need the web module:

You’ll probably want to take advantage of Spring Social’s simplified configuration support for XML and/or Java configuration. If so, you’ll need the config module:

If you want to integrate Spring Social with Spring Security to enable users to sign into your application via Facebook, Twitter, or another provider, you’ll need the security module:

Final GA releases of Spring Social will be available in the Maven Central repository. But if you are developing against a milestone or release candidate version, such as 1.1.0.M1 or 1.1.0.RC1, then you will need to add Spring’s milestone repository to your build in order to resolve the artifacts:

Similarly, if you are trying out the latest nightly build version (e.g. 1.1.0.BUILD-SNAPSHOT), you will need to add Spring’s snapshot repository:

At very minimum, you’ll need the core module in your application’s classpath (as a Maven <dependency>):

Or, if you’re using Gradle to build your project:

To let Spring Social handle the back-and-forth authorization handshake between your web application and a service provider, you’ll need the web module:

You’ll probably want to take advantage of Spring Social’s simplified configuration support for XML and/or Java configuration. If so, you’ll need the config module:

If you want to integrate Spring Social with Spring Security to enable users to sign into your application via Facebook, Twitter, or another provider, you’ll need the security module:

Final GA releases of Spring Social will be available in the Maven Central repository. But if you are developing against a milestone or release candidate version, such as 1.1.0.M1 or 1.1.0.RC1, then you will need to add the following repository to your build in order to resolve the artifacts:

Similarly, if you are trying out the latest nightly build version (e.g. 1.1.0.BUILD-SNAPSHOT), you will need to add the following 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 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. In Gradle:

Or in Maven:

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 depends on a few things to run. Most dependencies are optional and an effort has been made to keep the required dependencies to a minimum. The project dependencies are described in this section.

We have created a few sample applications to illustrate the capabilities of Spring Social. To obtain the https://github.com/SpringSource/spring-social-samples code, use the following git command:

The Spring Social Samples project includes the following samples:

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

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:

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 authorization code 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:

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.

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:

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:

Callers are first expected to call fetchNewRequestToken(String) to obtain a temporary token from the service provider 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 Twitter using the OAuth1 server-side flow illustrated above. Here, TwitterConnectionFactory is a subclass of OAuth1ConnectionFactory:

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. In Java configuration, you can configure connection factories by overriding SocialConfigurer's addConnectionFactories() method:

This creates a registry of connection factories that other objects can use to lookup connection factories dynamically. The connection factory registry implements the ConnectionFactoryLocator interface:

Example usage of a ConnectionFactoryLocator is shown below:

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:

For convenience in 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. Note that although this schema was designed with compatibility in mind, it may not be compatible with all databases. You may need to adapt this schema definition to accommodate any peculiarities of your chosen database.

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:

As a convenient alternative to JdbcUsersConnectionRepository and JdbcConnectionRepository, Spring Social also provides InMemoryUsersConnectionRepository and InMemoryConnectionRepository. These in-memory repositories are useful for development-time and testing, but aren’t recommended for production use.

The example code below demonstrates construction and usage of an InMemoryUsersConnectionRepository:

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:

Notice that the three elements in this example come from each provider’s own XML configuration namespace. You’ll need Spring Social’s Facebook. Twitter, and LinkedIn modules in your classpath to make use of these configuration elements.

Spring Social’s own configuration namespace offers support for configuring a JdbcConnectionRepository like this:

The <social:jdbc-connection-repository/> element defaults to use a DataSource bean whose ID is "dataSource". If you’ve configured your DataSource bean with a different ID, you’ll need to explicitly set that:

The <social:jdbc-connection-repository/> also defaults to use a TextEncryptor bean whose ID is "textEnryptor" and a UserIdSource bean whose ID is "userIdSource". If you’ve given those beans different IDs, then you’ll need to explicitly set those as well:

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:

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:

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:

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:

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:

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.

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 to the authorization URL. In the case of Facebook, that means that the Facebook authorization URL pattern should be as follows:

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:

The hidden "scope" field contains the scope values to be passed along in the scope> parameter 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.

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.

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

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 Connection`s returned by the provider's `getConnections() method.

SocialAuthenticationFilter reacts to requests whose path fits a pattern of "/auth/{providerid}". Therefore, to initiate a provider sign-in flow via SocialAuthenticationFilter, you can simply provide a link to "/auth/{providerid}" on a web page. For example, consider the following excerpt from a Thymeleaf template:

This HTML results in 3 links, one each for Twitter, Facebook, and LinkedIn. When the user clicks on the Twitter link, the browser will navigate to a URL whose path is "/auth/twitter". SocialAuthenticationFilter will intercept that request and initiate an authentication flow with Twitter by redirecting the browser to Twitter’s authentication page:

Of course, for SocialAuthentication to work, you must have configured a ConnectionFactory implementation corresponding to the provider (e.g., TwitterConnectionFactory).

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:

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 Signing up with a sign up form).

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:

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:

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:

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

Or to set the sign up URL using XML configuration:

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:

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:

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#doPostSignUp(). For example, the following method handles the sign up form submission, creates an account and then calls ProviderSignInUtils#doPostSignUp() to complete the connection:

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:

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:

If there is any problem in creating the new user implicitly (for example, if the implicitly chosen username is already taken) execute() may return null to indicate that the user could not be created implicitly. This will ultimately result in ProviderSignInController redirecting the user to the signup page.

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

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:

DirectMessageOperations, for example, contains API bindings to Twitter’s "direct_messages" resource:

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:

For OAuth2, only the access token should be required:

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:

An OAuth2 example:

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

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:

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.

We recommend that you use Spring’s REST client testing support, including MockRestServiceServer to test your API bindings.

First create an instance of MockRestServiceServer against the RestTemplate instance used by your API implementation:

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

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

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:

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:

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

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:

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

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

Consult the JavaDoc API of the various service provider types for more information and subclassing options.

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:

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:

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

If you look at the implementation you are using, it probably has a core template, like GitHubTemplate. But what if it doesn’t have the operation you are looking for? You can either wait for the team to develop it, or write it yourself.

To write your own extension, simply extend the core class and add your own implementation:

This fragment extends Spring Social GitHub’s GitHubTemplate. It adds a new method, findAllRepositories. By extending the core template, you are granted access to an already-connected RestTemplate via getRestTemplate(). You have to assemble the URI yourself, but online documentation from the provider puts the power in your hands.

By design, Spring Social uses an embedded RestTemplate to do the legwork of interacting with the provider. That way, if you are using more than one Spring Social project, each one’s individual instance won’t collide with other. As a side effect, it may seem hard to apply something like caching. It’s not.

Spring Social’s AbstractOAuth2ApiBinding, the root of all OAuth2-based provider templates, provides a hook ot post process the RestTemplate when it gets created.

In this example, the code extends GitHubTemplate and then overrides sthe postProcess() method. In Spring Social core, the restTemplate is simply passed through during creation and nothing is changed. In this example, the code creates an AspectJ proxy, adds some RestTemplateAspect advice, sets the factory to proxy the class and not its interface, and then returns back a proxy.

You can already do things like wrap GitHubTemplate operations with caching. This hook enables you to apply any type of advice directly to the RestTemplate.