Identity::Gateway

Identity’s gateway provider for Ruby and Rails applications. Act as a man in the middle between backend services and Identity.

Installation

Add this line to your application’s Gemfile:

“by gem ‘identity-gateway’

“

Use Bundler to install the dependency:

$ bundle

Usage

Once you’ve configured it, you can use the Identity::Gateway::Provider class in order to act as your authentication mechanism.

“by

app/controllers/api_controller.rb

module Api class ApiController < ApplicationController def authorize_access! @provider = Identity::Gateway::Provider.new(request) @provider.authorize! end end end

app/controllers/api/v1/posts_controller.rb

module Api module V1 class PostsController < Api::ApiController before_action :authorize_access!, only: [:index]

  def index
    # Only authenticated users can access it.
  end
end

end end

“

Current subject

A subject is the instance associated to the model you specify using the model option when you configure the gem. Any instance of Identity::Gateway::Provider expose a public method name current_resource that allows you to retrieve the resource associated to a given access token.

“by

app/controllers/api_controller.rb

module Api class ApiController < ApplicationController def authorize_access! @provider = Identity::Gateway::Provider.new(request) @provider.authorize! end

def current_user
  @current_user ||= @provider.current_resource
end

end end

“

Rescuing a denied Authorization in Rails

Identity::Gateway raises a Identity::Gateway::Unauthorized error you can rescue_from in your ApplicationController. You can customize the unauthorized_response method in every controller.

“by class ApplicationController < ActionController::Base protect_from_forgery with: :null_session

rescue_from Identity::Gateway::Unauthorized, with: :unauthorized_response

private

def unauthorized_response render json: { message: ‘You need to sign in before continuing.’ }, status: :unauthorized end end

“

Alternatively, you can globally handle Identity::Gateway::Unauthorized’s by having rails handle them as a 401 error and serving a 401 error page. Add the following to application.rb:

“by config.action_dispatch.rescue_responses[Identity::Gateway::Unauthorized] = :unauthorized

“

Configuration

You can configure Identity::Gateway by creating an initializer config/initializers/identity_gateway.rb and passing it a configure block:

“by Identity::Gateway.configure do |config| # Define options here end

“

Options

model

This option allows you to define the name of the model you wish to associate. For example, if you handle cache for users with a User model, then it could looks like:

“by config.model = ‘User’

“

provider_url

This option allows you to define the url to your Identity server:

“by config.provider_url = ‘https://identity.domain.com’

“

identity_path

This option allows you to define the path on Identity that return the information about the current user. Generally, this path will be /me:

“by config.identity_path = ‘/me’

“

version_header

This option allows you to define the Accept header use to determinate which version of Identity’s API you which to use:

“by config.version_header = ‘application/vnd.wamland+json; version=1’

“

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/wamland-team/identity-gateway.