README.md in rack-saml-0.0.1 vs README.md in rack-saml-0.0.2

- old
+ new

@@ -1,26 +1,24 @@ # SAML (Shibboleth SP) middleware for Rack -This project is deeply inspired by rack-shibboleth and ruby-saml. It is recommended to use the defact SAML implementation such as OpenSAML from the security or the functional aspect. However, there are also requirements to use SAML for light weight applications implemented by Ruby. rack-shibboleth may be a candidate to support such kind of objective. However it lacks the configurability to fit OmniAuth and the upgrade path to secure and stable middleware as OpenSAML. So thus I just implemented a prototype to support SAML (Shibboleth SP) for Rack middleware. +This project is deeply inspired by rack-shibboleth and ruby-saml. It is recommended to use the defact SAML implementation such as OpenSAML from the security or the functional aspect. However, there are also requirements to use SAML for light weight applications implemented by Ruby. rack-shibboleth may be a candidate to support such kind of objective. However it lacks the configurability to fit OmniAuth and OmniAuth Shibboleth Strategy. It also lacks the upgrade path to the secure and the stable SAML implementation like OpenSAML. So thus I just implemented a prototype to support SAML (Shibboleth SP) for Rack middleware. OmniAuth Shibboleth Strategy https://github.com/toyokazu/omniauth-shibboleth -## Limitations +rack-saml uses external libraries to generate and validate SAML AuthnRequest/Response. It uses Rack functions to implement SAML Transport (HTTP Redirect Binding and HTTP POST Binding). -### Signing AuthnRequest +## Changes -Current implementation supports only Onelogin SAML assertion handler. It does not support to sign AuthnRequest. +* version 0.0.2: SP session is supported using Rack::Session for Rack applications and ActionDispatch::Session for Rails applications. -### Encrypted Assertion +## Limitations -Current implementation does not support assertion encryption. So thus, assertion encription function should be disabled for rack-saml SPs. +### AuthnRequest Signing and Response Encryption -### SP Session +Current implementation supports only Onelogin SAML assertion handler. It does not support to sign AuthnRequest and encrypt Response. So thus, the assertion encription function should be disabled at IdP side for rack-saml SPs. -Current implementation does not support keeping session at SP side. - ## Getting Started ### Installation % gem install rack-saml @@ -31,73 +29,81 @@ % vi Gemfile gem 'rack-saml' ### Setup Rack::Saml middleware +Rack::Saml uses Rack::Session functions. You have to insert Rack::Session before Rack::Saml middleware. Rack::Session::Cookie is used in the following examples because it is easiest to setup and scale. You can use the other Rack::Session implementation. In a Rails application, it uses ActionDispatch::Session which is compatible with Rack::Session by default. So thus, you do not need to add Rack::Session in the Rails application. + #### For Rack applicaitons In the following example, config.ru is used to add Rack::Saml middleware into a Rails application. % vi config.ru - use Rack::Saml, {:saml_config => "#{Rails.root}/config/saml.yml", + use Rack::Session::Cookie, :secret => 'pass_to_auth_session' + use Rack::Saml, {:config => "#{Rails.root}/config/rack-saml.yml", :metadata => "#{Rails.root}/config/metadata.yml", - :attribute_map => "#{Rails.root}/config/attribute-map.yml", - :shib_app_id => "default"} + :attribute_map => "#{Rails.root}/config/attribute-map.yml"} #### For Ralis applications In the following example, config/application.rb is used to Rack::Saml middleware into a Rails application. % vi config/application.rb module TestRackSaml class Application < Rails::Application - config.middleware.use Rack::Saml, {:saml_config => "#{Rails.root}/config/saml.yml", + config.middleware.use Rack::Saml, {:config => "#{Rails.root}/config/rack-saml.yml", :metadata => "#{Rails.root}/config/metadata.yml", - :attribute_map => "#{Rails.root}/config/attribute-map.yml" - :shib_app_id => "default"} + :attribute_map => "#{Rails.root}/config/attribute-map.yml"} ... +#### Middleware options + +* *:config* path to rack-saml.yml file +* *:metadata* path to metadata.yml file +* *:attribute_map* path to attribute-map.yml file + If you just want to test Rack::Saml, you can ommit middleware options in the both example (config.ru or config/application.rb). use Rack::Saml -However, you can not omit :shib_app_id option if you want to use this middleware with OmniAuth::Shibboleth Strategy. +It may be useful for a tutorial use. At least, saml_idp or shib_ds in rack-saml.yml and metadata.yml must be configured to fit your environment. Rack::Saml uses default configurations located in the rack-saml gem path. $GEM_HOME/rack-saml-x.x.x/config/xxx.yml -#### Middleware options +Please copy them to an arbitrary directory and edit them if you need. If you want to use your customized configuration file, do not forget to specify the configuration file path by middleware options. -* *:saml_config* path to saml.yml file -* *:metadata* path to metadata.yml file -* *:attribute_map* path to attribute-map.yml file -* *:shib_app_id* If you want to use the middleware as Shibboleth SP, you should specify an application ID. In the Shibboleth SP default configuration, 'default' is used as the application ID. - - #### Configuration files You can find default configuration files at - $GEM_HOME/rack-saml-x.x.x/config/ + $GEM_HOME/rack-saml-x.x.x/config/xxx.yml -##### saml.yml +##### rack-saml.yml -Configuration to set SAML parameters. +Configuration to set SAML parameters. At least, you must configure saml_idp or shib_ds. They depends on your environments. -* *protected_path* string or regular expression of the path name where SAML protects, e.g. /auth/shibboleth/callback or '^\/secure\/[^\s]*' -* *protected_path_regexp* use regular expression to match protected_path or not e.g. true / false +* *protected_path* path name where rack-saml protects, e.g. /auth/shibboleth/callback (default path for OmniAuth Shibboleth Strategy) * *metadata_path* the path name where SP's metadata is generated * *assertion_handler* 'onelogin' / 'opensaml' (not implemented yet) -* *saml_idp* idp_entity_id -* *saml_sp* sp_entity_id (self id) -* *sp_cert* path to the SAML SP's certificate file, e.g. cert.pem (signing AuthnRequest is not supported yet) -* *sp_key* path to the SAML SP's key file, e.g. key.pem (signing AuthnRequest is not supported yet) +* *saml_idp* IdP's entity ID which is used to authenticate user. This parameter can be omitted when you use Shibboleth Discovery Service (shib_ds). +* *saml_sess_timeout* SP session timeout (default: 1800 seconds) +* *shib_app_id* If you want to use the middleware as Shibboleth SP, you should specify an application ID. In the Shibboleth SP default configuration, 'default' is used as the application ID. +* *shib_ds* If you want to use the middleware as Shibboleth SP and use discovery service, specify the uri of the Discovery Service. +* *sp_cert* path to the SAML SP's certificate file, e.g. cert.pem (AuthnRequest Signing and Response Encryption are not supported yet) +* *sp_key* path to the SAML SP's key file, e.g. key.pem (AuthnRequest Signing and Response Encryption are not supported yet) +SAML SP's entity ID (saml_sp) is automatically generated from request URI and /rack-saml-sp (fixed path name). The Assertion Consumer Service URI is generated from request URI and protected_path. + + saml_sp_prefix = "#{request.scheme}://#{request.host}#{":#{request.port}" if request.port}#{request.script_name}" + @config['saml_sp'] = "#{saml_sp_prefix}/rack-saml-sp" + @config['assertion_consumer_service_uri'] = "#{saml_sp_prefix}#{@config['protected_path']}" + ##### metadata.yml -To connect to an IdP, you must describe IdP's specification. In rack-saml, it should be written in metadata.yml. metadata.yml file include the following lists. +To connect to an IdP, you must describe IdP's specification. In rack-saml, it should be written in metadata.yml. metadata.yml file include the following lists. You must generate your own metadata.yml by using conv_metadata.rb. * *idp_lists* list of IdP metadata * *sp_lists* list of SP metadata idp_lists and sp_lists are hashes which have entity ids as key values. @@ -110,11 +116,11 @@ parameters of the sp_lists (currently not used): * *certificate* base64 encoded certificate of SP * *saml2_http_post* Location attribute of the SP's assertion consumer uri with HTTP POST Binding -These parameters are automatically extracted from SAML metadata. You can use conv_metadata.rb command for extraction. +These parameters are automatically extracted from SAML metadata (XML). You can use conv_metadata.rb command for extraction. % $GEM_HOME/rack-saml-x.x.x/bin/conv_metadata.rb metadata.xml > metadata.yml ##### attribute-map.yml @@ -122,31 +128,34 @@ "Attribute Name": "Environment Variable Name" "urn:oid:0.9.2342.19200300.100.1.1": "uid" ... +You can use default attribute-map.yml file. If you want to add new attributes, please refer the attribute-map.xml file used in Shibboleth SP. + ### Setup IdP to accept rack-saml SP #### SP Metadata generation To connect a new SP to the existing IdP, you need to import SP's metadata into the IdP. rack-saml provides metadata generation function. It is generated at '/Shibboleth.sso/Metadata' by default. #### IdP configuration examples not to encrypt assertion -Current rack-saml implementation does not support assertion encryption because Onelogin::Saml does not support signature and encryption of assertion. So thus, in the followings, we would like to show sample configurations to disable encryption in IdP assertion processing. These are not recommended for sensitive applications. +Current rack-saml implementation does not support assertion encryption because Onelogin::Saml does not support AuthnRequest signing and Response encryption. So thus, in the followings, we would like to show sample configurations to disable encryption in IdP assertion processing. These are not recommended for sensitive applications. ##### Shibboleth IdP example Add the following configuration after <rp:DefaultRelyingParty> in relying-party.xml. You should specify sp entity id at the 'id' and the 'provider' attributes. % vi $IDP_HOME/conf/relying-party.xml ... - <rp:RelyingParty id="http://example.com:3000/auth/shibboleth/callback" provider="http://example.com:3000/auth/shibboleth/callback" defaultSigningCredentialRef="IdPCredential"> + <rp:RelyingParty id="http://example.com:3000/rack-saml-sp" provider="http://idp.example.com/idp/shibboleth" defaultSigningCredentialRef="IdPCredential"> <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" includeAttributeStatement="true" assertionLifetime="PT5M" assertionProxyCount="0" signResponses="never" signAssertions="always" encryptAssertions="never" encryptNameIds="never"/> </rp:RelyingParty> ## TODO +* write spec files * ruby-opensaml (I hope someone implement it :) ## License Copyright (C) 2011 by Toyokazu Akiyama.