Omniauth::Shipbob

This is an OmniAuth strategy for authenticating to ShipBob.

Requires Ruby >= 3.2, OmniAuth 2.x and omniauth-oauth2 1.9.x.

Installation

Add this line to your application's Gemfile:

gem 'omniauth-shipbob'

And then execute:

$ bundle

Or install it yourself as:

$ gem install omniauth-shipbob

Usage

OmniAuth 2 only accepts POST for the request phase. In a Rails app, add omniauth-rails_csrf_protection to your Gemfile and link to the provider with button_to or link_to ..., method: :post:

gem 'omniauth-rails_csrf_protection'

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :shipbob,
         'client_id', 'client_secret',
         :callback_url => 'http://example.test/auth/shipbob/callback',
         :scope => 'scopes-list'
end

Configuring

You can configure integration_name through the authorize_params hash:

  Rails.application.config.middleware.use OmniAuth::Builder do
    provider :shipbob,
           'client_id', 'client_secret',
           :callback_url => 'http://example.test/auth/shipbob/callback',
           :scope => 'scopes-list',
           :authorize_params => {:integration_name => 'my-application-name' }
end

Configure the API endpoint

api_url sets the host the strategy calls to look up the channel id that lands in credentials['channel_id']. It defaults to https://api.shipbob.com/1.0.

Configure for Sandbox ENV

Configure these options to use ShipBob's sandbox environment.

  Rails.application.config.middleware.use OmniAuth::Builder do
    provider :shipbob,
           ...,
           api_url: 'https://sandbox-api.shipbob.com/2.0',
           client_options: {
             site: 'https://authstage.shipbob.com'
           },
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Releasing

Releases are cut from the GitHub Releases UI; GitHub Actions builds and publishes the gem to rubygems.org via RubyGems trusted publishing, so no API key is stored in the repo and the gemspec can keep rubygems_mfa_required.

1. Bump VERSION in lib/omniauth-shipbob/version.rb and add a CHANGELOG.md section for it, along with a link definition for the new heading at the bottom of that file. Commit both on master.
2. Draft a new release with the target set to master and the tag set to the version prefixed with v — v0.1.0, not 0.1.0. The prefix is stripped before comparing against version.rb; the gem version itself carries no v.
3. Click Generate release notes — the preferred method — then publish. The generated notes list the merged pull requests; CHANGELOG.md carries the curated prose and links back to each release.

Publishing creates the tag, which fires the Release workflow: it reruns the full test matrix, refuses to continue if the tag and version.rb disagree, and pushes the gem. Note that RubyGems versions are immutable — a bad release can be yanked, never replaced, so the version bump has to be committed before the release is published.

One-time RubyGems setup

Already configured, and only needed again if the gem is renamed or moved: on rubygems.org open the gem -> Trusted publishers -> Create, with owner dropstream, repository omniauth-shipbob, workflow release.yml, and environment release. The repo also needs an environment named release.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dropstream/omniauth-shipbob.

License

Available as open source under the terms of the MIT License.