omniauth-ebay-oauth

OmniAuth Strategy for eBay Apps (for using with eBay REST APIs)

Preface

Why do I need it? There are a couple of other gems with OmniAuth strategies for eBay?

eBay has two different authorization methods: Auth'n'auth and OAuth. Technically, they are both uses OAuth2 protocol (just to embrace a little confusion).

This gem implements authorization with OAuth method while currently available gems (like ebay_request or omniauth-ebay) implements Auth'n'auth.

What is the difference? Access tokens!

With Auth'n'auth you will get a single token which you can use to access only old eBay XML APIs (Trading API, etc.)

With OAuth, you will get a pair of access and refresh tokens which can be used to access new eBay REST APIs (Buy API, Sell API, etc.)

However, you can use new OAuth tokens to access old APIs too by providing an access token in HTTP header X-EBAY-API-IAF-TOKEN. This is documented in eBay developer program website: Using OAuth with the eBay traditional APIs.

If you plan to use new APIs, you are welcome to use this gem together with ebay_api client gem for REST APIs.

For old APIs, you can look at ebay_request gem (you can configure it to use OAuth tokens).

Now you can read the eBay docs about REST APIs and OAuth and then proceed to…

Installation

Add to your Gemfile:

gem 'omniauth-ebay-oauth'

Then execute:

bundle install

Usage

use OmniAuth::Builder do
  provider :ebay_oauth, CLIENT_ID, CLIENT_SECRET, callback_url: RU_NAME,
    sandbox: false, scope: 'https://api.ebay.com/oauth/api_scope' # redefining additional default options
end

Required options:

CLIENT_ID, CLIENT_SECRET - Your application's OAuth credentials for the environment you're targeting.
__callback_url__ - Your application's RuName for the environment you're targeting.

Additional options:

sandbox - Are you running your application in sandbox mode, default true.
scope - A list of OAuth scopes that provide access to the interfaces you call, default: []. If you want change scopes you could pass it as string or as array of scopes like so: ['https://api.ebay.com/oauth/api_scope/sell.marketing.readonly', 'https://api.ebay.com/oauth/api_scope/sell.account.readonly']
prompt - Use value login to ask user for login and password even if they're already logged in (useful for switching between multiple accounts). By default is absent.
__read_timeout__ - Number of seconds to wait for one block to be read for Auth'n'auth eBay API requests, default is 60.
+ all OmniAuth supported options, like: callback_path, provider_ignores_state and so on.

Additional usage information could be found on OmniAuth README page.

Minimal working Sinatra application:

require 'sinatra'
require 'omniauth-ebay-oauth'

use Rack::Session::Cookie
use OmniAuth::Builder do
  provider :ebay_oauth, ENV['EBAY_CLIENT_ID'], ENV['EBAY_CLIENT_SECRET'],
    callback_url: ENV['EBAY_RU_NAME'], name: 'ebay'
end

get '/' do
  redirect '/auth/ebay'
end

get '/auth/ebay/callback' do
  "Hello, #{request.env['omniauth.auth'].dig('info', 'name')}"
end

# OmniAuth disables starting authentication with GET request to mitigate CVE-2015-9284.
# For testing purposes we can enable it, but for production it is better to use POST with CSRF protection/
OmniAuth.config.allowed_request_methods += %i[get]

Development

To pass your code through the all checks you simply need to run:

bundle exec rake

Please, keep in mind OmniAuth Strategy Contribution Guide and eBay developers program.

Releasing new versions

Bump version number in lib/omniauth/ebay-oauth/version.rb

In case of pre-releases keep in mind rubygems/rubygems#3086 and check version with command like Gem::Version.new(OmniAuth::EbayOauth::VERSION).to_s
Fill CHANGELOG.md with missing changes, add header with version and date.

Make a commit:

git add lib/omniauth/ebay-oauth/version.rb CHANGELOG.md
version=$(ruby -r ./lib/omniauth/ebay-oauth/version.rb -e "puts Gem::Version.new(OmniAuth::EbayOauth::VERSION)")
git commit --message="${version}: " --edit

Create annotated tag:

git tag v${version} --annotate --message="${version}: " --edit --sign

Fill version name into subject line and (optionally) some description (list of changes will be taken from CHANGELOG.md and appended automatically)
Push it:
```
git push --follow-tags
```
GitHub Actions will create a new release, build and push gem into rubygems.org! You're done!

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/evilmartians/omniauth-ebay-oauth.

License

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

evilmartians / omniauth-ebay-oauth

readme