HeimdallAuth

This makes it easy to equip an empty rails application with our Heimdall Auth features.

New Feature: Secure Sidekiq (and other mounts)

Use it like so in config/routes.rb:

mount_heimdall_auth_secured Sidekiq::Web => '/sidekiq', :manage => :sidekiq

or

# The /sidekiq/stats path gets available for services like Datadog
mount_heimdall_auth_secured Sidekiq::Web => '/sidekiq', :manage => :sidekiq, accessible_via_token: {'/sidekiq/stats': ENV['SIDEKIQ_STATS_TOKEN_FOR_WATCHDOG']}

instead of the known:

mount Sidekiq::Web => '/sidekiq'

Additionally you need to add the rights to your app/models/ability.rb:

if user.is_admin
  can :manage, :sidekiq
end

and the password in .env and .env.example if you used it:

SIDEKIQ_STATS_TOKEN_FOR_WATCHDOG=halloweltrandomstring

Options:

  • mount_heimdall_auth_secured ENGINE => PATH, ACTION => RESOURCE, accessible_via_token: EXCEPTION_PASSWORD, EXCEPTION_PATH2: EXCEPTION_PASSWORD2
    • ENGINE - any mountable Engine like Sidekiq::Web
    • PATH - where to mount the engine
    • ACTION & RESOURCE - like any action and resource in cancancan
  • :accessible_via_token -> Defines paths that are available via a particular token. e.g. for Watchdog services like Datadog
    • URL needs then to have the token as ?token=secretpassword in the query params. Like: https://webhook.vesputi-abc.de/sidekiq/stats?token=secretpassword

Installation and Usage

Example: https://gitlab.vesputi.com/netzmap/nanna

0) Commit the empty rails application (and mention the command you used for generating the app)

1) Add this line to your application's Gemfile:

gem 'heimdall_auth'

2) and afterwards do theses commands (yes... second bundle install ist needed, because the install script adds dotenv gem)

bundle install
rails puma_dev:link
rails generate heimdall_auth:install
rails heimdall:register -- -u"[email protected]" -p"HeimdallPassword" >> .env
bundle install
killall puma-dev

3) And please commit directly after executing the lines above so you have clean history

Linking puma_dev

This executes a very simple ln -s command in order to link our application with appropriate naming to the local puma_dev server.

rails puma_dev:link

Heimdall-Auth install scripts

This makes a few steps in order to install heimdall stuff to your app.

rails generate heimdall_auth:install

executes the following generators

  1. rails generate heimdall_auth:cancan
  2. rails generate heimdall_auth:sessions
  3. rails generate heimdall_auth:standard_pages
  4. rails generate heimdall_auth:dotenv

generate heimdall_auth:cancan

This adds the ability.rb file of the cancancan gem with default heimdall roles and adds check_authorization to the application controller. (For details see the cancancan gem)

generate heimdall_auth:sessions

This adds the default heimdall_auth routes for session generation to the routes file, switches the application to https only and lowers the log level.

generate heimdall_auth:standard_pages

This adds the default admin page /admin and two error pages: for invalid_user_data and not_enough_rights.

generate heimdall_auth:dotenv

This adds a default .env.example file (for documentation purposes) to the application and adds the dotenv gem to the gemfile which loads enviroment variables from .env file.

Register at local heimdall

The following command Registeres the service at Heimdall and puts credentials at the end of the .env file

rails heimdall:register -- -u"[email protected]" -p"YourHeimdallPassword" >> .env

Parameters:

-u"[email protected]" # Username in Heimdall (Needs Admin rights)
-p"YourHeimdallPassword" # Password in Heimdall
-h"https://heimdall.vesp" (Optional) - Protocol and Domain the heimdall is found at
-s"https://foo.vesputi-abc.de" # (Optional) - Protocol and Domain the Service is found at

RSpec

If you want to test your Applications controller than you have to give it a User You do so by mocking current_user in ApplicationController

RSpec.describe "/foobar", type: :request do
  before { allow_any_instance_of(ApplicationController).to receive(:current_user) { HeimdallAuth::User.new(is_editor: true) } }
end

Usage with RSpec

Simulate an Admin user

See the example:

require 'rails_helper'

RSpec.describe "/cards", type: :request do

  let(:admin_user) {
    HeimdallAuth::User.new(email: "[email protected]", is_admin: true)
  }

  describe "GET /index" do
    before(:each) do
      allow_any_instance_of( HeimdallAuth::ControllerAdditions ).to receive(:current_user).and_return(admin_user)
    end

    it "renders a successful response" do
      Card.create! valid_attributes
      get cards_url