sinatra-els

Sinatra ELS Helper

This is a Sinatra extension to assist in verification of an ELS (openAM) authentication token.

These tokens are usually stored in a browser cookie to assist in SSO but we can also use them to create Web Services with federated authentication. The caller must first authenticate with ELS to generate a token then pass that token along with a WS call (usually in a HTTP Header)

To find out more about generating a token, see [https://stash.ops.aol.com/projects/CIO_CODEHAUS_PUBLIC/repos/els_token/browse]

Installation

Bung this in your Gemfile

gem 'sinatra-els', '~>1.0.0'

There are two flavors of Sinatra applications, classic and modular. Both need a require statement:

require 'sinatra/els'

That's it for classic apps. Modular apps must register the extension:

class MyApp < Sinatra::Base
  register Sinatra::ELS
end

Usage

There are a couple of ways to use this extension:

1. els_before hook

The els_before hook, without any arguments, will setup a Sinatra before handler for all routes and interrogate for ELS authentication.

the els_before method takes an optional hash which can specify an :only or :except key with an array of strings that represent regaulr expressions (without the enclosing '/' slashes). These will be used to match the route and invoke ELS authentication. As the key names suggest, regular expressions passed to the :only key will only invoke ELS authentication when the current route matches. Converseley, the :except key will be used to ignore ELS authentication for the supplied regex's.

Example 1: Only process ELS authentication on the '/api/' route and any route ending with 'reports'

els_before :only => [ "^\/api\/", "reports$" ]

Example 2: Perform ELS authentication on all routes except '/util/'

els_before :except => [ "^\/util\/" ]

2. authorize!

The authorize! method (used by els_before) can be manually invoked in any route should the els_before hook not be required or if the default behavior of els_before doesn't meet your needs

Example:

get '/myapi' do
  authorize!
  # Code below will be executed if authentication is successful
end

###Environment specific setup

This is just something I have found useful during development and testing. Because the default is to NOT use ELS, it's possible to selectively setup ELS depending on your environment.

Example: Only use the els_before hook in production and uat environments

configure :production, :uat do
  els_before
end 

Configuration

This extension requires a configuration object (as a hash) which will tell it the ELS end point to use, the AD Users and/or AD Groups to allow when performing credential validation and the HTTP header key in which to expect an ELS identity token. For the sake of this example I have stored my config in a .yml file

yml file: /config/els.yml

development:
  uri: https://els-sso.corp.aol.com/opensso/identity
  users:
    - bob
    - alice
  groups:
    - MyApi users
    - Domain Admins
  header: X-API-Key

This must be loaded, under the environment key, to :els_opts.

The following is a full example

app file: /app/my_api.rb_

class MyApi < Sinatra::Base

  set :root, File.expand_path(File.join(File.dirname(__FILE__), '..')) 

  register Sinatra::ELS

  set :els_opts, YAML.load_file(File.join(settings.root, 'config','els.yml'))[settings.environment.to_s]

  configure :production, :uat do
    els_before :except => [ "\/util/" ]
  end
  
  # ELS validation will occur before this route in production and uat
  get '/api/coolness' do
    "Cool! You are allowed to use this"
  end
  
  # ELS validation will NOT occur before this route in any environment
  get '/util/health' do
    "All good, carry on"
  end
  
end