OmniAuth Lightspeed OAuth2

OmniAuth strategy for Lightspeed Restaurant (K-Series) OAuth2 authentication.

Lightspeed K-Series uses OpenID Connect (Keycloak) with standard OAuth2 Authorization Code Grant. This gem handles the full OAuth2 flow, token exchange, and fetches business information from the Lightspeed K-Series API.

Installation

Add to your Gemfile:

gem 'omniauth-lightspeed-oauth2'

Then run:

bundle install

Usage

Rails with Devise

# config/initializers/devise.rb
config.omniauth :lightspeed_oauth2,
  ENV['LIGHTSPEED_CLIENT_ID'],
  ENV['LIGHTSPEED_CLIENT_SECRET'],
  environment: Rails.env.production? ? :production : :trial

Standalone OmniAuth

# config.ru or initializer
use OmniAuth::Builder do
  provider :lightspeed_oauth2,
    ENV['LIGHTSPEED_CLIENT_ID'],
    ENV['LIGHTSPEED_CLIENT_SECRET'],
    environment: :trial
end

Environments

Environment	Auth Server	API Server
`:trial` (default)	`auth.lsk-demo.app`	`api.trial.lsk.lightspeed.app`
`:production`	`auth.lsk-prod.app`	`api.lsk.lightspeed.app`

Auth Hash

After successful authentication, the auth hash contains:

{
  provider: 'lightspeed_oauth2',
  uid: '12345',                          # Lightspeed business ID
  info: {
    business_name: 'My Restaurant',
    currency_code: 'USD',
    location_id: 67890,
    location_name: 'Main Location',
    country: 'US',
    timezone: 'America/New_York'
  },
  credentials: {
    token: 'access_token_value',
    refresh_token: 'refresh_token_value',
    expires_at: 1234567890,
    expires: true
  },
  extra: {
    raw_info: {
      'business_id' => 12345,
      'business_name' => 'My Restaurant',
      'currency_code' => 'USD',
      'location_id' => 67890,
      'location_name' => 'Main Location',
      'country' => 'US',
      'timezone' => 'America/New_York'
    }
  }
}

Configuration Options

Option	Default	Description
`environment`	`:trial`	API environment (`:trial` or `:production`)
`scope`	`openid`	OAuth2 scopes to request

Callback URL

https://yourdomain.com/auth/lightspeed_oauth2/callback

For development with ngrok:

https://yourapp.ngrok.dev/auth/lightspeed_oauth2/callback

Note: Lightspeed requires the redirect_uri to match exactly. This gem automatically strips query parameters from the callback URL during token exchange to ensure matching.

Token Refresh

Access tokens expire. Use the refresh token to obtain new pairs:

client = OAuth2::Client.new(
  ENV['LIGHTSPEED_CLIENT_ID'],
  ENV['LIGHTSPEED_CLIENT_SECRET'],
  site: 'https://api.trial.lsk.lightspeed.app',
  token_url: 'https://auth.lsk-demo.app/realms/k-series/protocol/openid-connect/token'
)

token = OAuth2::AccessToken.from_hash(client, {
  access_token: stored_access_token,
  refresh_token: stored_refresh_token
})

new_token = token.refresh!
# Store new_token.token and new_token.refresh_token

Development

git clone https://github.com/dan1d/omniauth-lightspeed-oauth2.git
cd omniauth-lightspeed-oauth2
bundle install

# Run tests (100% line + branch coverage enforced)
bundle exec rspec

# Run linter
bundle exec rubocop

# Run both
bundle exec rake

Testing

20 examples with 100% line and branch coverage enforced via SimpleCov. The test suite uses WebMock to stub all HTTP requests.

Contributing

Fork it
Create your feature branch (git checkout -b feature/my-feature)
Write tests first (TDD)
Ensure 100% coverage: bundle exec rspec
Ensure no RuboCop offenses: bundle exec rubocop
Commit your changes
Push to the branch
Create a Pull Request

License

MIT License. See LICENSE.txt for details.