shibboleths_lil_helper 1.0.0

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+gem "activesupport", "~> 3.0.9"
+gem "nokogiri"
+gem 'i18n' # Required to make require 'active_support/all' work...
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.4"
+  gem "rcov", ">= 0"
+  gem 'ruby-debug'
+end

data/Gemfile.lock

@@ -0,0 +1,36 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.0.9)
+    columnize (0.3.4)
+    git (1.2.5)
+    i18n (0.6.0)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    linecache (0.46)
+      rbx-require-relative (> 0.0.4)
+    nokogiri (1.5.0)
+    rake (0.9.2)
+    rbx-require-relative (0.0.5)
+    rcov (0.9.10)
+    ruby-debug (0.10.4)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.4.0)
+    ruby-debug-base (0.10.4)
+      linecache (>= 0.3)
+    shoulda (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 3.0.9)
+  bundler (~> 1.0.0)
+  i18n
+  jeweler (~> 1.6.4)
+  nokogiri
+  rcov
+  ruby-debug
+  shoulda

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 University of Minnesota
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,199 @@
+About
+=====
+Shibboleth's Lil Helper is a tool that automates the generation of Apache/IIS Shibboleth Native Service Provider configuration & metadata files.  It provides several benefits over manually configuring each NativeSp instance/server by:
+
+* __Providing a consistent configuration approach__ you can apply uniformly across all of the servers managed by your organization.
+  * Makes deployment automation possible, errors less frequent, and troubleshooting easier.
+
+* __Dividing high level auth specs from actual NativeSp configuration__
+  * Programmers can focus on high level goals like "protect files underneath the '/secure' directory on 'somewebsite.com'" rather than grappeling with the bewildering complexity of the NativeSp's interrelated XML files, the Shibboleth protocal, SAML, etc.  
+
+* __Providing conceptually simple linear process__ that distills the main steps associated with Shibboleth integration.
+
+IMPORTANT NOTE/DISCLAIMER
+-------------------------
+All you see here on Github is the readme, no code yet.
+For that to happen two things need to occur:
+
+* We need to battle-test the (working) code across our entire
+  infrastructure and fix bugs before releasing.
+
+* Someone from the IDM team within OIT needs approve that our approach
+  is solid and endorse its usage for the U of M.
+
+**The current status as of October 6th, 2011**
+
+* We have it working in PHP, .NET, and Rails on 2 servers and 4 vhosts for Apache and IIS.
+
+* Assuming no snags (cause that never happens in software, :)), we
+anticipate 90% of our infrastructure migrated by Nov 1st.  At which
+point we hope to release this code into the wild.  And perhaps do a demo
+session at a Code-People meeting.
+
+Why another tool?
+-----------------
+We needed something that could help manage shibboleth SP
+configuration consistently with minimal manual work for:
+
+* Many web servers
+  * each running iis6, iis7, or Apache 2.2
+  * each hosting many vhosts (aka sites)
+  * each running PHP, Rails 2 + 3, classic ASP, or .NET
+  * each running the Apache/IIS Native Service Provider
+
+Installation
+============
+* Pre-requisites:
+  * Rubygems: http://rubygems.org/pages/download
+  * Bundler: gem install bundler
+  
+* From github:
+
+      git clone git://github.com/joegoggins/shibboleths_lil_helper.git
+      cd shibboleths_lil_helper
+      bundle
+      ./bin/slh
+      (then follow instructions)
+
+* Via Ruby Gems: Not working yet
+
+Assumptions
+===========
+* Shibboleth Native Service Provider Apache/IIS is already installed on your target web servers.
+* The X509Certificate (sp-cert.pem, sp-key.pem) keys are in their default locations along-side shibboleth2.xml.  This tool does not help you generate these keys, that's up to you.  The default installation of Native Shib generates keys for you though.
+* The Shibboleth apache module is loaded globally for all vHosts
+* /bin/slh is in your $PATH (automatically done with Rubygem install
+  method, manual is git cloned
+
+Concept
+=======
+
+Auth specs are stated in your shibboleths_lil_helper/config.rb
+via an easily readable ruby parseable domain specific language.  From these specs, Shibboleth's Lil Helper is capable of generating all of the required XML files you will need to integrate with
+a Shibboleth Identify Provider (Idp).
+
+The generation of these XML files happens through a command line tool
+called "slh".  Each particular task is broken into sub-commands such as
+"initialize", "generate", or "metadata" that perform various tasks.
+
+For example, given the following shibboleths_lil_helper/config.rb:
+
+    Slh.for_strategy :umn_apache_shib_test_server do
+      set :sp_entity_id, 'https://asr.umn.edu/shibboleth/default'
+      set :idp_metadata_url, 'https://idp-test.shib.umn.edu/metadata.xml'
+      set :error_support_contact, 'goggins@umn.edu'
+      for_host 'asr-web-dev4.oit.umn.edu' do
+        for_site 'shib-php-test.asr.umn.edu' do
+          protect 'secure'
+        end
+        for_site 'shib-rails2-test.asr.umn.edu' do
+          protect 'secure'
+        end
+      end
+    end
+
+an invocation of
+
+    `slh generate`
+
+will produce the a dir structure and various config files
+associated with these specifications for each strategy, host, and site.
+
+    shibboleths_lil_helper/
+      generated/
+        <strategy>/               (apache_shib_test_server)
+          <hostname>/             (asr-web-dev4.oit.umn.edu)
+            idp_metadata.xml
+            shib_apache.conf
+            shibboleth2.xml
+            sp_metadata_for_host_to_give_to_idp.xml 
+            <site>/               (shib-php-test.asr.umn.edu)
+              fetched_metadata.xml
+
+
+* The generated shibboleth2.xml will have RequestMap specs that restrict
+  access to the "/secure" path for the specified vhosts.
+
+* These generated files should be checked into a source control repository.
+
+The core assumptions of the specifications DSL are
+
+* a strategy ("for_strategy")
+  * has one IDP entity id (:idp_metadata_url)
+  * has one service provider entity id (:sp_entity_id)
+  * has many hosts
+* a host (for_host)
+  * has many sites 
+* a site (for_site)
+  * has many site paths that have various auth rules
+* a site path (protect)
+  * has a "flavor" such as the following specified like
+    *protect "optional_auth", :flavor => :authentication_optional*
+    * authentication_required
+    * authentication_optional
+    * authentication_required_for_specific_users
+
+
+Usage
+=====
+* Type `slh`, you will see instructions for each sub-command and how
+  to get additional information about them.  In general the process is
+  * [initialize] initialize a shibboleths_lil_helper/config.rb
+  * [in your editor] tweak shibboleths_lil_helper/config.rb to reflect the servers you
+    will be using shibboleth with
+  * [generate] generate shibboleth2.xml, shib_apach.conf
+    config files
+  * [a deployment tool or manually] deploy these files out to each host (ideally using a deployment automation tool such as Capistrano)
+  * [metadata] generate metadata: creates and combines SP Metadata from all
+    of the Shib servers into a file(s) you can share with your IDP.
+  * [email] send the generated meta data to your IDP
+
+Real World Example
+==================
+The following describes how we integrate this tool's generated output
+into a deployment automation tool called Capistrano.
+
+We have a private repo called shibboleth_deployer that includes the shibboleths_lil_helper generated config files and uses Capistrano to push these files out target servers and restarts shibd and httpd.  It's usage looks like:
+
+    cap deploy HOST=asr-web-dev4.oit.umn.edu
+
+For each of our target servers we setup Capistrano to have a clone of
+this shibboleth_deployer repo structured in the standard way, e.g:
+
+    ls /etc/shibboleth_deployer
+        current
+        releases
+        shared
+
+Setup symlinks to the appropriate config files within
+shibboleth_deployer from the places the Native Shibboleth SP expects
+files to be, e.g:
+
+(from the /etc/shibboleth dir)
+    ln -s /etc/shibboleth_deployer/current/shibboleths_lil_helper/generated/apache_shib_test_server/asr-web-dev4.oit.umn.edu/shibboleth2.xml shibboleth2.xml
+
+    ln -s /etc/shibboleth_deployer/current/shibboleths_lil_helper/generated/apache_shib_test_server/asr-web-dev4.oit.umn.edu/idp_metadata.xml idp_metadata.xml
+
+(from the /etc/httpd/conf.d dir)
+    ln -s /etc/shibboleth_deployer/current/shibboleths_lil_helper/generated/apache_shib_test_server/asr-web-dev4.oit.umn.edu/shib_apache.conf shib_apache.conf
+
+Additional Docs
+===============
+* doc/nuances.markdown
+* doc/for_slh_developers.markdown
+
+How to Help
+======================
+
+Email Us
+----------------------
+* Let us know you are interested in using the tool.
+
+* Voice you ideas about questions you have and features you'd like to see.
+
+Authors
+=======
+* Joe Goggins, Academic Support Resources, goggins@umn.edu
+* Chris Dinger, Academic Support Resources, ding0057@umn.edu
+
+Copyright (c) 2011 University of Minnesota

data/Rakefile

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "shibboleths_lil_helper"
+  gem.homepage = "http://github.com/joegoggins/shibboleths_lil_helper"
+  gem.license = "MIT"
+  gem.summary = %Q{A ruby gem to streamline the setup, deployment, and ongoing management of Apache & IIS web-servers running the Shibboleth Native Service Provider implementations.}
+  gem.description = %Q{See the summary text.}
+  gem.email = "goggins@umn.edu"
+  gem.authors = ["Joe Goggins"]
+  gem.executables = 'slh'
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "shibboleths_lil_helper #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODOS.txt

@@ -0,0 +1,15 @@
+* Release as gem
+
+
+DONE
+* Incorporate FAQ stuff somehow https://www.pivotaltracker.com/story/show/19256223
+* Add something that warns LOUDLY to use slh with source control
+* Rejigger the default config.rb.erb--simplify and reference documentation
+  >>> Add is_key_originator
+* Separate metadata and make a verify_metadata command
+* verify is_key_originator has been specified somewhere after a strategy
+  has been declared
+* Eliminate *args from all DSL models, it allows you to mis-used the tool easily (i did) with /protect
+* Revert to host level sp metadata instead of all in one
+* Put comments in the generated output that specify the documentation associated with it
+  For example, above SPSSO: http://www.schemacentral.com/sc/ulex20/e-md_SPSSODescriptor.html

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/slh

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# This load path thingy
+# for testing executables in gems
+# http://blakesmith.github.com/2010/06/26/gem-executables-loading-the-relative-path.html
+this_files_path = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__
+$LOAD_PATH.unshift File.join(File.dirname(this_files_path), *%w[.. lib])
+require 'rubygems'
+require 'shibboleths_lil_helper'
+Slh::Cli.execute

data/doc/debugging_shibboleth.markdown

@@ -0,0 +1,8 @@
+---
+Check the syntax of you shibboleth2.xml
+  /usr/sbin/shibd -tc /swadm/etc/shibboleth/shibboleth2.xml
+
+---
+you MUST MUST MUST turn this on in your apache conf:
+UseCanonicalName On
+

data/doc/deprecated_code_that_could_be_useful.rb

@@ -0,0 +1,32 @@
+  # From Slh::Models::Site
+  # These nodes are extracted to create .metadata_site_specific_xml
+  # and removed to create metadata_non_site_specific_nokogiri
+  # which is used in Host to put the site specific crap below 1 instance of the non specific crap
+  # so you can give your IDP one metadata file
+  #
+  # def self.metadata_site_specific_xpaths
+  #   ['//md:ArtifactResolutionService', '//md:SingleLogoutService','//md:AssertionConsumerService']
+  # end
+
+  # def metadata_site_specific_xml
+  #   if @metadata_site_specific_xml.blank?
+  #     @metadata_site_specific_xml = ''
+  #     self.class.metadata_site_specific_xpaths.each do |xpath|
+  #       @metadata_site_specific_xml << self.metadata_nokogiri.xpath(xpath).to_a.join("\n")
+  #       @metadata_site_specific_xml << "\n"
+  #     end
+  #   end
+  #   @metadata_site_specific_xml
+  # end
+
+  # def metadata_non_site_specific_nokogiri
+  #   if @metadata_non_site_specific_nokogiri.blank?
+  #     @metadata_non_site_specific_nokogiri = self.metadata_nokogiri.clone
+  #     self.class.metadata_site_specific_xpaths.each do |xpath|
+  #       @metadata_non_site_specific_nokogiri.xpath(xpath).remove
+  #     end
+  #   end
+  #   @metadata_non_site_specific_nokogiri
+  # end
+
+

data/doc/for_slh_developers.markdown

@@ -0,0 +1,38 @@
+---
+Find the version of shibboleth you are currently running on a host
+  rpm -qi shibboleth
+
+FOR SHIBBOLETHS_LIL_HELPER DEVELOPERS
+---
+If you want to inspect what is happening ANYWHERE in the code (including
+ERB templates in <% %> tags)
+Put
+  debugger
+anywhere in the code, and run:
+  rdebug slh <SOME_COMMAND>
+
+An interactive Ruby shell will pop up and you can hit
+  e <THE_NAME_OF_THE_VAR>
+
+
+---
+Assuming
+  * you are in the root dir of a git clone of shibboleths_lil_helper
+  * you have already run initialize and therefore have a
+    "shibboleths_lil_helper" sub-dir within the 
+     shibboleths_lil_helper repo
+
+You can get at an irb session loaded with your config stuff like this:
+  rake console
+
+  # then once in console
+  require 'shibboleths_lil_helper'
+  Slh.load_config 
+
+  # Then tinker with config stuff stemming from
+  Slh.strategies
+
+DEV_WISH_LIST: `rake console` should do all of these things for you, I
+think this will involve looking at jeweler's "console" rake task and
+figuring out how to add files to load and ruby to run before entering
+the irb session