Ruby on Rails SAML Integration: A Beginner-Friendly Guide

Ruby on Rails SAML Integration: A Beginner-Friendly Guide

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider (IdP) and a service provider (SP). In simpler terms, SAML allows users to log in to multiple applications using a single set of credentials managed by a central authority. This eliminates the need for users to create and remember separate logins for each application, improving user experience and simplifying identity management for organizations.

This guide provides a comprehensive, beginner-friendly walkthrough of integrating SAML into a Ruby on Rails application, turning your Rails app into a service provider. We’ll cover the fundamental concepts, step-by-step implementation using the devise_saml_authenticatable gem, and troubleshooting common issues.

Understanding the Core Concepts

Before diving into the implementation, it’s crucial to understand the key players and the flow of information in a SAML-based authentication system:

• Identity Provider (IdP): The IdP is responsible for authenticating users and asserting their identity to the service provider. Examples include Okta, OneLogin, Azure Active Directory, and Shibboleth.
• Service Provider (SP): The SP is the application that relies on the IdP for authentication. This is your Rails application.
• User: The individual attempting to access the protected resources of the SP.
• Assertion: An XML document containing information about the user, such as their identity and attributes, issued by the IdP after successful authentication.

The SAML Authentication Flow:

1. User requests access: The user attempts to access a protected resource in your Rails application (the SP).
2. Redirection to IdP: The SP redirects the user to the IdP for authentication.
3. User authentication: The user logs in to the IdP using their credentials.
4. Assertion generation: Upon successful authentication, the IdP generates a SAML assertion containing information about the user.
5. Assertion transmission: The IdP sends the SAML assertion back to the SP.
6. Assertion validation and user creation/login: The SP validates the SAML assertion and creates a new user account or logs in the existing user based on the information in the assertion.

Implementing SAML in Rails with devise_saml_authenticatable

The devise_saml_authenticatable gem simplifies SAML integration with Rails applications by providing a Devise strategy for SAML authentication. Let’s walk through the implementation process:

1. Install necessary gems:

Add the following gems to your Gemfile and run bundle install:

ruby
gem 'devise'
gem 'devise_saml_authenticatable'

2. Configure Devise:

Generate the Devise initializer and configure it:

bash
rails generate devise:install

Edit config/initializers/devise.rb and add the following inside the Devise configuration block:

ruby
config.saml_configure do |settings|
settings.assertion_consumer_service_url = "http://localhost:3000/users/saml/auth"
settings.issuer = "http://localhost:3000"
settings.idp_sso_target_url = "YOUR_IDP_SSO_TARGET_URL"
settings.idp_cert_fingerprint = "YOUR_IDP_CERT_FINGERPRINT"
settings.name_identifier_format = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
# Add other settings as needed based on your IdP configuration
end

Replace YOUR_IDP_SSO_TARGET_URL and YOUR_IDP_CERT_FINGERPRINT with the appropriate values provided by your IdP.

3. Generate the User model:

If you haven’t already, generate the User model with Devise:

bash
rails generate devise User

4. Configure the User model:

Add the :saml_authenticatable module to your User model in app/models/user.rb:

ruby
devise :saml_authenticatable, :trackable, :timeoutable # Add other modules as needed

5. Configure routes:

Add the following line to your config/routes.rb file within the Devise scope:

ruby
devise_for :users, controllers: { saml_sessions: 'saml_sessions' }

6. Metadata Configuration:

The IdP requires metadata about your service provider. The devise_saml_authenticatable gem provides a route to serve this metadata. Access this route in your browser (e.g., http://localhost:3000/users/saml/metadata) and provide the XML content to your IdP.

7. Attribute Mapping (Optional):

You can map attributes from the SAML assertion to your User model. Add the following to your config/initializers/devise.rb file:

ruby
config.saml_attribute_mapping = {
"email" => "email",
"first_name" => "first_name",
"last_name" => "last_name"
# Map other attributes as needed
}

8. Protecting Resources:

Use Devise’s authenticate_user! before_action in your controllers to protect resources requiring SAML authentication.

“`ruby
class MyController < ApplicationController
before_action :authenticate_user!

# … your controller actions …
end
“`

9. Testing and Troubleshooting:

• Test the integration: After configuring everything, try accessing a protected resource. You should be redirected to your IdP for login. After successful authentication, you should be redirected back to your Rails application.
• Check logs: Examine your Rails logs for any errors during the SAML process.
• Validate XML: Use an online XML validator to verify the SAML metadata and assertions.
• Inspect SAML responses: Use a browser extension like SAML Tracer to inspect the SAML requests and responses between your application and the IdP.

Advanced Configurations and Considerations:

• Single Logout (SLO): Implement SLO to allow users to log out of all SAML-enabled applications with a single action. The devise_saml_authenticatable gem supports SLO.
• Encrypted Assertions: Enhance security by configuring your IdP and SP to use encrypted assertions.
• Attribute Statements: Leverage attribute statements within the SAML assertion to provide additional user information to your application.
• Customizing the Login Form: You might need to customize the login experience if your IdP doesn’t provide a standard login form. This can usually be achieved through IdP-specific configurations.

Example IdP Configuration (Okta):

• Create a new application in Okta: Choose “SAML 2.0” as the sign-on method.
• Configure the SAML settings: Provide the ACS URL and Entity ID from your Rails application’s metadata.
• Assign users to the application: Specify which users can access your Rails application through SAML.

Alternative Gems:

While devise_saml_authenticatable is a popular choice, other gems are available for SAML integration in Rails, including ruby-saml and omniauth-saml.

Conclusion:

Integrating SAML into your Rails application can seem daunting at first, but with the help of gems like devise_saml_authenticatable and a clear understanding of the underlying concepts, it becomes a manageable process. This guide has provided a comprehensive overview of the implementation steps and common configurations. By following these instructions and utilizing the troubleshooting tips, you can successfully implement SAML authentication and enhance the security of your Rails application while providing a seamless login experience for your users. Remember to consult your IdP’s documentation for specific configuration details. With careful planning and execution, you can effectively leverage SAML to streamline user access and enhance the security posture of your Rails application.