shibboleths_lil_helper 1.0.0

data/doc/nuances.markdown

@@ -0,0 +1,13 @@
+Nuances
+=======
+
+Order matters with "for_site" (sort of)
+---------------------------
+* When running 'slh metadata', the first site declared under "for_host"
+  (in shibboleths_lil_helper/config.rb), is used when as the remote target to hit /Shibboleth.sso/Metadata.
+  This true anywhere a remote request is needed to be made for one of
+your hosts
+
+  Therefore, if the first site is broken but others are not--switching the order so the first one works will
+  make the metadata comparing work.
+

data/doc/technical_question_and_answer.markdown

@@ -0,0 +1,85 @@
+This document is both for Shibboleth's Lil Helper developers and folks
+setting up the Shibboleth SP.  It was created to simply catelog the many
+different gotchas that were solved while building this tool
+
+---
+QUESTION
+How can I learn how Shibboleth actually works from end to end in
+less than an hour?
+
+ANSWER
+http://www.switch.ch/aai/demo/index.html
+
+---
+QUESTION
+	If you are at 
+	  https://shib-php-test.asr.umn.edu/secure
+	  and goto
+	  https://shib-php-test.asr.umn.edu/Shibboleth.sso/Login
+	  it redirects to
+	  https://shib-php-test.asr.umn.edu
+	How to make it redirect to /secure?
+
+ANSWER
+  See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessionCreationParameters
+  Goto 
+https://shib-php-test.asr.umn.edu/Shibboleth.sso/Login?target=https%3A%2F%2Fshib-php-test.asr.umn.edu%2Fsecure
+
+---
+QUESTION
+  How do I logout and redirect to the current page
+If you are on 
+  https://shib-php-test.asr.umn.edu/secure
+and want to log out and redirect back to this same apge
+
+ANSWER
+  See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLogoutInitiator
+  You go to this page:
+    https://shib-rails2-test.asr.umn.edu/Shibboleth.sso/Logout?return=https%3A%2F%2Fshib-php-test.asr.umn.edu%2Fsecure
+
+
+---
+QUESTION
+Where is the specs and examples on how to do setup the RequestMap correctly?
+https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHowTo
+https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapPath
+https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapPathRegex
+
+
+QUESTION:
+Where is the XML specs for what constitutes valid Metadata?
+ANSWER
+http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf
+You can also find specification details at schemacentral.com (e.g.
+http://www.schemacentral.com/sc/ulex20/e-md_SPSSODescriptor.html)
+
+QUESTION
+
+If HTTP headers are an issue in Apache, why aren't they in IIS?
+
+ANSWER
+
+It seems like the ONLY way to use the Native SP with IIS is HTTP headers.
+
+TODO.
+
+
+---
+Question
+I've have apache and shib installed and configured for a particular IDP and out on a target server, and when I go to Shibboleth.sso/Login, I get "shibsp::ConfigurationException", whats wrong?
+
+Answer:
+One likely issue is that one of the files  referenced from shibboleth2.xml (i.e. attribute-map.xml), does not exist OR is not referenced as an absolute path in the case where shibboleth is not installed at the default location of /etc/shibboleth.
+
+
+QUESTION:
+When I hit something.com/Shibboleth.sso/Metadata on IIS I get:
+Shibboleth Error
+Shibboleth Extension not configured for web site (check ISAPI mappings in SP configuration).
+
+how do I fix this?
+ANSWER:
+
+You probably just need to restart IIS and shibd.
+but you should also check this out:
+https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPWindowsIIS7Installer

data/lib/shibboleths_lil_helper.rb

@@ -0,0 +1,9 @@
+require 'active_support/all'
+require 'securerandom' # part of the Ruby standard library
+require 'erb'
+require 'net/http'
+require 'net/https'
+require 'nokogiri' # XML Parser Gem sudo gem install nokogiri
+require 'fileutils'
+require 'optparse'
+require 'slh'

data/lib/slh.rb

@@ -0,0 +1,17 @@
+module Slh
+#  PROJECT_URL = 'https://github.com/joegoggins/shibboleths_lil_helper'
+  extend ActiveSupport::Autoload
+  autoload :ClassMethods
+  extend Slh::ClassMethods
+
+  autoload :Cli
+  module Models
+    extend ActiveSupport::Autoload
+    autoload :Base
+    autoload :Strategy
+    autoload :Host
+    autoload :Site
+    autoload :SitePath
+    autoload :Version
+  end
+end

data/lib/slh/class_methods.rb

@@ -0,0 +1,83 @@
+module Slh::ClassMethods
+  @@strategies = []
+  def strategies; @@strategies; end
+
+
+  ##########################
+  # CORE API METHODS BEGIN #
+  ##########################
+  def for_strategy(strategy_sym, &block)
+    @@strategies << Slh::Models::Strategy.new(strategy_sym, &block)
+  end
+
+  def clone_strategy_for_new_idp(existing_s, new_s, new_idp_url)
+    existing_strategy = self.strategies.detect {|x| x.name == existing_s}
+    raise "The specified strategy, #{existing_s}, does not exist" if existing_strategy.nil?
+    raise "The new strategy,#{new_s}, already exists" if self.strategies.detect {|x| x.name == new_s}
+    new_strategy = existing_strategy.clone
+    new_strategy.idp_metadata_url = new_idp_url
+    new_strategy.instance_variable_set(:@name, new_s)
+    @@strategies << new_strategy
+  end
+  ########################
+  # CORE API METHODS END #
+  ########################
+
+  def config_dir
+    'shibboleths_lil_helper'
+  end
+
+  def config_file
+    File.join self.config_dir,'config.rb'
+  end
+
+  @@is_loaded = false
+  def load_config
+    unless @@is_loaded
+      Slh.command_line_output "Loading #{Slh.config_file}"
+      begin
+        require Slh.config_file
+      rescue LoadError
+        Slh.command_line_output "No #{Slh.config_file} found, exiting...Are you sure you are running this command from the right working directory?",
+          :highlight => :red,
+          :exit => true
+      end
+      if Slh.strategies.empty?
+        Slh.command_line_output "No strategies found in #{Slh.config_file}, you should add some, exiting...",
+          :highlight => :red,
+          :exit => true
+      end
+      Slh.strategies.each do |strategy|
+        begin
+          strategy.key_originator_site
+        rescue Slh::Models::Strategy::KeyOriginatorNotSpecified => e
+          Slh.command_line_output "Strategy: #{strategy.name} DOES NOT specify 'set :is_key_originator, true' on any site--all strategies must.",
+            :highlight => :red,
+            :exit => true
+        end
+      end
+      @@is_loaded = true
+    end
+  end
+  def command_line_output(msg,*args)
+    options = args.extract_options!
+    s=msg
+    unless options[:highlight].blank?
+      case options[:highlight]
+      when :green
+        s="\e[1;32m#{s}\e[0m"
+      when :red
+        s="\e[1;31m#{s}\e[0m"
+      else
+        s="\e[1;31m#{s}\e[0m"
+      end
+    end
+    unless options[:exception].blank?
+      s << "Exception = #{options[:exception].class.to_s}, message=#{options[:exception].message}"
+    end
+    puts s 
+    if options[:exit]
+      exit
+    end
+  end
+end

data/lib/slh/cli.rb

@@ -0,0 +1,140 @@
+module Slh
+  class Cli # Command Line Interface
+    extend ActiveSupport::Autoload
+    autoload :CommandBase  # abstract class
+    autoload :HostFilterableBase # abstract class
+    autoload :Initialize
+    autoload :Generate
+    autoload :FetchMetadata
+    autoload :CompareMetadata
+    autoload :VerifyMetadataEncryption
+    autoload :GenerateMetadata
+    autoload :GenerateCapistranoDeploy
+    autoload :CopyTemplatesToOverride
+    autoload :DescribeConfig
+
+    attr_reader :args,:action
+
+    def output(msg,*args)
+      Slh.command_line_output(msg,*args)
+    end
+
+    def parse_options_and_delegate(args)
+      if args.nil?
+        @args = [] 
+      else  
+        @args = args.dup
+      end
+      $stdout.sync = true # no output buffering
+      case @args.first
+      when nil
+        puts <<-'EOS'
+
+  This is Shibboleth's Lil Helper.
+                                            He'll help you create consistent
+               ___,@                        config XML for your Shibboleth-Native 
+               /  <                         Service-Provider servers (Apache or IIS)
+          ,_  /    \  _,                    without pulling your hair out in frustration.
+      ?    \`/______\`/
+   ,_(_).  |; (e  e) ;|                     He knows several commands listed below
+    \___ \ \/\   7  /\/    _\8/_            invoked like: "slh initialize".
+        \/\   \'=='/      | /| /|
+         \ \___)--(_______|//|//|           Append "--help" like "slh initialize --help"
+          \___  ()  _____/|/_|/_|           to learn about the options each command can
+             /  ()  \    `----'             take
+            /   ()   \
+           '-.______.-'                     It is STRONLY RECOMMENDED to keep generated files
+         _    |_||_|    _                   produced by this tool under source control--this sneaky
+        (@____) || (____@)                  little elf does not prompt before overwriting files.
+         \______||______/
+MAIN COMMANDS (in usage order)
+  initialize
+    Creates a shibboleths_lil_helper/config.rb.
+    This is where you put ALL OF YOUR shibboleth SP config info for your organization.
+    Shibboleth's Lil Helper operates on this structure to provide all of the funcionality below.
+
+  generate
+    Generates shibboleth2.xml (and others) for deployment to each of your target hosts.
+    Don't forget to restart shibd and httpd on each host after you've updated these files.
+
+  verify_metadata
+    Makes sure all sites expose a URL like site.com/Shibboleth.sso/Metadata.
+    Detects differences in locally generated config with deployed config.
+    Detects encryption key inconsistency issues.
+
+  generate_metadata
+    Assembles your SP metadata for each strategy to give to your IDP
+
+OPTIONAL COMMANDS
+  generate_capistrano
+    Creates a Capistrano config/deploy.rb for automating deployment.  (see Capistrano website)
+    To install and prep for use with capistrano
+      Install:    gem install capistrano
+      Capify dir: capify .
+      Edit config/deploy.rb
+      cap deploy HOST=somehost.com
+
+  copy_templates_to_override
+    Copies config templates into your local directory should you need to customize things beyond what the tool
+    provides.
+    This feature is designed to be used with the 'set_custom :var, "somevalue"' syntax in the config.rb
+    After running this command, you could add the following to one of the shibboleths_lil_helper/templates files:
+      <% if @strategy.respond_to? :dogz %>
+        <%= @strategy.dogz %>
+      <% end %>
+    then in the shibboleths_lil_helper/config.rb
+      set_custom :dogz, "YEA DOGZ"
+    it would result in "YEA DOGZ" appearing in rendered template
+
+    This feature is like a gun in church: You probably don't need it, but if you do, its good to have.
+    (read: don't use this unless you really need it.)
+
+  describe
+    Summarizes the configuration described in shibboleths_lil_helper/config.rb
+
+OTHER DOCUMENTATION SOURCES (not just this tool)
+  https://wiki.shibboleth.net/
+    The official Shibboleth Wiki
+  (within this project--the doc folder)
+    There are lots of short little developer oriented tips we used while creating this tool.
+
+        EOS
+        exit
+      when 'initialize'
+        klass = Slh::Cli::Initialize
+      when 'generate'
+        klass = Slh::Cli::Generate
+      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]
+      when "generate_capistrano"
+        klass = Slh::Cli::GenerateCapistranoDeploy
+      when "copy_templates_to_override"
+        klass = Slh::Cli::CopyTemplatesToOverride
+      when "describe"
+        klass = Slh::Cli::DescribeConfig
+      else 
+        raise "Invalid slh action"
+      end
+      if klass.kind_of? Array
+        klass.each do |k|
+          @action = k.new(@args[1..-1])   # everything except "slh" aka "initialize -f"
+          @action.execute
+        end
+      else
+        @action = klass.new(@args[1..-1]) # everything except "slh" aka "initialize -f"
+        @action.execute
+      end
+    end
+    def self.execute
+      @@instance = self.new
+      @@instance.parse_options_and_delegate(ARGV)
+    end
+    @@instance = nil
+    def self.instance
+      raise "must hit execute to get this piece rolling" if @@instance.nil?
+      @@instance
+    end
+  end
+end

data/lib/slh/cli/command_base.rb

@@ -0,0 +1,32 @@
+# Children should define .default_options and option_parser
+class Slh::Cli::CommandBase
+  attr_reader :args,:option_parser,:options
+  def default_options
+   { }  # CHILD SHOULD DEFINE
+  end
+  def option_parser
+    OptionParser.new # CHILD SHOULD DEFINE
+  end
+
+  def initialize(args)
+    @options = self.default_options
+    if args.nil?
+      @args = [] 
+    else
+      @args = args.dup
+    end
+  end
+  def output_header
+    Slh::Cli.instance.output "\n<<<< BEGIN #{self.class.to_s} >>>>\n"
+  end
+  def output_footer
+    Slh::Cli.instance.output "\n<<<< END #{self.class.to_s} >>>>\n"
+  end
+  def execute
+    Slh.load_config unless self.class == Slh::Cli::Initialize
+    self.option_parser.parse!(self.args)
+    self.output_header
+    self.perform_action
+    self.output_footer
+  end
+end

data/lib/slh/cli/compare_metadata.rb

@@ -0,0 +1,53 @@
+class Slh::Cli::CompareMetadata < Slh::Cli::HostFilterableBase
+  def perform_action
+    # DEV_WISH_LIST: Clean up this mess... this stuff belongs somewhere else
+    mismatch_found = false
+
+    Slh.strategies.each do |strategy|
+      Slh::Cli.instance.output "Iterating hosts for strategy #{strategy.name}"
+      strategy.hosts.each do |host|
+        next if @options[:filter].kind_of?(String) && !host.name.match(@options[:filter])
+
+        raise "Can't find the generated shibboleth2.xml for #{host.name}" unless File.exists?(host.shibboleth2_path)
+
+        local = Nokogiri::XML(File.read(host.shibboleth2_path)) #Nokogiri::XML(shib2)
+        remote_first_site = host.sites.first
+
+        begin
+          remote = Nokogiri::XML(remote_first_site.metadata)
+        rescue Slh::Models::Site::CouldNotGetMetadata => e
+          Slh::Cli.instance.output "  NOT FOUND  #{host.name}", :highlight => :red
+          Slh::Cli.instance.output "    Remote metadata not available at #{remote_first_site.metadata_url}, exception message: #{e.message}"
+          mismatch_found = true
+          next # skip this host
+        rescue Timeout::Error => e
+          Slh::Cli.instance.output "  TIMEOUT #{host.name}", :highlight => :red
+          Slh::Cli.instance.output "    Remote metadata not available at #{remote_first_site.metadata_url}, exception message: #{e.message}"
+          mismatch_found = true
+          next # skip this host
+        end
+        local.remove_namespaces!
+        remote.remove_namespaces!
+        local_version_node = local.at('ApplicationDefaults/CredentialResolver/Key/Name')
+        remote_version_node = remote.at('KeyInfo/KeyName') # remote.at('md:KeyDescriptor/ds:Name')
+        raise "No version nodes found in #{shib2.path}!" if local_version_node.blank?
+        raise "No version nodes found in remote metadata for #{host.name}" if remote_version_node.blank?
+        local_version = local_version_node.inner_text.sub(Slh::Models::Version::PREFIX, '')
+        remote_version = remote_version_node.inner_text.sub(Slh::Models::Version::PREFIX, '')
+        if local_version == remote_version
+          Slh::Cli.instance.output "  OK        #{host.name}", :highlight => :green
+        else
+          Slh::Cli.instance.output "  MISMATCH  #{host.name}", :highlight => :red
+          Slh::Cli.instance.output "    From metadata gathered at #{remote_first_site.metadata_url}"
+          mismatch_found = true
+        end
+      end
+    end
+
+    if mismatch_found
+      Slh::Cli.instance.output "\nThe newest copy of shibboleth2.xml is not deployed to all of your hosts!  This may or may not result in a broken installation, depending on what has changed since the last time you ran this command.", :highlight => true
+    else
+      Slh::Cli.instance.output "\nShibboleth2.xml is up-to-date on all of your hosts!"
+    end
+  end
+end

data/lib/slh/cli/copy_templates_to_override.rb

@@ -0,0 +1,12 @@
+class Slh::Cli::CopyTemplatesToOverride < Slh::Cli::CommandBase
+  def default_options
+   { }
+  end
+
+  def perform_action
+    Slh::Cli.instance.output "Copying all of the erb templates from Shibboleth's Lil Helper to your local directory"
+    FileUtils.cp_r(File.join(File.dirname(__FILE__), '..', 'templates'),Slh.config_dir)
+    Slh::Cli.instance.output "These templates will be used instead of the defaults in the Shibboleth's Lil Helper Rubygem"
+  end
+end
+