This is a quick howto on integrating Oracle SSO with a JRuby on Rails application. The technique used here is the same that's used on Oracle Mix. If you've worked with Ruby on Rails before, you're probably familiar with a few authentication plugins like acts_as_authenticated and restful_authentication. restful_authentication is actually a fork of acts_as_authenticated that focuses on making it more RESTful. We'll be taking the restful_authentication plugin and modifying it to work with Oracle SSO. At some point, it would be great to fork restful_authentication and create a java SSO plugin specifically for JRuby on Rails apps.

These instructions assume basic knowledge of RoR application development and basic knowledge or Oracle SSO.

Overview

The acts_as_authenticated or restful_authentication plugins allow you to authenticate against your database. Those two plugins will create a User and Sessions model that allows you to store your users' profiles and manage your sessions for those users. We will augment this technique to redirect the authentication against an Oracle SSO provider. After you authenticate against an Oracle SSO provider, your app will have access to a bunch of HTTP request headers that you can use to identify the user in your application. On first login, you might also want to cache the user information into your user model. In some circumstances, the information your app receives from the Oracle SSO provider might not be enough. In this case, you might need to make an additional request to another user source, like an LDAP system. This is exactly how we do it on mix.oracle.com -- Oracle SSO passes back the UID (in this case, the users email address), then uses that to make an LDAP bind and search to get more information. We then take the additional information we get from LDAP and cache it to the user model. Any subsequent logins bypass the call to LDAP since we already got everything we need. The Oracle AS doc has a more detailed overview of how all this works.

Step 1: Install the acts_as_authenticated plugin into your RoR app

Follow the instructions listed here ->http://agilewebdevelopment.com/plugins/restful_authentication to install the plugin. After you've done that, use the generator to create the models, controllers, and views required:

script/generate authenticated user sessions

The full instructions are inside the README file in your RAILS_ROOT/vendor/plugins/acts_as_authenticated directory.

Step 2: Edit lib/authenticated_system.rb

At some point, it would probably be better to come up with another plugin that won't require you to edit the lib/authenticated_system.rb file. However, for simplicity, let's go through and show you just exactly what needs to be changed. I've pasted the full source on pastie -> http://pastie.caboo.se/158338 because it's easier to see. Let's go through the sections I've modified...



The access_denied method is triggered whenever a user tries to access a protected resource. By default the restful_authentication plugin will redirect you to the login page (new_sessions_path). Oracle SSO is triggered by an HTTP response header of 499 with a specific message of "Oracle SSO." Since the standard Ruby response method doesn't allow you to set a response message, we had to do it in Java (line 80). You can read more about how these headers work in the mod_osso developers guide.

The code we added in access_denied, will cause mod_osso (the Oracle HTTP Server module responsible for SSO) to redirect the user to the Oracle SSO login page, but after a user logs in, we need to handle the redirect back to our RoR application. For that, we added some code to the logged_in? method. BTW, the Oracle SSO code will only fire if you're running in production. We wanted to the flexibility to bypass Oracle SSO when we're in dev or test.



The logged_in? method gets called by the login_required method. If a resource is protected, the login_required method is called to check if the user is logged_in? and if they're not, access_denied is called. So, when logged_in? is called after a successful Oracle SSO provider login, an HTTP request header is made available to your RoR app via mod_osso. In this case, the header we use is "REMOTE_USER." This is typically the username the user logged in with. If the username isn't a suitable identifier, you have other options you can use as a unique identifier.

Line 9-10 sets the @current_user instance variable. In our case, we check to see if the user exists in our model, if not, we search for the user in the LDAP system, then cache it in our user model. You can tweak this to your liking.

Step 3

There is no step 3! Once you've got the authenticated_system.rb file set up to your liking, all you have to do is run your RoR app under JRuby on OAS. BTW, this howto assumes that you've already created/requested an Oracle SSO partner application configuration and have already set up mod_osso on your Oracle HTTP Server with the proper partner info.