publishing_platform_sso

This gem provides everything needed to authenticate users and applications in the publishing platform. It is a wrapper around OmniAuth that adds a 'strategy' for OAuth2 integration against AWS Cognito.

Usage

Integration with a Rails app

• Include the gem in your Gemfile:

  gem 'publishing_platform_sso'

• Create a "users" table in the database. Example migration:

  class CreateUsers < ActiveRecord::Migration[7.1]
    def change
      create_table :users do |t|
      t.string :family_name
      t.string :given_name
      t.string :email
      t.string :uid
      t.text :groups

      t.timestamps
      end
    end
  end

• Create a User model with the following:

  serialize :groups, Array

• Add to your ApplicationController:

  include PublishingPlatform::SSO::ControllerMethods
  before_action :authenticate_user!

Securing your application

PublishingPlatform::SSO::ControllerMethods provides some useful methods for your application controllers.

To make sure that only people with an account and permission to use your app are allowed in use authenticate_user!.

class ApplicationController < ActionController::Base
  include PublishingPlatform::SSO::ControllerMethods
  before_action :authenticate_user!
  # ...
end

You can refine authorisation to specific controller actions based on groups using authorise_user!. All groups are assigned via AWS Cognito.

class PublicationsController < ActionController::Base
  include PublishingPlatform::SSO::ControllerMethods
  before_action :authorise_for_editing!, except: [:show, :index]
  # ...
private
  def authorise_for_editing!
    authorise_user!('edit_publications')
  end
end

authorise_user! can be configured to check for multiple groups:

# fails unless the user is in at least one of these groups
authorise_user!(any_of: %w(edit create))

# fails unless the user is in both of these groups
authorise_user!(all_of: %w(edit create))

AWS Cognito makes sure that only users who have been granted access to the application can access it (e.g. they have been added to the signin group for your app).

Authorisation for applications

In addition to the single-sign-on strategy, this gem also allows authorisation via a "bearer token" using the OAuth2 Client Credentials Grant flow. This is used by publishing applications to be authorised to access APIs without the presence of a user.

TODO: provide more information here about scopes etc.

To authorise with a bearer token, a request has to be made with the header:

Authorization: Bearer your-token-here

Use in production mode

To use publishing_platform_sso in production you will need to setup the following environment variables, which we look for in the config. These can be retrieved from AWS Cognito.

Applications that sign in users (single-sign-on).

• SSO_OAUTH_ID
• SSO_OAUTH_SECRET

Applications that access APIs without the presence of a user (Client Credentials Grant flow).

• OAUTH_ID
• OAUTH_SECRET

Use in development mode

In development, you generally want to be able to run an application without needing to run your own SSO server to be running as well. publishing_platform_sso facilitates this by using a 'mock' mode in development. Mock mode loads an arbitrary user from the local application's user tables:

PublishingPlatform::SSO.test_user || PublishingPlatform::SSO::Config.user_klass.first

Extra scopes for applications

By default the mock strategies add the signin scope.

If your application needs different or extra scopes for access, you can specify this by adding the following to your config:

PublishingPlatform::SSO.config do |config|
  # other config here
  config.additional_mock_scopes_required = ["array", "of", "scopes"]
end

Licence

MIT License