基于Rails+React的应用集成SAML实现Docebo平台SSO配置咨询

Great question! Integrating SAML SSO between your Rails/React app (acting as the Service Provider, SP) and Docebo (as the Identity Provider, IdP) is totally feasible—let’s walk through a practical, step-by-step solution tailored to your stack.

First, let’s align on the SSO flow to set context:

• A user visits your React frontend and clicks a "Login with Docebo" button.
• The frontend redirects to your Rails backend’s SSO initiation endpoint.
• Rails generates a SAML authentication request and redirects the user to Docebo’s login page.
• After the user authenticates with Docebo, Docebo sends a signed SAML response back to your Rails backend’s Assertion Consumer Service (ACS) endpoint.
• Rails validates the SAML response, creates/syncs the user record, and establishes a session (or issues a JWT for your frontend).
• The user is redirected back to your React frontend as a logged-in user.

For Rails, the most robust and widely used tool for SAML is the devise_saml_authenticatable gem, which integrates seamlessly with Devise (the standard Rails auth framework).

Step 2.1: Install & Configure Dependencies #

1. Add the gem to your Gemfile:

   gem 'devise_saml_authenticatable'
   gem 'devise' # Skip if you already have Devise set up
   

2. Run bundle install and generate Devise/SAML scaffolding:

   bundle install
   rails generate devise:install # Skip if Devise is already configured
   rails generate devise_saml_authenticatable:install
   rails generate devise_saml_authenticatable User # Adjust if your user model has a different name
   rails db:migrate
   

Step 2.2: Configure SAML Settings #

Edit config/initializers/devise_saml_authenticatable.rb to point to Docebo’s IdP metadata and define your SP details:

DeviseSamlAuthenticatable.configure do |config|
  # Load Docebo's IdP metadata (Docebo will provide this URL)
  config.idp_metadata_url = "https://your-docebo-instance.com/saml/metadata"
  
  # Your app's SP Entity ID (you'll input this in Docebo later)
  config.sp_entity_id = "https://your-app-domain.com/saml/metadata"
  
  # ACS URL: Docebo sends SAML responses here (auto-generated by the gem)
  config.assertion_consumer_service_url = "https://your-app-domain.com/users/saml/auth"
  
  # Use email as the unique identifier (match what Docebo will send)
  config.name_identifier_format = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
  
  # Optional: Enable debug logging for troubleshooting
  config.debug = Rails.env.development?
end

Step 2.3: Map SAML Attributes to Your User Model #

Update your app/models/user.rb to handle SAML attributes sent by Docebo. First, add fields to store Docebo-provided data (run a migration if needed):

rails generate migration AddSamlFieldsToUsers name:string email:string docebo_user_id:string
rails db:migrate

Then update the User model:

class User < ApplicationRecord
  devise :saml_authenticatable

  # Map SAML attributes from Docebo to your user fields
  def saml_attributes=(attributes)
    self.email = attributes["email"] || attributes["mail"] # Adjust based on Docebo's attribute names
    self.name = attributes["displayName"] || attributes["name"]
    self.docebo_user_id = attributes["user_id"] # Unique ID from Docebo
    self.save! if changed?
  end
end

Note: Confirm the exact attribute names Docebo sends—check their docs or use debug logs to inspect the SAML response.

Step 2.4: Add SSO Initiation Route #

Add a route in config/routes.rb to trigger the SSO flow:

Rails.application.routes.draw do
  devise_for :users
  get "/sso/login", to: "sessions#initiate_saml_login"
  # ... your other routes
end

Create a SessionsController to handle the redirect:

class SessionsController < ApplicationController
  def initiate_saml_login
    # Redirect to Devise's SAML login endpoint
    redirect_to user_saml_login_path
  end
end

Your frontend’s job is simple: trigger the SSO flow and handle post-login state.

1. Add a "Login with Docebo" Button
   In your login component:

   const LoginPage = () => {
     const handleDoceboLogin = () => {
       window.location.href = "/sso/login"; // Redirect to your Rails SSO initiation route
     };
   
     return (
       <div>
         <h1>Login to Our App</h1>
         <button onClick={handleDoceboLogin}>Login with Docebo</button>
       </div>
     );
   };
   
   export default LoginPage;
   

2. Handle Post-Login Redirect
   After Rails validates the SAML response, it will redirect the user to your app’s root (or a path you configure via Devise’s after_sign_in_path_for). For a SPA setup, you might want Rails to redirect to your frontend domain with a session token or JWT. For example:

   # In app/controllers/application_controller.rb
   def after_sign_in_path_for(resource)
     # Replace with your frontend URL
     "https://your-frontend-domain.com/dashboard?token=#{generate_jwt(resource)}"
   end
   
   private
   def generate_jwt(user)
     # Use a gem like jwt to create a token for your frontend
     JWT.encode({ user_id: user.id, exp: 24.hours.from_now.to_i }, Rails.application.credentials.secret_key_base)
   end
   

3. Manage Frontend Auth State
   Your React app should parse the token from the URL, store it (e.g., in localStorage or a state management tool like Redux), and use it to authenticate API requests to Rails. Add route guards to redirect unauthenticated users to the login page.

You need to register your Rails SP in Docebo’s admin console—this is critical for the SAML handshake to work.

1. Log into your Docebo instance and navigate to Settings > Security > Single Sign-On.
2. Click Add New Provider and select SAML 2.0.
3. Fill in the SP details:
   • Entity ID: Use your Rails app’s sp_entity_id (from devise_saml_authenticatable.rb).
   • ACS URL: Use your Rails app’s assertion_consumer_service_url.
   • Name ID Format: Select urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (match what you set in Rails).
4. Configure Attribute Mapping: Map Docebo user attributes to the names your Rails app expects (e.g., email, displayName, user_id).
5. Enable the provider and save your changes.
6. Copy Docebo’s metadata URL (found in the provider details) and paste it into your Rails devise_saml_authenticatable.rb config.

• Test the End-to-End Flow: Click "Login with Docebo" from your frontend, authenticate with Docebo, and verify you’re logged into your app.
• Debug SAML Responses: Enable debug logging in Rails (set config.debug = true in the SAML initializer) to inspect the raw SAML response and attribute names.
• Common Issues:
  • Validation Errors: Ensure Docebo’s metadata URL is accessible, your SP entity ID/ACS URL match exactly, and the SAML response signature is valid.
  • Attribute Mismatches: Double-check that the attribute names in your saml_attributes= method match what Docebo sends.
  • CORS Issues: If your frontend and backend are on different domains, configure Rails CORS to allow your frontend origin.

内容的提问来源于stack exchange，提问作者jay_dateer