shibboleths_lil_helper 1.0.2 → 1.0.3

data/README.markdown

@@ -10,15 +10,7 @@ Shibboleth's Lil Helper (slh) is a tool that automates the generation of Apache/
 
 * __Providing conceptually simple linear process__ that distills the main steps associated with Shibboleth integration.
 
-* Verifying metadata consistency across sites & hosts associated with
-  particular Shibboletht SP entity_id.
-
-DISCLAIMER
--------------------------
-All you see here on Github is the readme, no code yet.
-
-This is released as a RubyGem right now, we hope to push the source up
-here once things stabilize further
+* __Verifying metadata consistency__ across sites & hosts associated with particular Shibboletht SP entity_id.
 
 Why another tool?
 -----------------
@@ -32,83 +24,152 @@ configuration consistently with minimal manual work for:
   * each running the Apache/IIS Native Service Provider
 
 Installation
-============
-* Pre-requisites:
+------------
+* Pre-requisites
+  * Ruby: http://www.ruby-lang.org/en/downloads/
   * Rubygems: http://rubygems.org/pages/download
 
 * Via Ruby Gems:
-  * gem install shibboleths_lil_helper
+  * `gem install shibboleths_lil_helper`
   * Then type `slh` -- this provides more detailed/actionable
     documentation
 
+* Via Git: (requires bundler gem)
+  * this is how developers/contributors should install the tool
+  * `git clone ...git://thisrepo... slh`
+  * `cd slh`
+  * `bundle install`
+  * then add a symlink to bin/slh (something like below)
+    * `ln -s bin/slh ~/slh`
+  * make sure the slh binary is the right one (not a gem one)
+    * `which slh`
+
+* Install notes:
+  * Tool requires nokogiri gem which in-turn requires libxml2, you may
+    run into difficulties there: See http://nokogiri.org/tutorials/installing_nokogiri.html if you have problems.
+
+Before using this tool
+----------------------
+For each host you want to integrate with Shibboleth, do the following and have answers for the questions below.
+
+__Don't try to use this tool until you have followed these instructions for at least one host.__
+
+For each host:
+
+  * __Install Shibboleth Native Service Provider Apache/IIS__
+    https://wiki.shibboleth.net/confluence/display/SHIB2/Installation
+    Ideally, you should be able to hit a URL like "Shibboleth.ss/Metadata" for each site
+    on the host and have it cough out some XML goo. (not a strict
+requirement, slh will help you with this later too)
+
+  * What web server is it? IIS or Apache
+
+  * If IIS, what is the site ID?  
+    You can find this my clicking "Websites" in IIS and looking at the "Identifier" column for myshinynewwebsite.umn.edu.
+
+  * What is the host name of the computer?  (e.g. somehost.com)
+
+  * What is the site name?  (e.g. myshinynewwebsite.umn.edu)
+
+  * Is authentication required for the entire site or particular directories?
+
+  * Is this URL available for your site?  myshinynewwebsite.umn.edu/Shibboleth.sso/Metadata
+
+  * What is the error support contact email?
+
+  * What is the Service Provider entity ID you'd like to use? 
+    A simple convention is to have a dev entity for "development" or "staging" apps and one for production stuff.
+    You might consider https://YOUR_ORG.umn.edu/shibboleth/dev_default or https://YOUR_ORG.umn.edu/shibboleth/prod_default
+
+
 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.
-* The Shibboleth apache module is loaded globally for all vHosts.
-* You are integrating with a single Identity Provider.
+-----------
+* Each host integrates with a single Identity Provider, not multiple.
+* (for Apache) The Shibboleth apache module is loaded globally for all vHosts.
 
 Concept
-=======
+-------
 
-All configuration and authentication specs for all Shibboleth SP instances are specified in a single ruby parseable "shibboleths_lil_helper/config.rb" file.  From these specs, slh is capable of generating all of the required XML files you will need to integrate with a Shibboleth Identify Provider (Idp).
+All configuration and authentication specs for all Shibboleth SP instances are specified in a single ruby parseable `shibboleths_lil_helper/config.rb` file.  From these specs, slh is capable of generating all of the required XML files you will need to integrate with a Shibboleth Identify Provider (Idp).  The following breaks down the essential steps.
 
-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", "verify_metadata", or "generate_metadata" that perform various tasks.
 
-* It all starts with:
+### Initialization
+It all starts with
 
     mkdir shibboleth_deployer
     cd shibboleth_deployer
     slh initialize
 
-  This creates a config file with example code you'll need to change to work.
+This creates a config file with example code you'll need to change to work.
+
+### SP configuration
+Edit `shibboleths_lil_helper/config.rb` to reflect your setup:
 
-* Go in and edit shibboleths_lil_helper/config.rb to reflect your setup,
-  adding
   * entity id
   * idp metadata url
   * hosts, sites, and paths to protect for each for each site
 
-
-* From here you type:
+From here you type:
 
     slh generate
 
-  which will generate shibboleth2.xml and a couple others
-  Now--you go put these files on the hosts they have been generated for.
+This creates:
+
+  * shibboleth2.xml
+  * idp_metadata.xml
+  * shib_apache.conf (if using apache)
 
-* The generated shibboleth2.xml will have RequestMap specs that restrict
-  access to specified paths you have
+for each host for each entity_id.  shibboleth2.xml contains RequestMap, AssertionConsumer server "endpoints" and other goo needed to integrate with an Shib IDP.
 
+Go deploy these config files to you hosts. (the tool provides more details)
 
-* Once you've copied the shibboleth2.xml up to your target hosts, you
-  can type:
+### Metadata verification
+Verify your metadata data across all hosts:
 
     slh verify_metadata
 
-  which will tell some of the things that are probably incorrect with
-  your setup and how to fix it. (like copying the sp-key.pem and sp-cert.pem keys associated with the :is_key_originator site to all of the other hosts)
+Which will tell some of the things that are probably incorrect with
+  your setup and how to fix it. (like copying the sp-key.pem and sp-cert.pem keys associated with the `:is_key_originator` site to all of the other hosts)
 
-* Then, once verify_metadata is showing all green:
+### Metadata generation
+Once verify_metadata is showing all green:
 
     slh generate_metadata
 
-  which generates a metadata file for each strategy/entity id you have
+which generates a metadata file for each strategy/entity id you have
 that you can give you your IDP.
 
-Real World Example
-==================
-The following describes how we integrate this tool's generated output
-into a deployment automation tool called Capistrano.
+Once the IDP has added your metadata, then each site should be able to
+respond to 
+
+    Shibboleth.sso/Login
+
+and be happily prompted for login.
+
+
+Deployment automation
+---------------------
+Once you have the basic stuff working, you may want to automate
+deployment:
+
+    slh capistrano_deploy
+
+will create a config/deploy.rb
+
+See https://github.com/capistrano/capistrano/wiki/ for more details
 
-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:
+This requires some initial setup per host and only works well if your
+target hosts run SSH (aka default not-IIS setup)
+
+deployment automation example
+-----------------------------
+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
 
+### Initial setup
 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:
+this shibboleth\_deployer repo structured in the standard way:
 
     ls /etc/shibboleth_deployer
         current
@@ -116,33 +177,49 @@ this shibboleth_deployer repo structured in the standard way, e.g:
         shared
 
 Setup symlinks to the appropriate config files within
-shibboleth_deployer from the places the Native Shibboleth SP expects
+shibboleth\_deployer from the places the Native Shibboleth SP expects
 files to be, e.g:
 
-(from the /etc/shibboleth dir)
+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
+from the /etc/httpd/conf.d dir
 
-Additional Docs
-===============
-* See the stuff in /doc in this project
+    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
 
 How to Help
-======================
+-----------
+* Let us know the issues you are having with the tool via Github Issues.
 
-Email Us
+* Improve the documentation!  The whole purpose of this tool is to
+  provide a straight-forward path to setting up a Shibboleth SP.
+
+How to contribute
 ----------------------
-* Let us know you are interested in using the tool.
+* Fork, implement, issue a pull request for small changes.
 
-* Voice your ideas about questions you have and features you'd like to see.
+* Email us for big ideas or API changes--we'd like to keep this tool
+  stable and want to collaborate to identify the right way of
+accommodating new features while maintaining backward compatibility.
 
-Authors
-=======
+Contributors
+------------
 * Joe Goggins, Academic Support Resources, goggins@umn.edu
 * Chris Dinger, Academic Support Resources, ding0057@umn.edu
 
-Copyright (c) 2011 University of Minnesota
+Acknowledgements
+----------------
+Thanks to these folks for providing feedback and willingness to pilot
+the tool.
+
+* David Peterson, Office of Institutional Research
+* Debbie Gillespie, Computer Science and Engineering
+* Eva Young, Office of Institional Compliance
+* Josh Buysse, CLA Office of Information Technology
+* Aaron Zirbes, Environmental Health Sciences
+
+
+Copyright (c) Regents of the University of Minnesota

data/TODOS.txt

@@ -1,7 +1,14 @@
-* Release as gem
+TODOS
+
+
 
 
 DONE
+* Added note in readme: Broke because of libxml2 lacking http://nokogiri.org/tutorials/installing_nokogiri.html
+* after slh generate, tell the user exactly where they should put the files.
+* Blowup gracefully when no protect statements 
+* config.rb.erb: specify what must be specified and what is optional
+* Release as gem
 * 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

data/VERSION

@@ -1 +1 @@
-1.0.2
+1.0.3

data/lib/slh/cli.rb

@@ -107,7 +107,7 @@ OTHER DOCUMENTATION SOURCES (not just this tool)
       when 'verify_metadata'
         klass = [Slh::Cli::FetchMetadata, Slh::Cli::CompareMetadata, Slh::Cli::VerifyMetadataEncryption]
       when 'generate_metadata'
-        klass = [Slh::Cli::FetchMetadata, Slh::Cli::CompareMetadata,Slh::Cli::VerifyMetadataEncryption, Slh::Cli::GenerateMetadata]
+        klass = Slh::Cli::GenerateMetadata
       when "generate_capistrano"
         klass = Slh::Cli::GenerateCapistranoDeploy
       when "copy_templates_to_override"

data/lib/slh/cli/generate.rb

@@ -12,9 +12,23 @@ class Slh::Cli::Generate < Slh::Cli::HostFilterableBase
           FileUtils.mkdir_p(host.config_dir)
           File.open(strategy.config_file_path(cf,host), 'w') {|f| f.write(strategy.generate_config_file_content(cf,host)) }
           Slh::Cli.instance.output "    Wrote #{strategy.config_file_path(cf,host)}"
+          if cf == 'shib_apache.conf'
+            Slh::Cli.instance.output "      copy this into /etc/httpd/conf.d or somewhere apache can read it are target host", :highlight => :green
+          else
+            if host.shib_prefix.nil?
+              Slh::Cli.instance.output "      copy this into /etc/shibboleth for this host on target host", :highlight => :green
+            else
+              Slh::Cli.instance.output "      copy this into #{host.prefixed_filepath_for(cf)} on target host", :highlight => :green
+            end
+          end
         end
       end
+
+      originator_host = strategy.key_originator_site.parent_host
+      Slh::Cli.instance.output "\ncopy sp-key.pem sp-cert.pem from host #{originator_host.name} to ALL target hosts.", :highlight => :green
+      Slh::Cli.instance.output "  This makes the X509Certificate stuff in all metadata for all sites associated with an entity_id match"
     end
+
     Slh::Cli.instance.output "You MUST deploy these files your web servers and restart httpd and shibd for subsequent commands to work", :highlight => true
   end
 end

data/lib/slh/models/site.rb

@@ -28,6 +28,9 @@ class Slh::Models::Site < Slh::Models::Base
     if block_given?
       self.instance_eval(&block)
     end
+    if self.paths.empty?
+      raise "No protect statements for site #{site_name}, you must protect at least 1 path for every site.  Adding a \"protect\" statement should make this error go away"
+    end
   end
 
   def metadata

data/lib/slh/templates/config.rb.erb

@@ -1,40 +1,96 @@
+# ABOUT
+# =====
+# This file is the basis for your shibboleth config for
+# all entities, hosts, sites, and url paths you want to protect for your organization.
+# 
+# All slh commands utilize this file to do its thing.
+#
+# To get started:
+#   * fill in the REQUIRED items
+#   * run slh generate
+#   * deploy the files our to your server to the appropriate place
+#   * fight with your server to get somesite.com/Shibboleth.sso/Metadata spitting out XML
+#     for each host
+#
+# Then:
+#   * run slh verify_metadata
+#   * copy sp-key, sp-cert, etc
+#   * re-run command until you aren't seeing any errors
+# Then:
+#   * run slh generate_metadata
+#   * give the metadata to your IDP folks
+#
+# Verify:
+#   * Goto somesite.com/Shibboleth.sso/Login
+#   * You should be prompted to login
+#
+# A strategy
+#   has one entity
+#   has a metadata url
+#   has many hosts
+#     a host has many sites
+#         a site has many protected paths
+#           a protected path can require auth, optionally use auth, or restrict to a 
+#           particular set of users
+#
 Slh.for_strategy :test_idp do
-  set :sp_entity_id, 'YOUR_ENTITY_ID'
-  set :idp_metadata_url, 'YOUR_IDP_METADATA_URL'
-  set :error_support_contact, 'YOUR_ERROR_SUPPORT_EMAIL_ADDRESS'
+  set :sp_entity_id, 'YOUR_ENTITY_ID'                     # REQUIRED, https://yourorg.umn.edu/shibboleth/default
 
-  for_apache_host 'SOMEHOSTNAME.COM' do
-    # UNCOMMENT THIS IF YOUR SHIB STUFF LIVES IN A NON-STANDARD LOCATION 
-    # set :shib_prefix, '/swadm/etc/shibboleth'
-    for_site 'SOMESITENAME1.COM' do
+  set :idp_metadata_url, 'YOUR_IDP_METADATA_URL'          # REQUIRED, https://idp-test.shib.umn.edu/metadata.xml
+  set :error_support_contact, 'YOUR_ERROR_SUPPORT_EMAIL_ADDRESS' # OPTIONAL
+
+  # Can be either
+  # for_apache_host
+  #   or
+  # for_iis_host
+  for_apache_host 'SOMEHOSTNAME.COM' do                          # REQUIRED
+    # uncomment if your shib stuff lives in a non-standard location
+    # set :shib_prefix, '/swadm/etc/shibboleth'                  # OPTIONAL
+
+    # uncomment if and fill-in if you are using IIS
+    # set :site_id, "YOU_MUST_SET_THE_SITE_ID_HERE"              # REQUIRED if for_iis_host
+    #
+    # replace with the host name of your server
+    for_site 'SOMESITENAME1.COM' do                              # REQUIRED
       # Each strategy must set this for exactly one site
       # its used as the authoritative source to from which all other
       # sites metadata's X509Certificate should match
       # the sp-key.pem and sp-cert.pem files from this host should be
       # copied to all other hosts underneath the strategy
-      #
-      set :is_key_originator, true
-      protect 'SOME_PATH_YOU_WANT_TO_REQUIRE_AUTH'
-    end
-    for_site 'SOMESITENAME2.COM' do
-      protect 'SOME_PATH_YOU_WANT_OPTIONAL_AUTH' do
-        set :flavor, :authentication_optional
+      set :is_key_originator, true                               # REQUIRED, see instructions
+      protect '/' do                                             # REQUIRED
+        # delete this line if you want to require auth for the whole site 
+        set :flavor, :authentication_optional                    # OPTIONAL
+        # There are three "flavors":
+        #   authentication_required: defaults to this if unspecified
+        #     i.e. (no do-end block required)
+        #       protect 'secure'
+        #
+        #   authentication_optional: Makes it possible for
+        #     the app layer to redirect to Shibboleth.sso/Login
+        #     i.e. 
+        #       protect 'lazy_auth' do
+        #         set :flavor, :authentication_optional
+        #       end 
+        #   authentication_required_for_specific_users: Require auth and restrict to
+        #     a particular set of users (not-tested extensively)
+        #     i.e. 
+        #       protect 'specific_users' do
+        #         set :flavor, :authentication_required_for_specific_users
+        #         set :specific_users, %w(SOMEUSER@SOME.DOMAIN.COM ANOTHERUSER@SOME.DOMAIN.COM)
+        #       end 
       end
+      # ... for each protected dir for this site ...
     end
-    for_site 'SOMESITENAME3.COM' do
-      protect 'SOME_PATH_YOU_WANT_TO_RESTRICTED_TO_PARTICULAR_USERS' do
-        set :flavor, :authentication_required_for_specific_users
-        set :specific_users, %w(SOMEUSER@SOME.DOMAIN.COM ANOTHERUSER@SOME.DOMAIN.COM)
-      end
-    end
-  end
-  for_iis_host 'SOMEIISHOSTNAME.COM' do
-    for_site 'SOMEIISSITENAME1.COM' do
-      set :site_id, "YOU_MUST_SET_THE_SITE_ID_HERE"
-      protect 'SOME_PATH_YOU_WANT_TO_REQUIRE_AUTH'
-    end
+    # ... for each site on this host ...
   end
+  # ... for each host within this strategy (using this entity_id)
 end
-Slh.clone_strategy_for_new_idp :test_idp,
-                               :production_idp,
-                               'THE_PRODUCTION_IDP_METADATA_URL'
+# ... for each strategy/aka entity_id ...
+#
+# Uncomment this line if you want to create a new strategy that is identical
+# an existing one but points at a different IDP entity URL
+#
+# Slh.clone_strategy_for_new_idp :test_idp,                            # OPTIONAL
+#                                :production_idp,
+#                                'THE_PRODUCTION_IDP_METADATA_URL'

data/shibboleths_lil_helper.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{shibboleths_lil_helper}
-  s.version = "1.0.2"
+  s.version = "1.0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Joe Goggins"]
-  s.date = %q{2011-11-02}
+  s.date = %q{2011-11-08}
   s.default_executable = %q{slh}
   s.description = %q{See the summary text.}
   s.email = %q{goggins@umn.edu}

data/test/fixtures/dummy1.rb

@@ -2,14 +2,14 @@
 # Slh.define_idp_meta_data :default, 'https://idp-test.shib.umn.edu/metadata.xml'
 # Slh.define_error_support_contact :default, 'goggins@umn.edu'
 #
-Slh.define_strategy :dummy1,
+Slh.for_strategy :dummy1,
   :sp_entity_id => 'https://shib-local-vm1.asr.umn.edu/rhel5_sp1',
   :idp_metadata_url => 'https://idp-test.shib.umn.edu/metadata.xml',
   :error_support_contact => 'goggins@umn.edu' do
   for_host 'shib-local-vm1.asr.umn.edu' do
-    for_app 'https://shib-local-vm1.asr.umn.edu' do
-      protect_location '/secure'
-      protect_location '/lazy', :with => :lazy_authentication
+    for_site 'https://shib-local-vm1.asr.umn.edu' do
+      protect '/secure'
+      protect '/lazy', :flavor => :authentication_optional
     end
   end
 end

data/test/test_shibboleths_lil_helper.rb

@@ -1,17 +1,9 @@
 require 'helper'
 
 class TestShibbolethsLilHelper < Test::Unit::TestCase
-  # should "have a Slh namespace that will contain all classes contained" do
-  #   assert Slh.class == Module
-  # end
-  # should "provides class representing core shibboleth model-ish ideas" do
-  #   assert Slh::Models::App.class == Class
-  #   assert Slh::Models::Host.class == Class
-  #   # TODO add more
-  # end
-  # should "provide some top level methods for using the tool" do
-  #   # TODO add more
-  # end
+  should "have a Slh namespace that will contain all classes contained" do
+    assert Slh.class == Module
+  end
 
   # context "with :dummy1 strategy" do
   #   setup do

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 0
-  - 2
-  version: 1.0.2
+  - 3
+  version: 1.0.3
 platform: ruby
 authors: 
 - Joe Goggins
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-11-02 00:00:00 -05:00
+date: 2011-11-08 00:00:00 -06:00
 default_executable: slh
 dependencies: 
 - !ruby/object:Gem::Dependency