omniauth-realme 0.1.0 → 0.2.0

data/lib/omniauth/realme.rb

@@ -2,3 +2,50 @@
 
 require 'omniauth/realme/version'
 require 'omniauth/strategies/realme'
+
+module OmniAuth
+  module Realme # :nodoc:
+    class Error < StandardError; end
+
+    ##
+    # Generates SAML SP metadata XML using the same settings you used to
+    # configure the OmniAuth strategy. This XML is suitable for uploading to
+    # Realme at https://mts.realme.govt.nz/logon-mts/metadataupdate
+    #
+    # @param [Hash] options - An optional Hash of options to configure the
+    #                         strategy. This is convenient for testing but is
+    #                         not required during normal operation because the
+    #                         strategy will already be configured by the Rails
+    #                         initializer.
+    # @return [String] SP metadata serialized as an XML string
+    #
+    def self.generate_metadata_xml(options: {})
+      meta = OneLogin::RubySaml::Metadata.new
+
+      # OmniAuth strategies are Rack middlewares. When an instance of a rack
+      # middleware is created it is given a reference to the next rack
+      # app/middleware in the chain. We are only interested here in getting the
+      # SAML settings out of the strategy. We don't hit any code paths which
+      # would require a real rack app/middleware so `nil` works just fine.
+      rack_app = nil
+
+      # The Rails initializer calls `OmniAuth::Strategies::Realme.configure`
+      # which merges the provided block into the default options for
+      # `OmniAuth::Strategies::Realme` - use
+      # `OmniAuth::Strategies::Realme.default_options` to inspect the current
+      # state of these options.
+      #
+      # This means that the `options` we pass in here will be merged into (and
+      # override) those default options.
+      #
+      # When this method is called by app code, we want to use the options set
+      # by the Rails initializer so pass an empty hash as `options`. When this
+      # method is called by its specs, no Rails initializer has run so we need
+      # to pass in some options.
+      #
+      strategy = OmniAuth::Strategies::Realme.new(rack_app, options)
+
+      meta.generate(strategy.saml_settings)
+    end
+  end
+end

data/lib/omniauth/realme/version.rb

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

data/lib/omniauth/strategies/realme.rb

@@ -6,47 +6,268 @@ require 'ruby-saml'
 module OmniAuth
   module Strategies
     class Realme
+      class Error < StandardError; end
+      class RelayStateTooLongError < Error; end
+
+      ##
+      # Create an exception for each documented Realme error
+      # (https://developers.realme.govt.nz/how-realme-works/realme-saml-exception-handling/).
+      #
+      # All the errors we raise inherit from `OmniAuth::Strategies::Realme::Error`
+      # so a caller can rescue that if they want to rescue all exceptions from
+      # this class.
+      #
+      class RealmeAuthnFailedError        < Error; end
+      class RealmeInternalError           < Error; end
+      class RealmeInternalError           < Error; end
+      class RealmeNoAvailableIDPError     < Error; end
+      class RealmeNoPassiveError          < Error; end
+      class RealmeRequestDeniedError      < Error; end
+      class RealmeRequestUnsupportedError < Error; end
+      class RealmeTimeoutError            < Error; end
+      class RealmeUnknownPrincipalError   < Error; end
+      class RealmeUnrecognisedError       < Error; end
+      class RealmeUnsupportedBindingError < Error; end
+
       include OmniAuth::Strategy
-      autoload :AuthRequest, 'omniauth/strategies/realme/auth_request'
+
+      RCMS_LAT_NAME = 'urn:nzl:govt:ict:stds:authn:safeb64:logon_attributes_jwt'
+
+      # The SAML spec says the maximum length of the RelayState is 80
+      # bytes. See section 3.4.3 of
+      # http://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf
+      MAX_LENGTH_OF_RELAY_STATE = 80 # bytes
 
       # Fixed OmniAuth options
       option :provider, 'realme'
 
       def request_phase
+        req_options = { 'SigAlg' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256' }
+
+        ##
+        # If we recieved a `relay_state` param e.g. we were invoked like:
+        #
+        #   redirect_to user_realme_omniauth_authorize_path(relay_state: 'some_value')
+        #
+        # then we pass it to Realme (via RubySaml). Realme (as a SAML IdP)
+        # should return that value unaltered when it redirects back to this
+        # application and `#callback_phase` below is executed.
+        #
+        if request.params['relay_state']
+          if request.params['relay_state'].length > MAX_LENGTH_OF_RELAY_STATE
+            ex = RelayStateTooLongError.new('RelayState exceeds SAML spec max length of 80 bytes')
+
+            # fail!() returns a rack response which this callback must also
+            # return if OmniAuth error handling is to work correctly.
+            return fail!(create_label_for(ex), ex)
+          end
+
+          req_options['RelayState'] = request.params['relay_state']
+        end
+
         req = OneLogin::RubySaml::Authrequest.new
-        redirect req.create(saml_settings, 'SigAlg' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256')
+        redirect req.create(saml_settings, req_options)
       end
 
-      def callback_phase
-        response = ::OneLogin::RubySaml::Response.new(request.params['SAMLResponse'], settings: saml_settings)
+      def callback_phase # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
+        response = ::OneLogin::RubySaml::Response.new(request.params['SAMLResponse'],
+                                                      settings: saml_settings,
+                                                      allowed_clock_drift: allowed_clock_drift)
+
+        ##
+        # `RelayState` is an arbitrary string (length < 80 characters). If we
+        # sent it to Realme with the SAMLRequest then Realme will return it unaltered.
+        #
+        # If we receive any relay state then we save it.
+        #
+        @relay_state = request.params['RelayState'] if request.params['RelayState']
 
+        # If the Realme Context Mapping Service (RCMS) is enabled in Realme
+        # for our app then we will get a RCMS Login Access Token in the
+        # SAMLResponse.
+        #
+        # We save the token if it exists. See
+        # https://developers.realme.govt.nz/how-realme-works/whats-realme-rcms/
+        #
         if response.is_valid?
-          session[:uid] = response.nameid
+          @realme_cms_lat = response.attributes[RCMS_LAT_NAME] if response.attributes[RCMS_LAT_NAME]
+        end
+
+        if legacy_rails_session_behaviour_enabled?
+          OmniAuth.logger.info "Deprecation: omniauth-realme will stop putting values via Rails `session` in a future version. Use request.env['omniauth.auth'] instead." # rubocop:disable Layout/LineLength
+
+          if response.is_valid?
+            session[:uid] = response.nameid
+          else
+            session[:realme_error] = {
+              error: response.errors.join[/=> (\S+) ->/, 1],
+              message: default_error_messages_for_rails_session(response.errors.join)
+            }
+          end
         else
-          authorize_failure
+          if response.is_valid? # rubocop:disable Style/IfInsideElse
+            @uid = response.nameid
+          else
+            ex = create_exception_for(status_code: response.status_code, message: response.status_message.strip)
+
+            # fail!() returns a rack response which this callback must also
+            # return if OmniAuth error handling is to work correctly.
+            return fail!(create_label_for(ex), ex)
+          end
         end
 
-        @raw_info = response
         super
       end
 
-      private
+      ##
+      # The `credentials` Hash will be placed within the `request["omniauth.auth"]`
+      # Hash that `OmniAuth::Strategy` builds. See
+      # https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema
+      #
+      # `credentials` contains any extra credentials information about the user
+      # that we received from the authentication service (Realme) e.g. an RCMS
+      # token if it exists.
+      #
+      credentials do
+        output = {}
+        output[:realme_cms_lat] = @realme_cms_lat if @realme_cms_lat
+        output
+      end
+
+      ##
+      # The `extra` Hash will be placed within the `request["omniauth.auth"]`
+      # Hash that `OmniAuth::Strategy` builds. See
+      # https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema
+      #
+      # `extra` contains anything which isn't information about the user or a
+      # user credential.
+      #
+      extra do
+        output = {}
+        output[:relay_state] = @relay_state if @relay_state
+        output
+      end
+
+      ##
+      # Return the `uid` (User ID) value in a way that allows
+      # OmniAuth::Strategy to place it in the `request["omniauth.auth"]` Hash
+      # that it builds. See
+      # https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema
+      #
+      uid do
+        @uid
+      end
 
-      def saml_settings
+      def saml_settings # rubocop:disable Metrics/AbcSize
         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.issuer                             = options.fetch('issuer')
+        settings.assertion_consumer_service_url     = options.fetch('assertion_consumer_service_url')
+        settings.attributes_index                   = options.fetch('attributes_index', '0')
+        settings.private_key                        = options.fetch('private_key')
+        settings.authn_context                      = options.fetch('auth_strength', '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                               = !options.fetch('raise_exceptions_for_saml_validation_errors', false)
+
+        settings.security[:authn_requests_signed] = true
+
+        ##
+        # Realme error if this is missing from the metadata
+        #
+        #     WantAssertionsSigned must be true (MTS-002)
+        #
+        settings.security[:want_assertions_signed] = true
+
+        ##
+        # Realme MTS requires our Metadata XML to have both:
+        #
+        #     <md:KeyDescriptor use="signing">...</md:KeyDescriptor>
+        #     <md:KeyDescriptor use="encryption">...</md:KeyDescriptor>
+        #
+        # in the metadata XML we submit. We need to set a certificate **and**
+        # set `:want_assertions_encrypted` for ruby-saml to include these
+        # elements.
+        #
+        settings.certificate = options.fetch('certificate')
+        settings.security[:want_assertions_encrypted] = true
+
+        settings
+      end
 
-          settings.security[:authn_requests_signed] = true
+      private
 
-          settings
+      ##
+      # Realme documents the various error conditions it can return:
+      #
+      # https://developers.realme.govt.nz/how-realme-works/realme-saml-exception-handling/
+      #
+      def create_exception_for(status_code:, message:) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+        case status_code
+        when /status:Timeout\z/
+          RealmeTimeoutError.new(message)
+        when /status:InternalError\z/
+          RealmeInternalError.new(message)
+        when /status:AuthnFailed\z/
+          RealmeAuthnFailedError.new(message)
+        when /status:NoAvailableIDP\z/
+          RealmeNoAvailableIDPError.new(message)
+        when /status:NoPassive\z/
+          RealmeNoPassiveError.new(message)
+        when /status:RequestDenied\z/
+          RealmeRequestDeniedError.new(message)
+        when /status:RequestUnsupported\z/
+          RealmeRequestUnsupportedError.new(message)
+        when /status:UnknownPrincipal\z/
+          RealmeUnknownPrincipalError.new(message)
+        when /status:UnsupportedBinding\z/
+          RealmeUnsupportedBindingError.new(message)
+        else
+          RealmeUnrecognisedError.new("Realme login service returned an unrecognised error. status_code=#{status_code} message=#{message}")
+        end
+      end
+
+      ##
+      # The OmniAuth failure endpoint requires us to pass an instance of an
+      # Exception and a String|Symbol describing the error. This method builds
+      # a simple description based on class of the exception.
+      #
+      # This gem can be used in any Rack environment so we don't use any Rails
+      # specific text wrangling methods
+      #
+      # @param [Exception] exception The exception to describe
+      # @return [String] The label describing the exception
+      #
+      def create_label_for(exception)
+        exception.class.to_s.gsub('::', '_')
+      end
+
+      def allowed_clock_drift
+        options.fetch('allowed_clock_drift', 0)
+      end
+
+      def legacy_rails_session_behaviour_enabled?
+        options.fetch('legacy_rails_session_behaviour_enabled', true)
+      end
+
+      def default_error_messages_for_rails_session(error)
+        case error
+        when /Timeout/
+          '<p>Your RealMe session has expired due to inactivity.</p>'
+        when /NoAvailableIDP/
+          "<p>RealMe reported that the TXT service, Google Authenticator or the RealMe token service is not available.</p>
+           <p>You may try again later. If the problem persists, please contact RealMe Help <a href='tel:'0800664774>0800 664 774</a>.</p>"
+        when /AuthnFailed/
+          '<p>You have chosen to leave the RealMe login screen without completing the login process.</p>'
+        when /InternalError/
+          "<p>RealMe was unable to process your request due to a RealMe internal error.</p>
+              <p>Please try again. If the problem persists, please contact RealMe Help Desk on <a href='tel:'0800664774>0800 664 774</a>.</p>"
+        else
+          "<p>RealMe reported a serious application error with the message:</p>
+              <p>#{error}</p>
+              <p>Please try again later. If the problem persists, please contact RealMe Help Desk on <a href='tel:'0800664774>0800 664 774</a>.</p>"
+        end
       end
     end
   end

data/omniauth-realme.gemspec

@@ -1,33 +1,42 @@
-
 # frozen_string_literal: true
 
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'omniauth/realme/version'
+require_relative 'lib/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.version       = OmniAuth::Realme::VERSION
+  spec.authors       = ['DigitalNZ']
+  spec.email         = ['info@digitalnz.org']
 
   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.homepage      = 'https://github.com/omniauth/omniauth'
   spec.license       = 'GNU'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
+
+  # spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/omniauth/omniauth'
 
-  spec.files = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |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_dependency 'uuid', '~> 2.0'
 
   spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'pry-byebug'
+  spec.add_development_dependency 'rack-test'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-realme
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
-- DanHenton
-autorequire: 
+- DigitalNZ
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2018-11-12 00:00:00.000000000 Z
+date: 2020-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: omniauth
@@ -25,33 +25,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: uuid
+  name: ruby-saml
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.5'
 - !ruby/object:Gem::Dependency
-  name: ruby-saml
+  name: uuid
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  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: rack-test
+  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
@@ -94,22 +122,50 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  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: rubocop-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
+- info@digitalnz.org
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - ".ruby-version"
-- ".travis.yml"
 - Gemfile
 - Gemfile.lock
-- LICENSE
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -119,11 +175,13 @@ files:
 - lib/omniauth/realme/version.rb
 - lib/omniauth/strategies/realme.rb
 - omniauth-realme.gemspec
-homepage: https://example.com
+homepage: https://github.com/omniauth/omniauth
 licenses:
 - GNU
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/omniauth/omniauth
+  source_code_uri: https://github.com/omniauth/omniauth
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -131,16 +189,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.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: 
+rubygems_version: 3.0.3
+signing_key:
 specification_version: 4
 summary: Omniauth strategy for New Zealands secure online identity verification service.
 test_files: []