SAML Service Provider Metadata - Complete Implementation Guide

metadata = Saml::Kit::Metadata.build do |x|
  x.entity_id = "https://www.example.org/metadata"
  x.organization_name = "Acme"
  x.contact_email = "acme@example.org"
  x.organization_url = "https://www.example.org"
  x.build_service_provider do |_|
    _.add_assertion_consumer_service('https://www.example.org/assertions', binding: :http_post)
  end
end
puts metadata.to_xml(pretty: true)

Saml::Kit.configure do |config|
  config.entity_id = "https://www.example.org/metadata"
  config.add_key_pair(
    ENV['X509'],
    ENV['PRIVATE_KEY'],
    use: :signing
  )
end
metadata = Saml::Kit::Metadata.build do |x|
  x.organization_name = "Acme"
  x.contact_email = "acme@example.org"
  x.organization_url = "https://www.example.org"
  x.build_service_provider do |_|
    _.add_assertion_consumer_service(
      'https://www.example.org/assertions',
      binding: :http_post
    )
  end
end
puts metadata.to_xml(pretty: true)

configuration = Saml::Kit::Configuration.new do |config|
  config.entity_id = "https://www.example.org/metadata"
  config.generate_key_pair_for(use: :signing)
  config.generate_key_pair_for(use: :encryption)
end
metadata = Saml::Kit::Metadata.build(configuration: configuration) do |x|
  x.organization_name = "Acme"
  x.contact_email = "acme@example.org"
  x.organization_url = "https://www.example.org"
  x.build_service_provider do |_|
    _.add_assertion_consumer_service('https://www.example.org/assertions', binding: :http_post)
  end
end
puts metadata.to_xml(pretty: true)

# app/controllers/sp_metadata_controller.rb
class SpMetadataController < ApplicationController
  def show
    metadata = Saml::Kit::Metadata.build do |builder|
      builder.entity_id = sp_entity_id
      builder.organization_name = Rails.application.class.module_parent_name
      builder.contact_email = ENV.fetch('SUPPORT_EMAIL', 'support@example.com')
      builder.organization_url = root_url
      
      builder.build_service_provider do |sp|
        # Assertion Consumer Service - where SAML responses are posted
        sp.add_assertion_consumer_service(
          saml_acs_url, 
          binding: :http_post
        )
        
        # Single Logout Service - for SAML logout flows
        sp.add_single_logout_service(
          saml_sls_url,
          binding: :http_post
        )
        
        # Single Logout Service for HTTP-Redirect binding
        sp.add_single_logout_service(
          saml_sls_url,
          binding: :http_redirect
        )
      end
    end
    
    respond_to do |format|
      format.xml { render xml: metadata.to_xml }
      format.html { render xml: metadata.to_xml }
    end
  end

  private

  def sp_entity_id
    "#{request.protocol}#{request.host_with_port}/sp/metadata"
  end

  def saml_acs_url
    "#{request.protocol}#{request.host_with_port}/saml/acs"
  end

  def saml_sls_url
    "#{request.protocol}#{request.host_with_port}/saml/sls"
  end
end

# config/initializers/saml_kit.rb
Saml::Kit.configure do |config|
  config.entity_id = ENV.fetch('SAML_SP_ENTITY_ID') { "#{Rails.application.routes.url_helpers.root_url}sp/metadata" }
  
  # Configure signing certificate for metadata and authentication requests
  if Rails.env.production?
    config.add_key_pair(
      ENV.fetch('SAML_SP_CERTIFICATE'),
      ENV.fetch('SAML_SP_PRIVATE_KEY'),
      use: :signing
    )
    
    # Optional: separate encryption certificate
    config.add_key_pair(
      ENV.fetch('SAML_SP_ENCRYPTION_CERTIFICATE'),
      ENV.fetch('SAML_SP_ENCRYPTION_PRIVATE_KEY'),
      use: :encryption
    )
  else
    # Generate temporary keys for development
    config.generate_key_pair_for(use: :signing)
    config.generate_key_pair_for(use: :encryption)
  end
  
  # Configure assertion requirements
  config.assertion_consumer_service_binding = :http_post
  config.single_logout_service_binding = :http_post
  
  # Security settings
  config.default_name_id_format = Saml::Kit::Namespaces::PERSISTENT
end

# config/routes.rb
Rails.application.routes.draw do
  # Service Provider metadata endpoint
  get '/sp/metadata', to: 'sp_metadata#show', as: :sp_metadata
  
  # SAML endpoints
  post '/saml/acs', to: 'saml#acs', as: :saml_acs      # Assertion Consumer Service
  match '/saml/sls', to: 'saml#sls', via: [:post, :get], as: :saml_sls  # Single Logout Service
  get '/saml/login', to: 'saml#login', as: :saml_login  # Initiate SAML login
end

# app/controllers/saml_controller.rb
class SamlController < ApplicationController
  skip_before_action :authenticate_user!, only: [:login, :acs, :sls]
  
  # Initiate SAML authentication (SP-initiated flow)
  def login
    idp_metadata_url = params[:idp] || ENV.fetch('SAML_IDP_METADATA_URL')
    
    # Build authentication request
    auth_request = Saml::Kit::AuthenticationRequest.build do |builder|
      builder.destination = idp_metadata_url
      builder.assertion_consumer_service_url = saml_acs_url
    end
    
    # Store request ID for validation
    session[:saml_request_id] = auth_request.id
    
    # Redirect to Identity Provider
    redirect_to auth_request.redirect_url, allow_other_host: true
  end
  
  # Handle SAML response (Assertion Consumer Service)
  def acs
    saml_response = Saml::Kit::Response.deserialize(params[:SAMLResponse])
    
    # Validate response
    unless saml_response.valid?
      Rails.logger.error "Invalid SAML response: #{saml_response.errors.full_messages}"
      redirect_to new_user_session_path, alert: 'SAML authentication failed'
      return
    end
    
    # Validate in-response-to matches stored request ID
    unless saml_response.in_response_to == session[:saml_request_id]
      Rails.logger.error "SAML response ID mismatch"
      redirect_to new_user_session_path, alert: 'SAML authentication failed'
      return
    end
    
    # Extract user information from SAML assertion
    assertion = saml_response.assertion
    email = assertion.attribute_value_for('email') || assertion.name_id
    name = assertion.attribute_value_for('name')
    
    # Find or create user
    user = User.find_or_initialize_by(email: email)
    user.name = name if name.present?
    user.save!
    
    # Sign in user
    sign_in(user)
    session.delete(:saml_request_id)
    
    redirect_to root_path, notice: 'Successfully authenticated via SAML'
  end
  
  # Handle SAML logout (Single Logout Service)
  def sls
    if request.post?
      # Handle logout response from IdP
      logout_response = Saml::Kit::LogoutResponse.deserialize(params[:SAMLResponse])
      
      if logout_response.valid?
        sign_out(current_user) if user_signed_in?
        redirect_to root_path, notice: 'Successfully logged out'
      else
        redirect_to root_path, alert: 'Logout failed'
      end
    else
      # Handle logout request from IdP
      logout_request = Saml::Kit::LogoutRequest.deserialize(params[:SAMLRequest])
      
      if logout_request.valid?
        sign_out(current_user) if user_signed_in?
        
        # Build logout response
        logout_response = Saml::Kit::LogoutResponse.build(logout_request) do |builder|
          builder.status_code = Saml::Kit::Namespaces::SUCCESS
        end
        
        redirect_to logout_response.redirect_url, allow_other_host: true
      else
        redirect_to root_path, alert: 'Invalid logout request'
      end
    end
  end
  
  private
  
  def saml_acs_url
    "#{request.protocol}#{request.host_with_port}/saml/acs"
  end
end

# Certificate rotation strategy
class CertificateRotator
  def self.rotate_certificates!
    # Generate new certificates
    new_signing_cert = generate_certificate(use: :signing)
    new_encryption_cert = generate_certificate(use: :encryption)
    
    # Update configuration with both old and new certificates
    Saml::Kit.configure do |config|
      # Keep old certificates for compatibility
      config.add_key_pair(old_signing_cert, old_signing_key, use: :signing)
      config.add_key_pair(old_encryption_cert, old_encryption_key, use: :encryption)
      
      # Add new certificates
      config.add_key_pair(new_signing_cert, new_signing_key, use: :signing)
      config.add_key_pair(new_encryption_cert, new_encryption_key, use: :encryption)
    end
    
    # Schedule removal of old certificates after IdPs have updated
    DeprecateCertificatesJob.set(wait: 30.days).perform_later
  end
end

# Validate metadata before serving
class MetadataValidator
  def self.validate!(metadata)
    doc = Nokogiri::XML(metadata.to_xml)
    
    # Ensure required elements are present
    raise 'Missing EntityDescriptor' unless doc.at_xpath('//md:EntityDescriptor', 'md' => 'urn:oasis:names:tc:SAML:2.0:metadata')
    raise 'Missing SPSSODescriptor' unless doc.at_xpath('//md:SPSSODescriptor', 'md' => 'urn:oasis:names:tc:SAML:2.0:metadata')
    raise 'Missing AssertionConsumerService' unless doc.at_xpath('//md:AssertionConsumerService', 'md' => 'urn:oasis:names:tc:SAML:2.0:metadata')
    
    # Validate certificate presence in production
    if Rails.env.production?
      raise 'Missing signing certificate' unless doc.at_xpath('//md:KeyDescriptor[@use="signing"]', 'md' => 'urn:oasis:names:tc:SAML:2.0:metadata')
    end
    
    true
  end
end