sinatra-els 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ba66d68fec95409ea3060da53d24672033ed54d8
+  data.tar.gz: 316f7cc35abd3ccc780a3b68622c241e5bb1e7ec
+SHA512:
+  metadata.gz: 3c1507750818d74b9bfd6bbfa26a760d8c4aa9c625fecb7f45e871889f7d21749fb4019c71da38ec0acf6c0cd3b5f6ded728c34255da1d1a14ccc29ceb91ae37
+  data.tar.gz: 8edab93b0fb5d522cf167dab07fbac928fda1bfc2cd7f3d7e69be153624ea885ed6b38ff87950ab9204064025fcfe23023dec1cdd92f26d57083815bea14976e

data/README.md

@@ -0,0 +1,113 @@
+# 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

data/lib/sinatra/els.rb

@@ -0,0 +1,101 @@
+require 'sinatra/base'
+require 'els_token'
+require 'yaml'
+
+
+module Sinatra
+  module ELS  
+    
+    module Auth
+      #
+      # Set up the before hook to use ELS authentication.
+      # Setup ELS options using <i>set :els_opts</i>
+      #
+      #     params:
+      #       opts       -  Optional hash with a key of either :only, or :except
+      #                     and an array of String values which will be cast into
+      #                     regular expressions.
+      #
+      #     example:
+      #       # only use els when patch matches "/api/" or anything ending in "/orders"
+      #       els_before true, :only => ["^\/api\/",".*\/orders$"]
+      #
+      #       # do not use els if the "/util/" path is matched
+      #       els_before true, :except
+      #
+      #       # use els before everything
+      #       els_before
+      #   
+      # when <i>before_all === false</i> all before processing will be ignored
+      #
+      # An optional hash of path matchers can be supplied 
+      #
+      def els_before(opts = {})
+        before {
+          if opts.key? :only
+            # execute authorize if path matches regex(s)
+            if request.path_info.match(/#{opts[:only].map{|i|"(#{i})"}.join('|')}/)
+              authorize!
+            end
+          elsif opts.key? :except
+            # execute authorize if path doesn't match regex(s)
+            if not request.path_info.match(/#{opts[:except].map{|i|"(#{i})"}.join('|')}/)
+              authorize!
+            end
+          else
+            authorize!
+          end
+        }  
+      end
+    end
+    
+    module Helpers
+      
+      #
+      # Perform ELS authentication
+      # Setup ELS options using <i>set :els_opts</i>
+      #
+      def authorize!
+        token = env[settings.els_opts['header']]
+        headers "X-Resource" => request.request_method + " : " + request.url
+        unless token
+          logger.warn("Missing #{settings.els_opts['header']} from IP Address: #{env['REMOTE_ADDR']}")
+          halt 403
+        else
+          unless ElsToken.is_token_valid?(token, settings.els_opts)
+            logger.warn("failed authentication from IP Address: #{env['REMOTE_ADDR']}")
+            halt 403
+          else
+            user = ElsToken.get_identity(token, settings.els_opts)
+            # Ensure user has explicit permission via username or group association
+            skip_user = settings.els_opts['users'].nil?
+            skip_group = settings.els_opts['groups'].nil?
+            user_missing = group_missing = false
+            unless skip_user
+              user_missing = !settings.els_opts['users'].include?(user.name)
+            end
+            unless skip_group
+              group_missing = (settings.els_opts['groups'] & user.roles).empty?
+            end
+            if user_missing and group_missing
+              logger.warn("#{user.name} Does not have permission to use this servce: #{env['REMOTE_ADDR']}")
+              halt 403
+            end
+          end
+        end
+      end
+      
+      # TODO - other interesting els routes
+    end
+    
+    def self.registered(app)
+      app.helpers ELS::Helpers
+      app.register ELS::Auth
+      
+      # When including, set the els_opts hash. eg.
+      #app.set :els_opts, YAML.load_file(File.join(app.settings.root, 'config','els.yml'))[app.settings.environment.to_s]   
+    end
+  end
+
+  register ELS
+end

data/spec/app.rb

@@ -0,0 +1,23 @@
+require 'sinatra/base'
+require 'logger'
+require 'sinatra/els'
+
+class Tester < 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]
+  
+  els_before :only => ["^\/auth"]  
+  
+  get '/no_auth' do
+    "It works!"
+  end
+  
+  get '/auth' do
+    "It works!"
+  end
+  
+end
+

data/spec/app_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'els_token'
+require 'yaml'
+
+describe Tester do
+  include Rack::Test::Methods
+
+  before :all do
+    # obtain a valid els token
+    puts "Please provide a valid user which is contained in the els.yml file"
+    username = gets.chomp
+    puts "Please enter your password"
+    password = STDIN.noecho(&:gets).chomp
+    els = YAML.load_file(File.join(File.dirname(__FILE__),'..', 'config','els.yml'))["test"]
+    @token = ElsToken.authenticate(username,password,els)
+  end
+
+  def app
+    Tester
+  end
+
+  context 'ELS Not Required' do
+    it 'should not return 403' do
+      get '/no_auth'
+      expect(last_response).to be_ok
+    end
+  end
+  
+  context 'ELS Required' do
+    
+    it 'should return 403 with no els token' do
+      get '/auth'
+      expect(last_response.status).to eql(403)
+    end
+    
+    it 'should return 200 with els token' do
+      get '/auth', nil, 'X-API-Key' => "#{@token}"
+      expect(last_response).to be_ok
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+ENV['RACK_ENV'] = 'test'
+
+app_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+$: << File.join(app_root, 'lib')
+
+require 'app'
+require 'rspec'
+require 'rack/test'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: sinatra-els
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Neil Chambers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: els_token
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.4.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.4.4
+description: See README.md
+email: neil.chambers@teamaol.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- lib/sinatra/els.rb
+- README.md
+- spec/app.rb
+- spec/app_spec.rb
+- spec/spec_helper.rb
+homepage: https://stash.ops.aol.com/projects/CIOCODEHAUS/repos/sinatra-els/browse
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --title
+- Sinatra ELS Helper
+- --main
+- README.md
+- --line-numbers
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.1
+signing_key: 
+specification_version: 4
+summary: ELS helper for Sinatra
+test_files:
+- spec/app.rb
+- spec/app_spec.rb
+- spec/spec_helper.rb