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 [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:
-
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\/" ]
-
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