ruby-saml¶ ↑

• To bootstrap run “bundle install” (This step is very important, we rely on a forked version of xmlcanonicalizer!)

• To build the gem run “rake build”

• To install the gem run “sudo gem install pkg/ruby-saml-x.x.x.gem”

• To run tests run “rake” or “rake spec”

Transaction ID verification¶ ↑

To verify SAML response ID’s match the outgoing request, clients of this gem must do two things: 1 - Cache the outgoing transaction ID. 2 - Provide the SAML library the cached transaction ID.

For example, in a Rails application, you can store the transaction ID in the user’s session as follows:

saml_request = Onelogin::Saml::Authrequest.new
session[:saml_transaction_id] = saml_request.transaction_id
redirect_to(saml_request.create(settings))

Once the user returns from the IDP with a SAML response, enforce transaction ID matches as follows:

saml_response = Onelogin::Saml::Response.new(params[:SAMLResponse])
saml_response.settings = settings
unless session[:saml_transaction_id]
  redirect_to(:action => "denied") and return
end
saml_response.expected_transaction_id = session[:saml_transaction_id]
if saml_response.valid? and saml_response.name_id
  session[:username] = saml_response.name_id
  redirect_to "/auth/index"
else
  redirect_to "/auth/denied"
end

Once expected_transaction_id is set on a Onelogin::Saml::Response, all calls to valid? will check the response’s ID against the provided id.

Rake tasks¶ ↑

To access rake tasks provided by ruby-saml, include the following in your Rakefile:

require 'onelogin/saml/tasks'

ruby-saml includes the following rake tasks:

• saml:gen_cert - Generate a self-signed certificate and private key pair, saving them to ./config/saml/sp.{cer,key}

• saml:gen_sp_metadata - Generate a service provider metadata file based on config information in ./config/saml/sp.yml

An example sp.yml to get you started:

issuer: saml-example
consumer_url: http://saml.example.com/authenticate
name_id_format:
  - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
cert_file: ./config/saml/sp.cer
private_key_file: ./config/saml/sp.key
private_key_password: passphrase_for_sp_key

Note on Patches/Pull Requests¶ ↑

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.