omniauth-realme 0.1.0

data/README.md

@@ -0,0 +1,177 @@
+# omniauth-realme
+Omniauth strategy for New Zealands secure online identity verification service.
+
+This Gem has been developed for the intension of using [devise](https://github.com/plataformatec/devise) as the account model with Realme SSO intergation.
+This Gem covers all of the SAML client requirements for RealMe intergations including the RealMe's default error messages.
+
+You will need to set up your frontend login pages to match [RealMe's branding guide lines](https://developers.realme.govt.nz/how-to-integrate/application-design-and-branding-guide/realme-page-elements/)
+We suggest you use their assets in a zip file their page.
+
+Getting to Production:
+You will need to complete the [RealMe Operational handover checklist](https://developers.realme.govt.nz/how-to-integrate/getting-to-production/operational-handover-checklist/) `login service` form to gain access to RealMe production environments.
+
+Not Using *ruby* but need to itergrate? Use this gem is a baseline and find a suitable Library on [onelogin's](https://github.com/onelogin) github account.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'devise'
+gem 'omniauth-realme'
+```
+
+And then execute:
+
+    $ bundle
+
+### Realme
+To test that you have installed the Gem correctly intergrate with their message testing servies [RealMe MTS](https://mts.realme.govt.nz/logon-mts/home) first, followed by ITE then Production intergrations.
+
+You will need to be setup your applications intergration via their [developers website](https://developers.realme.govt.nz) for ITE and production set up.
+
+### Devise
+Setup
+```ruby
+# config/initializers/devise.rb
+Devise.setup do |d_config|
+  d_config.omniauth :realme
+end
+```
+
+Here we configure the [ruby-saml](https://github.com/onelogin/ruby-saml) gem.
+Realme provides the nessassery `service-metadata.xml` files for their side of the intergation they can be found on this [page](https://developers.realme.govt.nz/how-realme-works/technical-integration-steps#e75)
+
+```ruby
+# config/initializers/realme_omniauth.rb
+OmniAuth::Strategies::Realme.configure do |config|
+  # Website issuer namespace
+  config.issuer = 'http://myapp/<issuer>/<access>'
+
+  # Callback url
+  config.assertion_consumer_service_url = 'http://myapp.com/users/auth/realme/callback'
+  
+  # Sign the request saml and decrypt response
+  config.private_key = 'Realme SLL private cert'
+
+  # Realme login service xml file.
+  # You will need to download the different XML files for the different environments found here: https://developers.realme.govt.nz/how-realme-works/technical-integration-steps/
+  config.idp_service_metadata = Rails.root.join('path', 'to', 'logon-service-metadata.xml')
+  
+  # default Strenght
+  config.auth_strenght = 'urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:LowStrength'   
+end
+```
+
+Controllers
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  before_action :configure_permitted_parameters, if: :devise_controller?
+  # ...
+
+  private
+
+  def configure_permitted_parameters
+    # :uid, :provider and any new fields need to be added here
+    devise_parameter_sanitizer.permit(:sign_up, keys: [:password, :password_confirmation, :email, :uid, :provider])
+  end
+
+  # ...
+end
+```
+
+The customer `uid` will come through in their session as `session[:uid]`
+
+```ruby
+require 'devise'
+
+module Users
+  class OmniauthCallbacksController < ::Devise::OmniauthCallbacksController
+    skip_before_action :verify_authenticity_token
+
+    def realme
+      return redirect_to new_user_session_path, alert: session.delete(:realme_error)[:message] if session[:realme_error].present? || session[:uid].blank?
+
+      @user = User.from_omniauth('realme', session.delete(:uid))
+
+      unless @user.valid?
+        @user.errors.each { |err| @user.errors.delete(err) }
+
+        flash.notice = 'RealMe login successful, please fill in your user details.'
+        return render 'devise/registrations/new.html.haml'
+      end
+
+      flash.notice = 'RealMe login successful.'
+
+      sign_in_and_redirect @user
+    end
+  end
+end
+```
+
+Views
+  - You will need to update your registration `new` and `edit` views by adding the new fields as well as hidden fields for `provider` and `uid`.
+  - User sign in view will also need to be updated so that it links to the OmniAuth realme pass through using the link helper `user_realme_omniauth_authorize_path`.
+
+Model
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  # Include default devise modules. Others available are:
+  # :confirmable, :lockable, :timeoutable, :trackable and :omniauthable
+  devise :database_authenticatable, :registerable,
+         :recoverable, :rememberable, :validatable,
+         :omniauthable, omniauth_providers: [:realme]
+
+  validates :provider, presence: true
+  validates :uid,      presence: true, uniqueness: true
+  validates :email,    presence: true, uniqueness: true
+
+  def self.from_omniauth(provider, uid)
+    where(provider: provider, uid: uid).first_or_create do |user|
+      user.provider = provider
+      user.uid      = uid
+    end
+  end
+end
+```
+
+Migrations
+  - You will need to add `provider` and `uid` to your model and index the `uid`
+```ruby
+# db/migrate/<timestamp>_devise_create_users.rb
+class DeviseCreateUsers < ActiveRecord::Migration[5.2]
+  def change
+    create_table :users do |t|
+      # ...
+
+      t.string :provider, null: false
+      t.string :uid,      null: false, unique: true
+
+      # ...
+    end
+     # ...
+    add_index :users, :uid, unique: true
+  end
+end
+```
+
+Remove SAMLResponse from Rails log
+```ruby
+#config/initializers/filter_parameter_logging.rb
+Rails.application.config.filter_parameters += [:password, 'SAMLResponse']
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/omniauth-realme.
+
+## License
+  GNU GENERAL PUBLIC LICENSE

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'omniauth/realme'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/omniauth/realme.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'omniauth/realme/version'
+require 'omniauth/strategies/realme'

data/lib/omniauth/realme/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Omniauth
+  module Realme
+    VERSION = '0.1.0'
+  end
+end

data/lib/omniauth/strategies/realme.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'omniauth'
+require 'ruby-saml'
+
+module OmniAuth
+  module Strategies
+    class Realme
+      include OmniAuth::Strategy
+      autoload :AuthRequest, 'omniauth/strategies/realme/auth_request'
+
+      # Fixed OmniAuth options
+      option :provider, 'realme'
+
+      def request_phase
+        req = OneLogin::RubySaml::Authrequest.new
+        redirect req.create(saml_settings, 'SigAlg' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256')
+      end
+
+      def callback_phase
+        response = ::OneLogin::RubySaml::Response.new(request.params['SAMLResponse'], settings: saml_settings)
+
+        if response.is_valid?
+          session[:uid] = response.nameid
+        else
+          authorize_failure
+        end
+
+        @raw_info = response
+        super
+      end
+
+      private
+
+      def saml_settings
+        idp_metadata_parser = OneLogin::RubySaml::IdpMetadataParser.new
+        settings = idp_metadata_parser.parse(File.read(options.fetch('idp_service_metadata')))
+
+          settings.issuer                         = options.fetch('issuer')
+          settings.assertion_consumer_service_url = options.fetch('assertion_consumer_service_url')
+          settings.private_key                    = options.fetch('private_key')
+          settings.authn_context                  = options.fetch('auth_strenght', 'urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:LowStrength')
+          settings.protocol_binding                   = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
+          settings.assertion_consumer_service_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
+          settings.soft = false
+
+          settings.security[:authn_requests_signed] = true
+
+          settings
+      end
+    end
+  end
+end
+
+OmniAuth.config.add_camelization 'realme', 'Realme'

data/omniauth-realme.gemspec

@@ -0,0 +1,33 @@
+
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'omniauth/realme/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'omniauth-realme'
+  spec.version       = Omniauth::Realme::VERSION
+  spec.authors       = ['DanHenton']
+  spec.email         = ['Dan.henton@live.com']
+
+  spec.summary       = 'Omniauth strategy for New Zealands secure online identity verification service.'
+  spec.description   = 'Omniauth strategy for New Zealands secure online identity verification service.'
+  spec.homepage      = 'https://example.com'
+  spec.license       = 'GNU'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'omniauth', '~> 1.0'
+  spec.add_dependency 'uuid', '~> 2.0'
+  spec.add_dependency 'ruby-saml', '~> 1.5'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-realme
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- DanHenton
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-11-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: uuid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ruby-saml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Omniauth strategy for New Zealands secure online identity verification
+  service.
+email:
+- Dan.henton@live.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/omniauth/realme.rb
+- lib/omniauth/realme/version.rb
+- lib/omniauth/strategies/realme.rb
+- omniauth-realme.gemspec
+homepage: https://example.com
+licenses:
+- GNU
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: Omniauth strategy for New Zealands secure online identity verification service.
+test_files: []