User Authentication

User authentication

Blacklight is bundled with the Authlogic ruby authentication library. By default, only a small handful of the extensive feature set is enabled.

Extending the User model

Customizing Authentication

The default AuthLogic authentication is a username and password against the database.

One way to customize this behavior, for instance to support some kind of enterprise Single-Sign On, is to over-ride certain methods in the UserSessionsController. (See "overriding controllers" in CUSTOMIZING).

• UserSessionsController#new
  • displays login form. Instead of over-riding the whole action (which doesn't do much), you can also just over-ride the app/views/user_sessions/new.html.erb template, or the _login_form.html.erb template.
• UserSessionsController#create
  • login form POSTs here on submit.
• UserSessionsController#destroy
  • called on logout action

A note on referer redirection

The built-in simple authentication flow described below can be used to present a login form if a user tries to access a protected action without being logged in. After the user has succesfully logged in, they are redirected back to where they came from, the protected action.

This redirection url is calculated by UserSessionsController#post_auth_redirect_url. It's initially taken from the HTTP referer header, but since the authentication process generally involves multiple actions (at least presentation and then submission of a login form), the original referer needs to be preserved. That's done by making sure to include a query parameter 'referer' with the original referer on every intermediate request.

If you customize the login process, you need to make sure to preserve that params['referer'] with every click too, if you want the redirection to work.

[Note also that when linking directly to /login action, you can choose to supply your own ?referer=url query parameter to request the user is returned to a specific url when complete. The built-in logic will only honor this request if the supplied referer is internal to the app. ]

Authorization integration

Blacklight defines a very primitive access control mechanism, used primarily to redirect users to the login page as needed. It user the Rails #rescue_from exception handler.

To add basic authorization handling within a controller, it may be easiest to add a before_filter that implements the necessary authorization logic, e.g.:

class UsersController < ApplicationController
  before_filter :verify_user, :only => :show # can't show without a logged in user
  [...]
  protected
  def verify_user
    flash[:notice] = "Please log in to view your profile." and raise Blacklight::Exceptions::AccessDenied  unless current_user
  end
end

The authorization method raises the Blacklight::Exceptions::AccessDenied exception. The ApplicationController uses rescue_from to handle this exception using the controller's #access_denied method. By default, #access_denied redirects the user to the login form, with the current request persisted as a request parameter:

class ApplicationController < ActionController::Base
  rescue_from Blacklight::Exceptions::AccessDenied, :with => :access_denied
  [...]
  def access_denied
    redirect_to root_url and flash.discard and return if request.referer =~ Regexp.new("#{request.request_uri}$")
    redirect_to login_url(:referer => request.request_uri)
  end
end

This behavior can be customized globally using by modifying the local ApplicationController, or within specific controllers by adding either a controller-specific rescue_from handler or #access_denied method.

SSO integration

customizing #post_auth_redirect_url behavior