Omniauth

Setting up OmniAuth

GrapeTokenAuth allows you to use use an OmniAuth provider in lieu of traditional username/password authentication. This wiki article will walk you through setting up GTA to work with OmniAuth providers.

Install the omniauth gems with bundler

You can find a list of omniauth providers here. You will also need to install the main omniauth gem. For example, here is a Gemfile for setting up Github omniauth:

# Gemfile

gem 'omniauth'
gem 'omniauth-github'

Configure provider callback

The details of setting up the provider side will obviously vary by provider. You will need to record any secrets or tokens the provider supplies. Additionally you will need to setup the callback URL to match the omniauth prefix you setup. This prefix can be setup in omniauth, or you can set it up through GrapeTokenAuth configuration. If you do not set it up, it will default to 'omniauth'. With that prefix the callback path will follow the form of:

prefix/provider/callback

Setup the callback URL in your provider with your domain and the path. If you would like to see a visual and more description, see this devise_token_auth README section.

Setup Middleware

If you are setting up middleware in a plain rack app, simply make sure the requisite gems have already been required and then setup the middleware as specified in each gem's instruction, for example here is the setup for github's middleware:

# config.ru

use OmniAuth::Builder do
  provider :github, ENV['GITHUB_KEY'], ENV['GITHUB_SECRET'], scope: 'email,profile'
end

Here the key and secret that github provided in the previous step are being pulled from environmental variables and used to configure the middleware.

If you are setting up omniauth in a rails app, the process found here using the initializer should be the same.

Extra Configuration

If you would like to configure the omniauth prefix you can set it up in the GrapeTokenAuth configuration:

GrapeTokenAuth.configure |config|
  config.omniauth_prefix = 'omniauth'
end

See the Configuration section for more.

Mounting the OmniAuth endpoints

The omniauth callbacks API will have to be mounted at the root path/API. It does not accept a mount path because that will come from the omniauth prefix.

class MainAPI < Grape::API
  ...

  mount_omniauth_callbacks
end

Next the scope specific callbacks will need to be mounted, these do not need to be at the root. This API mounts similar to the other GrapeTokenAuth APIs, for example:

class MainAPI < Grape::API
  ...

  mount_omniauth(to: '/auth', for: :user)
end

This would mount the callbacks for the user scope at the point of /auth relative to the MainAPI.