OauthIm

The IIAB apps use an OAuth service provider (currently FusionAuth). This gem serves to standardize integration with this service. The hope is that, at some point, we can add this service to the CMS, Kamaji, and related apps.

Installation

Add this line to your application's Gemfile:

gem 'oauth_im', '0.x.y'   # e.g., '0.1.2'

Then run:

$ bundle

Configuration

Once the gem is installed, add an initializer. The iiab app provides an example.

Environment

The ENV variable values can be obtained from the OAuth provider.

  • Here is an article at FusionAuth describing many of these settings.
  • The callback_route setting is used in two related ways:
  • Note that this callback URL must be whitelisted at the provider. At FusionAuth, this is done under the Applications|OAuth tab.
    • For instance, for the app staging-kh-iiab.herokuapp.com, if config.callback_route is set to callback (the default), then the URL https://staging-kh-iiab.herokuapp.com/oauth_im/callback must be entered in the OAuth provider's list of authorized redirect URLs.

RSA v. HMAC

To determine the access token signing key, find the name of the key and then look it up on the Settings|Key Master pane. (See screenshots.)

  • Inspect your app settings. The screenshot shows this being done for the app Kendall Hunt - Terraform.

app settings

  • Find the name of the token. The screenshot shows this being done for the app Kendall Hunt - Terraform. You will need to scroll down the page to the JWT section.

token name

  • Look up this signing token under Home|Settings|Key Master. The screenshot shows this being done for the signing token KendallHunt-Terraform (12).
    • For RSA tokens like this one, use the PEM encoded public key as-is.
    • For HMAC tokens, view the secret under Details (click to reveal).

token name

Usage

Helpers for Logging in and Out

The engine provides two endpoints for logging in and out, and exposes corresponding view helpers. These are accessible from the main app as:

path url
oauth_im.login_path oauth_im.login_url
oauth_im.logout_path oauth_im.logout_url
  • Note that the helpers are namespaced to the engine.

The controller actions for these routes are provided and should "just work." Note that there are no view templates associated with these actions, since requests to them are redirected to the OAuth provider.

Helpers for User ID and Authentication

The gem provides a controller concern, OauthIm::Authenticable, that exposes two helper methods for use in views:

  • authenticated?: returns true if the user has been authenticated by the OAuth service, false otherwise.
  • email: returns the current user's authenticated email address.

You can include this concern in your app's ApplicationController or some other appropriate location, e.g.:

class ApplicationController < ActionController::Base
  include OauthIm::Authenticable

  # etc.
end

Initializer

  • The gem provides a single initializer, AppContext.
  • This module is not name-spaced.

Methods

  • AppContext#provide_authentication? method defaults to true and can be overridden as required.
    • For example, iiab overrides this initializer so that the provide_authentication? method returns false unless the app is kh_iiab (not demo_im).
  • AppContext#privileged? defaults to nil and can be overridden as required.
  • AppContext#authenticate_for_specs offers a way to mock authentication and privilege in specs. It accepts a block.

Gem Maintenance

After many false starts, this repo includes two (seemingly functional) github workflows.

  1. Thanks to this workflow, largely copied from the CMS, the specs should run automatically when a PR is issued.
  2. Thanks to this workflow based on this blog post and using this release phase action, certain so-called conventional commits will result in a so-called release PR.
    • Per the above documentation, to issue such a commit, use the following format for your commit message:
      • fix: a comment about a minor change that corresponds to a SemVar patch
      • feat: a comment about a feature change that corresponds to a SemVar minor
      • fix!: a comment about a breaking change that corresponds to a Semvar major
      • feat!: ditto
    • Once a release PR is accepted and merged, a new PR is created that does several things:
    • If this new PR is accepted and merged, several other things happened:
      • A new tag and github release are created.
      • The new gem version is automatically pushed up to Rubygems.

Notes

  • Because the above process adds new commits to the repository, you should remember to pull them.
  • At Rubygems it is difficult to reuse version numbers for gems. For this reason, you shouldn't try to force-push updates to gem version numbers. Instead, let the automatic process manage versioning for you.

Version History

0.9.3

  • added specs for AppContext initializer

0.9.2

  • Fix redirect url
    • No longer does it take user back to page they were on
    • This caused problems with FusionAuth which wants all redirect URLs whitelisted
  • Update initializer defaults

0.9.1

  • Facilitate specs for privileged users by providing spec_user_data on AppContext

0.9.0

  • Consolidate all OAuth (FusionAuth) functionality
    • the register app can now include this gem for OAuth to create users
    • IIAB can include this gem to authenticate users
    • IIAB can include this gem to determine user privileges
  • Relax Rails version constraint in Gemfile
    • necessary in order for register app to use gem

0.8.2

  • README

0.8.1

  • Tightened up test environment helpers.

0.8.0

  • Allow RSA signing keys in addition to HMAC. This is because Terraform creates RSA keys during runs.

0.7.4

  • Use https protocol for callback in production; http otherwise

0.7.3

  • Cleaned up configuration

0.7.2

  • Using :http protocol in tests (not https)

0.7.1

  • Improving separation of concerns by way of a separate service object to manage oauth client.

0.6.0

  • Remove coupling between gem and iiab app via the AppContext module. Added default AppContext settings to be overridden in client app (in this case, iiab).