Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 76 Next »

Version status: 0.1.0 beta


Check out the federatedaccounts demo

0.1.0 introduced a new, modularized architecture with facebook and twitter modules

0.1.1 (to be released) will have OpenId realm with multiple authentication providers

0.0.x versions will not be maintained, please upgrade. 0.1.x is mostly (some component were renamed) backwards compatible unless you've made customizations. There's no need to explicitly contribute the realms anymore, just add the desired modules to the classpath.


Tynamo-federatedaccounts is an add-on to tapestry-security module and provides an API and components for federated authentication use cases, i.e. authenticating (your application) users with a third-party, such as Facebook, Twitter or Google. The most well-known protocol for it is probably Oauth. However, the module is purposefully not named as "tynamo-oauth" or similar, since the provided interfaces are designed for any federated accounts (where you need to "bridge" more than one account together), regardless of protocol. Besides Oauth, OpenID, LDAP and custom remote authentication protocols are obvious use cases. The module provides an authenticating realm for each specific third-party and required components and pages to authenticate via a particular federated authentication scheme. The module is designed to be as light-weight and non-invasive as possible with minimal amount of configuration required. For example, for enabling simple authentication with Facebook and Twitter in your (Hibernate-based web) application, you only need to provide the following configuration:

It is not strictly mandatory but you should also explicitly configure your application's hostname instead of relying on the hostname taken from request. This is required anyway if you are creating absolute urls without request context (for example in a background process) or when you are running loadbalancers in front of your application server. Oauth provider's callback URL handler may require that hostname matches with the provider's configuration (that's exactly the case with Facebook). Pre-T5.3 you have to override BaseUrlSource, in T5.3 you can simply set the following symbols:

The User class above is your own persistent type, or in the case of Hibernate/JPA, an @Entity. All types you are contributing to FederatedAccountService need to implement the interface FederatedAccount interface is shown below:

Depending on the FederatedAccountService used, you don't necessarily need to provide any meaningful implementation for federate(...) operation, but it's provided in case you want to merge/update some account properties. See the example implementation for ideas (the DefaultHibernateFederatedAccountServiceImpl requires you to implement storing the identifying remote property).

FederatedAccountService is a lightweight interface, providing a bridge between your local user accounts and remote accounts. The only operation in FederatedAccountService is:

The operation is designed to be invoked after a remote authentication has succeeded. "remotePrincipal" parameter is the username/userid in the remote system and the last parameter is an optional object describing the remote account. The current Facebook realm is using RestFB and returns RestFB User object as the remoteAccount. The Twitter realm uses Twitter4j and returns a Twitter4j User as the remoteAccount. DefaultHibernateFederatedAccountServiceImpl tries to obtain the configured entity for this realm (see the configuration above) and saves or updates the entity after calling its federate(...) operation.

FederatedAccounts module requires that FederatedAccountService interface is bound to an existing service, but doesn't bind to any by default. This is so you can easily provide a custom implementation for FederatedAccountService, using your own persistence model.

Configuring realms

The modularized architecture allows each module (and realm) to use their own, provider specific communication library. Each realm can support additional, provider-specific features. For example, you may want to request additional permissions from Facebook users etc. See below for documentation on FacebookRealm.


Want to do more with FB than just authenticate?


The module uses a fabulous little library, RestFB, for communicating with Facebook's Graph API. You are free to use the full power of RestFB and Facebook's Graph API in the rest of your application! Just remember that you need to store the access token for later use (see the Extension points below). The example application at demonstrates application's use of the access token, feel free to browse the source code for the sample app

First, create a Facebook application/register your website (same thing really). If you need to request specific application permissions, contribute an additional permission symbol (in addition to your application credentials), for example:

By default, FacebookRealm will use the Facebook user id as the principal property, i.e. that property is used as the remotePrincipal. You may change it by configuring FacebookRealm.FACEBOOK_PRINCIPAL. Facebook.PrincipalProperty {id, email, name} are the only supported principals. Using email as the principal property may sometimes be valuable for automatically merging existing accounts but remember that you need to explicitly request access to user's email. You can specify name as well, but note that it's not a uniquely identifying property (not even within Facebook), so you likely want to implement your own FederatedAccountService in that case and use composite keys or make the principal otherwise unique.

Workin together with the FacebookRealm is FacebookOauthSignIn component. This component displays the Facebook login icon and initiates the Oauth callflow. The component requires that you've contributed values for "facebook.clientid" and "facebook.clientsecret" to work. Additionally, you may require Facebook specific permissions and decide to manage transactions yourself (set FederatedAccountSymbols.COMMITAFTER_OAUTH to false, true by default). FacebookSignIn also support three different window modes [blank|inline|self] (e.g. windowmode="blank"). The live example well demonstrates these configuration choices.

Tapestry makes it easy!


Oauth is based on callback URIs back to your application. This module automatically adds an Facebook Oauth page as the callback URI, and handles the mechanics of obtaining and verifying the Oauth access key. Even if you've secured access to the rest of your site (with tapestry-security), distributed configuration contributed by this module allows unauthenticated requests to access the callback pages (but only if you do it all in Java!).

Extension points

What should you customize and why?

  • If you are not using hibernate as your persistence framework...
    -> provide a custom FederatedAccountService implementation
  • If you are handling your own transactions...
    -> set autoCommit to false i.e. contribute application symbol configuration.add(HostSymbols.COMMITAFTER_OAUTH,"false")
  • If you are using Hibernate, but need to merge local accounts with remote accounts matching a specific property...
    -> override : DefaultHibernateFederatedAccountServiceImpl.findLocalAccount(Class<?> entityType, String realmName, Object remotePrincipal, Object remoteAccount)
  • If you are adding/updating (i.e. cache) property values from remote account to local account...
    -> implement the required logic in FederatedAccount.federate(String realmName, Object remotePrincipal, Object remoteAccount)
  • If you are not using DefaultHibernateFederatedAccountServiceImpl but need to keep the Oauth access token for later use:
    ->You need to do something like:

    or, store the access token in your database. Note the (potential) expiration of an access token and cast the authenticationToken argument of federate() call in your FederatedAccountService to OauthAccessToken for easier handling.

  • If you are implementing your own remote account provider...
    -> See the current FacebookRealm implementation, FacebookOauth page and FacebookOauthSignIn component and related classes for examples (and contribute back if it's generally useful!)

Check out more examples from our full-featured functional tests or a simple, live demonstration with the default Facebook authentication in action, running on GAE.

Note on GAE


The module currently uses httpclient 4.x which doesn't run on GAE by default. To make it work, the example uses an additional dependency that is under LGPL. The code was taken from ESXX project and repackaged for Tynamo. This additional library is not included by default, you have to explicitly include it in your project if you want to use it and then set configuration.add(FederatedAccountSymbols.HTTPCLIENT_ON_GAE, "true"); in your AppModule. See the example pom.xml for more details.

  • No labels