Hub is a Ruby On Rails application with accompanying library gem which manages user accounts for a web site. Its main use is for sites that run more than one Rails application within a single domain. Through integration with the Hub library gem, applications share Hub user details so that a user only has to create one account and log in or out of one place. Without Hub, users have to create and manage individual accounts for individual applications. Hub is therefore a single sign-on mechanism.
Applications require modifications to use Hub. Applications that already have the concept of users and accounts must be modified with some care, because the application’s own account mechanism must be replaced or overlaid with the single sign-on alternative. Applications that have no account mechanism are much simpler to modify. You may wish to add Hub support to such applications so that users must create accounts to perform certain actions, such as posting to a forum or blog that might otherwise be completely open to the public – and therefore completely open to spam.
Hub has three main components. The Hub application handles users creating accounts, logging in and out and managing their account settings, through an ActiveRecord database connection and the library gem. User information stored securely in the database while the gem is used to record details when a user logs in or discard those details when a user logs out. The gem does this by sending objects to or reading objects from the third component, a small distributed Ruby server. Running on Unix domain sockets, the server allows all Hub-integrated Rails applications to share information on a logged in user without needing secondary ActiveRecord connections to the Hub database or any detailed knowledge of Hub’s user account model. Everything is hidden by the Hub library gem API.
Presently, only a version of Hub with views styled for the RISC OS Open web site is available. In future I hope to add a more generic and more easily customised version.
The latest version is available at:
http://www.riscosopen.org/tarballs/svn/hub.tar.bz2
First of all, install the Hub gem using the gem
command in the usual fashion. For example, for version 0.2.5 of the library, change into the directory containing the .gem
file from the unpacked Hub archive and issue the following command:
gem install hubssolib-0.2.5.gem
If you run multiple gem repositories you can instruct gem
to install into a specific location using the --install-dir
command line switch:
gem install hubssolib-0.2.5.gem --install-dir=/home/username/gems
The Hub DRb server consists of a small wrapper Ruby script which does most of its work using the Hub gem. To run the server, you need to first specify a DRb connection URI in the HUB_CONNECTION_URI
environment variable. Usually, this is a Unix domain socket and so lives in a location of your choice in the local filesystem. Run the server by running ruby
on the hub_sso_server.rb
file in the Hub archive. For example:
HUB_CONNECTION_URI="drbunix:/home/username/sockets/hub_drb" export HUB_CONNECTION_URI ruby /home/username/hub/hub_sso_server.rb &
Finally you can install the Hub application using whatever mechanism you prefer to application installation. See ample documentation elsewhere on the Web for information on installing Ruby On Rails applications – Hub itself contains the default rails README file with quite a lot of information in it.
Some configuration is needed using externally set environment variables. These are actually picked up by the Hub gem but you won’t know what values to set until the application, DRb server and gem are all installed.
HUBSSOLIB_DRB_URI
– as already discussed, this must hold a DRb URI giving the connection socket on which the server listens and to which clients connect.HUB_PATH_PREFIX
– sometimes the Hub Gem redirects to various locations within the Hub application. If you have installed the application away from document root, specify the prefix to put onto redirection paths here (otherwise, provide an empty string). For example, when redirecting to the account
controller’s login
method, the path used is HUB_PATH_PREFIX + '/account/login'
.HUBSSOLIB_RND_FILE_PATH
– this is a little unusual. To help encrypt data using an open source mechanism without allowing anyone and everyone to decrypt it, the Hub gem makes some use of an external file containing random data which is read when FCGI or the DRb server processes start. Ideally this should be between 1K and 16K of random data, though in practice any private file of unpredictable data, not exposed to the outside world, would do.Usually, these are set up in a Web server configuration file as part of launching an FCGI process to host the Hub application.
Don’t forget to set up the application’s database.yml
file in the usual fashion. use rake db:migrate
to build the empty database structure.
Visit your application in a Web browser and follow the links to sign up for a new account. To sign up, provide a name that will be displayed to users and a valid e-mail address. A confirmation message is sent to the address, containing a link that must be followed to activate the account. One created, users can log in and out of their accounts (with the possibility of sending a password reset request to their e-mail address in case they forget how to log in) and change their screen names. Users cannot change their recorded e-mail address – instead, they must create a new account under the new address.
As the first user of the Hub application, you test your installation by simply going through the sign-up process. The first account is automatically constructed with administrator privileges. If you are successfully able to visit the signup page, create your account, validate the signup using the confirmation e-mail message and subsequently log in or out of the new account, then Hub is correctly installed :-)
Administrative account users are presented with extra options in the Hub control panel when they log on. You can list currently logged on users, list all users and modify account settings for any user, including deleting their accounts. Accounts have a list of roles associated with them. Roles define whether or not a user has administrative privileges, webmaster privileges and so-on. When you integrate Hub with another application, you define exactly what these roles are because (as described below) you must assign lists of roles required to access protected controller actions.
Accounts can be assigned more than one role. Whether or not you ever want to do this will depend entirely on how you set up the roles required to access various controller actions as you integrate Hub with whichever applications you wish to work under the single sign-on mechanism.
For full integration with Hub, particularly when it comes to showing or hiding things in application views, you need to know some of the Hub programmer interface. This API is described later. First, we need to consider basic application integration issues, mostly revolving around modifying the application controllers.
Applications with no concept of user log-in are easy to integrate with Hub. Applications with only the concept of logging in for administrative purposes are similarly easy, provided your administrators do not mind having to log in using the application’s own administrative mechanisms (so you basically treat the application as if it has no existing user model).
To integrate, add the Hub filters into application.rb
:
# Hub single sign-on support. require 'hub_sso_lib' include HubSsoLib::Core before_filter :hubssolib_beforehand after_filter :hubssolib_afterwards
Within any controller which has actions which you wish to protect with Hub login, define a variable <notextile>
hubssolib_permissions</notextile>
and provide an accessor method for it. I’ll deal with the accessor method first; for a controller called FooController
, add the following to foo_controller.rb
:
def FooController.hubssolib_permissions <notextile>@@hubssolib_permissions</notextile> end
To define the permissions variable you create an instance of HubSsoLib::Permissions
. The constructor is passed a hash. The hash keys are symbolized names of the controller actions you want to protect. The hash values are an array of privileges required to access the action, from a choice of one or more of :admin
, :webmaster
, :privileged
and :normal
. These relate to the roles you can assign to accounts as Hub administrator. For example:
<notextile>@@hubssolib_permissions</notextile> = HubSsoLib::Permissions.new({ :show => [ :admin, :webmaster, :privileged, :normal ], :edit => [ :admin, :webmaster ] })
In this example, any user can access the controller’s show
action but only users with an administrator or webmaster role associated with their account can access the edit
action.
A user’s role(s) must match at least one of the privileges in the array for a given action – so even if your account has an administrator role (and only an administrator role), it won’t be able to access a protected action unless :admin
is included in the array given within the hash to the HubSsoLib::Permissions
constructor. For example:
<notextile>@@hubssolib_permissions</notextile> = HubSsoLib::Permissions.new({ :weblist => [ :webmaster, :privileged ] })
Here, only accounts with the webmaster or privileged role associated can access the weblist
action. If an account has only normal and/or administrative roles, it won’t be allowed through.
If you want to integrate Hub with an application which already has the concept of user accounts, logging in and logging out, there are two main approaches.
before_filter
in the application controller to run special code which you write, which maps a logged in Hub user to an existing application user. If the visitor is logged into Hub and no corresponding local application user account exists, one is created automatically based on the Hub account credentials.Neither approach is problem-free and both require quite a lot of effort and testing. Automated testing is very hard because the modified application’s behaviour depends upon logging in or out of Hub, which is running elsewhere. Unfortunately Rails doesn’t offer a universally supported single sign-on mechanism so applications all use different approaches to user management; this means that there is no magic bullet to integration with Hub. You have to learn and understand the structure of the application being integrated and be prepared to make changes that are potentially quite extensive.
TBD; hubssolib_logged_in? etc.