Project

ehsso

0.0
Low commit activity in last 3 years
A long-lived project that still receives updates
EH Single Sign On
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Dependencies

Development

~> 2.3
>= 6.1
~> 13.0
~> 3.12
~> 0.21
~> 1.18

Runtime

~> 1.3
~> 1.7
 Project Readme

Gem Version 01 - Test 02 - Release

ehsso

A Rails authorization gem that integrates with company-specific Single Sign-On (SSO) infrastructure. It extracts user identity from HTTP request headers and queries a configured authorization service to retrieve user roles for your application.

How it works

  1. Identity Extraction: Reads user information from specific HTTP headers injected by your SSO infrastructure
  2. Authorization Query: Sends the user identity along with your application's module key to a central authorization service
  3. Role Management: Receives and manages user roles specific to your application/module
  4. Access Control: Provides simple role-checking methods for implementing authorization logic in your Rails app

This gem handles the authorization aspect of SSO - determining what an already authenticated user is allowed to do in your specific application based on their assigned roles.

Supported Ruby Versions

Currently supported and tested ruby versions are:

  • 3.4 (EOL 31 Mar 2028)
  • 3.3 (EOL 31 Mar 2027)
  • 3.2 (EOL 31 Mar 2026)

Ruby versions not tested anymore:

  • 3.1 (EOL 31 Mar 2025)

Installation

Simply add ehsso to your Gemfile and bundle it up.

gem 'ehsso'

Configuration

Configure ehsso with an initializer.

Ehsso.configure do |config|
  # Application reference
  config.module_key = 'my_module_key'

  # Authorization service endpoint with HTTP Basic Auth
  config.base_url   = 'http://{host}:{port}'
  config.username_and_password = 'username:password'
end

Usage

The authorization service typically returns roles like:

  • ADMINISTRATOR - Full system access
  • OPERATOR - Manage and modify resources
  • USER - Standard access, read-only
  • GUEST - Limited access, pending approval

Note: The actual roles returned depend on your authorization service configuration. The gem dynamically handles any role names returned by the service.

Basic Controller Integration

class ApplicationController < ActionController::Base
  before_action :authorize_user

  private

  def authorize_user
    @current_user = Ehsso::Person.parse_from_request_header(request.headers)
    
    if @current_user.valid?
      @current_user.fetch  # Retrieve roles from authorization service
      
      unless @current_user.valid?
        render plain: 'Authorization service unavailable', status: :service_unavailable
      end
    else
      render plain: 'Unauthorized', status: :unauthorized
    end
  end
  
  def current_user
    @current_user
  end
end

Role-Based Access Control

class AdminController < ApplicationController
  before_action :require_admin

  def dashboard
    # Administrator-only content
  end

  private

  def require_admin
    unless @current_user.administrator?
      render plain: 'Access denied', status: :forbidden
    end
  end
end

class ResourcesController < ApplicationController
  def index
    # All authenticated users can view (even guests)
    @resources = Resource.all
  end

  def show
    # Users, operators, and administrators can view details
    if @current_user.user? || @current_user.operator? || @current_user.administrator?
      @resource = Resource.find(params[:id])
    else
      render plain: 'Guest access limited', status: :forbidden
    end
  end

  def edit
    # Operators and administrators can edit
    if @current_user.operator? || @current_user.administrator?
      @resource = Resource.find(params[:id])
    else
      render plain: 'Access denied', status: :forbidden
    end
  end

  def destroy
    # Only administrators can delete
    if @current_user.administrator?
      @resource = Resource.find(params[:id])
      @resource.destroy
      redirect_to resources_path
    else
      render plain: 'Access denied - Administrator only', status: :forbidden
    end
  end
end

Auto-Registration for New Users

class ApplicationController < ActionController::Base
  before_action :authorize_or_register_user

  private

  def authorize_or_register_user
    @current_user = Ehsso::Person.parse_from_request_header(request.headers)
    
    if @current_user.valid?
      # This will create user with 'GUEST' role if they don't exist yet
      @current_user.fetch_or_create
      
      if @current_user.guest?
        redirect_to pending_approval_path
      elsif @current_user.user? || @current_user.operator? || @current_user.administrator?
        # User has been granted proper access
        return true
      end
    else
      render plain: 'Missing SSO headers', status: :unauthorized
    end
  end
end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/thomis/ehsso.

License

The gem is available as open source under the terms of the MIT License.