SAML is Security Assertion Mark Up Language, which was built to provide authorization between multiple identities, so that multiple services can use the same authentication.

The SAML authentication can basically happen in two ways:

A) SP Initiated:

1. In this the Service Provider initiates a request to the Identity provider.
2. The Identity provider authorizes the request.
3. Identity Provider creates a SAML response and sends back to the Service Provider.

B) IdP Initiated:

1. In this case the Call is made from Identity Provider's end.
2. So The user Goes to the IdP's url for authentication
3. IdP authenticates the user and generates a SAML response.
4. The SAML response is sent to the Service Provider.

Now here we have a basic idea of SAML, So we are ready to integrate the SAML in our rails application.

To integrate SAML, here we are using "ruby-saml" gem. So lets see step by step how we will integrate it.

1. Add this to your Gemfile:

gem 'ruby-saml', '~> 1.0.0'

2. Include it where you want to handle SAML requests

require 'onelogin/ruby-saml'

3. Now the most important is to set the required things for the IDp to recognize. For that create a function that has all the settings, something like this:

def saml_settings
  settings = OneLogin::RubySaml::Settings.new

  settings.assertion_consumer_service_url = "http://#{request.host}/callback_url"  ## The IDp will send the response here after authorizing the user
  settings.issuer                         = "http://#{request.host}/metada_url" ## Your server's metadata URL
  settings.idp_entity_id                  = "https://IdPs_METADATA_URL"
  settings.idp_sso_target_url             = "https://IdPs_Target_SSO_URL" #Request will come here for authentication
  settings.idp_slo_target_url             = "https://IdPs_LOGOUT_URL"
  settings.idp_cert_fingerprint           = OneLoginAppCertFingerPrint  #Your server's certificate fingureprint
  settings.idp_cert_fingerprint_algorithm = "http://www.w3.org/2000/09/xmldsig#sha1"  #Algorithm used for encryption of the certificate
  settings.name_identifier_format         = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" #Name ID Format

  # Optional for most SAML IdPs
  settings.authn_context = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
  # or as an array
  settings.authn_context = [
    "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
    "urn:oasis:names:tc:SAML:2.0:ac:classes:Password"
  ]

  # Optional bindings (defaults to Redirect for logout POST for acs)
  settings.assertion_consumer_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  settings.assertion_consumer_logout_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

  settings
end

4. After setting these URLs, first you need to figure whether you are creating SP initiated request or IdP initiated. In case of SP initiated requested, you are required to create an action that hits the IdPs authorization URL like this:

def sso_url
  request = OneLogin::RubySaml::Authrequest.new
  redirect_to(request.create(saml_settings))
end

5. The above action will redirect your server to the IdPs authorizing URL, which is set as the idp_sso_target_url in settings and after the authorization is complete it will redirect to your given callback url, which is set as assertion_consumer_service_url. So in that request you need to capture the response something like this:

def callback_url
  response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], :settings => saml_settings)

  # We validate the SAML Response and check if the user already exists in the system
  if response.is_valid?
     # authorize_success, login the user to your application
     session[:userid] = response.nameid
     session[:attributes] = response.attributes
  else
    authorize_failure  # This method shows an error message
  end
end

Hope this was helpful for you. For more information regarding SAML or configuring gem, you can visit https://github.com/onelogin/ruby-saml