OmniAuth SSOProvider Strategy

A generic, customizable OmniAuth strategy for integrating with any OAuth 2.0 Single Sign-On (SSO) provider, typically used for custom or internal identity management systems.

This strategy is built on top of omniauth-oauth2 and provides a mechanism to fetch user details and, critically, retrieve the raw Access Token (JWT) for use in downstream API calls.

🚀 Installation

Add this gem and its dependency, omniauth-oauth2, to your application's Gemfile:

gem 'omniauth-oauth2'
gem 'omniauth-ssoprovider', require: 'omniauth/strategies/ssoprovider'

Then run bundle install.

🛠 Usage and Configuration

The strategy is configured like any standard OmniAuth OAuth2 strategy, but it requires you to set the specific URLs for your SSO provider.

Rails Setup

Create an initializer file, typically located at config/initializers/omniauth.rb:

# config/initializers/omniauth.rb
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :ssoprovider, ENV['SSO_CLIENT_ID'], ENV['SSO_CLIENT_SECRET'],
  # Client Options - Override the defaults for your specific SSO provider
  client_options: {
    site:          '[https://api.your-sso-host.com](https://api.your-sso-host.com)', # Base URL of the SSO provide (REQUIRED)
    authorize_url: '/oauth/authorize',             # Authorization endpoint path (Default: '/oauth/authorize')
    token_url:     '/oauth/token'                  # Token exchange endpoint path (Default: '/oauth/token')
  },
  # Strategy Options - Specific to fetching user details
  user_info_url:   '/api/v1/userinfo',             # Endpoint to fetch the user's details post-token exchange (REQUIRED)
  scope:           'read_profile read_email'       # Optional: Define the OAuth scopes
end

Required Environment Variables

For security, ensure you set your credentials using environment variables:

Variable	Description
`SSO_CLIENT_ID`	The public identifier for your application, provided by the SSO service.
`SSO_CLIENT_SECRET`	The secret key for your application, provided by the SSO service.

⚙️ Strategy Configuration Options

The following options can be customized when configuring the provider:

Option	Default Value	Description
`site`	`https://sso.example.com`	The base URL of your SSO service (e.g., `https://auth.company.com`).
`authorize_url`	`/oauth/authorize`	Path to the authorization code endpoint.
`token_url`	`/oauth/token`	Path to the token exchange endpoint.
`user_info_url`	`/api/v1/userinfo`	Crucial: The API endpoint used to fetch the user's data after the token is obtained.
`scope`	(none)	Optional OAuth scope string (e.g., `'openid email profile'`).

🔑 The Authentication Hash (Auth Hash)

Upon a successful callback, OmniAuth stores the user details in the env['omniauth.auth'] hash.

This strategy populates the hash as follows:

Section	Key	Value	Description
`uid`	`auth['uid']`	`raw_info['id']`	The unique identifier of the user (extracted from the raw info endpoint).
`info`	`auth['info']['name']`	`raw_info['name']`	The user's full name.
`info`	`auth['info']['email']`	`raw_info['email']`	The user's email address.
`extra`	`auth['extra']['raw_info']`	`{...}`	The full JSON response from the `user_info_url` endpoint.
`extra`	`auth['extra']['access_token']`	`'<JWT String>'`	The raw access token string. This is the token your application will use to make subsequent authenticated requests to your SSO API.

Accessing the Token

The primary feature of this strategy is securely exposing the raw JWT string for subsequent API usage. You can access it in your callback controller like this:

def omniauth_callback
  auth_hash = request.env['omniauth.auth']
  # The token required for API calls
  access_token = auth_hash['extra']['access_token']
  # The unique user ID
  user_id = auth_hash['uid']
  # ... proceed with sign-in logic
end