omniauth-sps_commerce 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0acb9eeb0bc851072a548e41b2eba2c6147e3adcc8f37212f989db855dc1d033
+  data.tar.gz: 90faa4b21c306e2e962299fa98399992d5adcb4205029e4cb37fad344e817c1f
+SHA512:
+  metadata.gz: '0775910b5083a680d252ba95a4686be5aee85edc53451a5c7f3d14c29b14fe8cb80b568be466865302776d8e409cd3d682a6f15000a7cd99b639fcb768b69244'
+  data.tar.gz: 485b917d28bf009fec063639f78d87ac91ec7e40bcb6d1b0a6b4b9a5945759abe96b1109377da03f07af761f059662d43706e28928897e236d2637885cb06597

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- `OmniAuth::Strategies::SpsCommerce`, registered as `:sps_commerce`: the authorization code
+  flow against `auth.spscommerce.com` (`/authorize`, `/oauth/token`), with a JSON token
+  request carrying the client credentials in its body.
+- Default scope `openid profile email offline_access` and default audience
+  `https://spscommerce.com`, so the callback returns an API access token and a refresh token.
+- `uid` and `info` from the id_token, falling back to the access token's claims; `extra`
+  carries both claim sets and the token response params (without the raw id_token).
+- Per-request `prompt` and `login_hint`.
+- A `callback_url` override that drops the callback's query string and honors a configured
+  `:callback_url`.
+- Supports `omniauth-oauth2` 1.8 as well as 1.9, so apps still on 1.8 can use it.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dropstream
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+# OmniAuth SPS Commerce
+
+An OmniAuth strategy for [SPS Commerce](https://www.spscommerce.com). It runs the OAuth 2.0
+authorization code flow against `auth.spscommerce.com` (SPS's Auth0 tenant) and returns an
+access token and refresh token for the SPS APIs, such as the Transaction API.
+
+Requires Ruby >= 3.2, OmniAuth 2.x and `omniauth-oauth2` 1.8 or 1.9.
+
+## Installation
+
+```ruby
+gem 'omniauth-sps_commerce'
+```
+
+## Usage
+
+OmniAuth 2 only accepts `POST` for the request phase. In a Rails app, add
+[`omniauth-rails_csrf_protection`](https://github.com/cookpad/omniauth-rails_csrf_protection)
+and link to the provider with `button_to`.
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :sps_commerce, ENV['SPS_CLIENT_ID'], ENV['SPS_CLIENT_SECRET']
+end
+```
+
+Register the callback URL (`https://<host>/auth/sps_commerce/callback`) on the app in the
+SPS Dev Center.
+
+### Production and sandbox keys
+
+Each SPS app comes with a production key and a sandbox key. Both authenticate against
+`auth.spscommerce.com`, so register the strategy once per key under different names:
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :sps_commerce, ENV['SPS_CLIENT_ID'], ENV['SPS_CLIENT_SECRET']
+  provider :sps_commerce, ENV['SPS_SANDBOX_CLIENT_ID'], ENV['SPS_SANDBOX_CLIENT_SECRET'],
+           name: :sps_commerce_sandbox
+end
+```
+
+The sandbox registration answers on `/auth/sps_commerce_sandbox` and
+`/auth/sps_commerce_sandbox/callback`. A refresh token can only be redeemed with the key
+that issued it, so record which registration a token came from (`auth.provider`).
+
+Use a separate SPS app (and so separate keys) per deployment environment.
+
+## The auth hash
+
+```ruby
+auth = request.env['omniauth.auth']
+auth['provider']                    # "sps_commerce" or "sps_commerce_sandbox"
+auth['uid']                         # Auth0 subject of the SPS user who authorized
+auth['info']                        # name, email, nickname (from the id_token)
+auth['credentials']['token']        # access token
+auth['credentials']['refresh_token']
+auth['credentials']['expires_at']
+auth['extra']['claims']             # id_token claims
+auth['extra']['access_token_claims']# access token claims, including SPS-specific ones
+```
+
+Token claims are decoded without verifying signatures. That is safe only because tokens
+come straight from `auth.spscommerce.com` over TLS, never from the browser. Don't reuse the
+decoder on tokens from any other source.
+
+## Configuring
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `scope` | `openid profile email offline_access` | `offline_access` is what returns a refresh token. |
+| `audience` | `https://spscommerce.com` | Without an audience, Auth0 issues an opaque token that only works on `/userinfo`. |
+| `client_options[:site]` | `https://auth.spscommerce.com` | |
+| `callback_url` | derived from the request | Drops the callback's query string, since Auth0 requires an exact `redirect_uri` match. |
+
+`prompt` and `login_hint` can also be set per request (`/auth/sps_commerce?login_hint=…`).
+Nothing else is taken from request params.
+
+The endpoints come from
+[SPS's OpenID configuration](https://auth.spscommerce.com/.well-known/openid-configuration).
+
+## Development
+
+Run `bin/setup`, then `bundle exec rake spec`. Run `bundle exec bundle-audit check --update`
+to check the locked dependencies against the advisory database; CI runs it weekly.
+
+## Releasing
+
+Releases are cut from the GitHub Releases UI and published by the `Release` workflow
+through [RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/):
+
+1. Bump `VERSION` in `lib/omniauth-sps_commerce/version.rb` and add a `CHANGELOG.md`
+   section. Commit both on `main`.
+2. Draft a release targeting `main` with tag `vX.Y.Z` matching `version.rb`, then publish.
+
+One-time setup on rubygems.org: open the gem, then **Trusted publishers** → **Create**, with
+owner `dropstream`, repository `omniauth-sps_commerce`, workflow `release.yml` and environment
+`release`. The repo also needs an environment named `release`.
+
+## License
+
+Available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/omniauth/strategies/sps_commerce.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'omniauth-oauth2'
+
+module OmniAuth
+  module Strategies
+    # SPS Commerce identity runs on Auth0. The endpoints below come from
+    # https://auth.spscommerce.com/.well-known/openid-configuration.
+    #
+    # An SPS app has a production key and a sandbox key. Both authenticate against
+    # the same host, so the strategy does not need to know which one it holds:
+    # register it twice with different names to offer both (see the README).
+    class SpsCommerce < OmniAuth::Strategies::OAuth2
+      DEFAULT_SITE = 'https://auth.spscommerce.com'
+      # The audience SPS documents for the authorize request. Without one, Auth0
+      # issues an opaque access token that only works on /userinfo.
+      DEFAULT_AUDIENCE = 'https://spscommerce.com'
+      # offline_access is what makes Auth0 return a refresh token.
+      DEFAULT_SCOPE = 'openid profile email offline_access'
+
+      option :name, 'sps_commerce'
+
+      option :client_options, {
+        site: DEFAULT_SITE,
+        authorize_url: '/authorize',
+        token_url: '/oauth/token',
+        # SPS documents client_id and client_secret in the token request body.
+        auth_scheme: :request_body
+      }
+
+      option :scope, DEFAULT_SCOPE
+      option :audience, DEFAULT_AUDIENCE
+
+      option :authorize_options, %i[scope audience prompt login_hint]
+
+      # Options a request may set for itself, e.g.
+      # /auth/sps_commerce?login_hint=user@example.com
+      REQUEST_AUTHORIZE_OPTIONS = %w[prompt login_hint].freeze
+
+      uid { user_claims['sub'] }
+
+      info do
+        {
+          name: user_claims['name'],
+          email: user_claims['email'],
+          nickname: user_claims['nickname']
+        }
+      end
+
+      extra do
+        {
+          'params' => access_token.params.except('id_token'),
+          'claims' => user_claims,
+          'access_token_claims' => access_token_claims
+        }
+      end
+
+      def authorize_params
+        super.tap do |params|
+          REQUEST_AUTHORIZE_OPTIONS.each do |key|
+            value = request.params[key]
+            params[key.to_sym] = value unless value.nil? || value == ''
+          end
+        end
+      end
+
+      # SPS documents a JSON token request; oauth2 sends a form unless the token
+      # params carry this header. It is added here rather than through the
+      # token_params option, which would symbolize the header name, and oauth2
+      # only recognizes it as a string.
+      def build_access_token
+        client.auth_code.get_token(
+          request.params['code'],
+          { redirect_uri: callback_url, headers: { 'Content-Type' => 'application/json' } }
+            .merge(token_params.to_hash(symbolize_keys: true)),
+          deep_symbolize(options.auth_token_params)
+        )
+      end
+
+      # OmniAuth::Strategy#callback_url appends the callback request's own query
+      # string, and Auth0 requires redirect_uri to match an allowed callback URL
+      # exactly. omniauth 2's `callback_path` already carries SCRIPT_NAME, so mount
+      # prefixes must not be added again.
+      def callback_url
+        options[:callback_url] || (full_host + callback_path)
+      end
+
+      private
+
+      # Claims for the signed-in user: from the id_token (granted by the openid
+      # scope), otherwise from the access token. The payload is read without
+      # verifying the signature, which is acceptable only because the token
+      # arrives directly from auth.spscommerce.com over TLS, never from the browser.
+      def user_claims
+        @user_claims ||= decode_jwt_claims(access_token.params['id_token']) || access_token_claims
+      end
+
+      # The API access token's claims, which carry the SPS-specific ones (for
+      # example the organization). Empty when the token is opaque.
+      def access_token_claims
+        @access_token_claims ||= decode_jwt_claims(access_token.token) || {}
+      end
+
+      def decode_jwt_claims(jwt)
+        payload = jwt.to_s.split('.')[1]
+        return nil if payload.nil? || payload.empty?
+
+        # Base64url-decode by hand; the base64 gem left Ruby's default gems in 3.4.
+        json = (payload.tr('-_', '+/') + '=' * (-payload.length % 4)).unpack1('m')
+        claims = JSON.parse(json)
+        claims.is_a?(Hash) ? claims : nil
+      rescue ArgumentError, JSON::ParserError, EncodingError
+        nil
+      end
+    end
+  end
+end

data/lib/omniauth-sps_commerce/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Omniauth
+  module SpsCommerce
+    VERSION = "0.1.0"
+  end
+end

data/lib/omniauth-sps_commerce.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "omniauth-sps_commerce/version"
+require "omniauth/strategies/sps_commerce"

data/omniauth-sps_commerce.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "omniauth-sps_commerce/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "omniauth-sps_commerce"
+  spec.version       = Omniauth::SpsCommerce::VERSION
+  spec.authors       = ["Karl Falconer"]
+  spec.email         = ["karl.falconer@getdropstream.com"]
+
+  spec.summary       = "OmniAuth strategy for SPS Commerce"
+  spec.description   = "An OmniAuth OAuth2 strategy that authenticates against SPS Commerce " \
+                       "(auth.spscommerce.com) and obtains tokens for the SPS Commerce APIs."
+  spec.homepage      = "https://github.com/dropstream/omniauth-sps_commerce"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"]      = spec.homepage
+  spec.metadata["source_code_uri"]   = spec.homepage
+  spec.metadata["changelog_uri"]     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Ship only the library itself; development scaffolding stays out of the gem.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:spec|bin|pkg|\.github)/}) ||
+        f.match(%r{\A(?:\.gitignore|\.rspec|\.ruby-version|\.ruby-gemset|Gemfile|Gemfile\.lock|Rakefile)\z})
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "omniauth", "~> 2.0"
+  spec.add_dependency "omniauth-oauth2", ">= 1.8", "< 2"
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-sps_commerce
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Karl Falconer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: An OmniAuth OAuth2 strategy that authenticates against SPS Commerce (auth.spscommerce.com)
+  and obtains tokens for the SPS Commerce APIs.
+email:
+- karl.falconer@getdropstream.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/omniauth-sps_commerce.rb
+- lib/omniauth-sps_commerce/version.rb
+- lib/omniauth/strategies/sps_commerce.rb
+- omniauth-sps_commerce.gemspec
+homepage: https://github.com/dropstream/omniauth-sps_commerce
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/dropstream/omniauth-sps_commerce
+  source_code_uri: https://github.com/dropstream/omniauth-sps_commerce
+  changelog_uri: https://github.com/dropstream/omniauth-sps_commerce/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: OmniAuth strategy for SPS Commerce
+test_files: []