identikey 0.3.0

data/lib/identikey/administration.rb

@@ -0,0 +1,211 @@
+require 'identikey/base'
+require 'identikey/administration/session'
+require 'identikey/administration/session_query'
+require 'identikey/administration/digipass'
+require 'identikey/administration/user'
+
+module Identikey
+  # This class wraps the Administration API wsdl, that contains dozens of
+  # methods. It is currently monolithic.
+  #
+  # It's the lower level into the Administration API, while its models are
+  # wrapped in separate clasess.
+  #
+  class Administration < Base
+    client wsdl: './sdk/wsdl/administration.wsdl'
+
+    operations :logon, :logoff, :sessionalive,
+      :admin_session_query, :user_execute,
+      :digipass_execute, :digipassappl_execute
+
+    def logon(username:, password:, domain:)
+      resp = super(message: {
+        attributeSet: {
+          attributes: typed_attributes_list_from(
+            CREDFLD_DOMAIN:          domain,
+            CREDFLD_PASSWORD:        password,
+            CREDFLD_USERID:          username,
+            CREDFLD_PASSWORD_FORMAT: Unsigned(0)
+          )
+        }
+      })
+
+      parse_response resp, :logon_response
+    end
+
+    def logoff(session_id:)
+      resp = super(message: {
+        attributeSet: {
+          attributes: typed_attributes_list_from(
+            CREDFLD_SESSION_ID: session_id
+          )
+        }
+      })
+
+      parse_response resp, :logoff_response
+    end
+
+    def sessionalive(session_id:)
+      resp = super(message: {
+        attributeSet: {
+          attributes: typed_attributes_list_from(
+            CREDFLD_SESSION_ID: session_id
+          )
+        }
+      })
+
+      parse_response resp, :sessionalive_response
+    end
+
+    def admin_session_query(session_id:)
+      attributes = [ ]
+
+      # These doesn't seem to work as described by the WSDL.
+      # if q_idx
+      #   attributes.push(attributeID: 'ADMINSESSIONFLD_SESSION_IDX',
+      #                   value: { '@xsi:type': 'xsd:string', content!: q_idx})
+      # end
+
+      # if q_location
+      #   attributes.push(attributeID: 'ADMINSESSIONFLD_LOCATION',
+      #                   value: { '@xsi:type': 'xsd:string', content!: q_location})
+      # end
+
+      # if q_username
+      #   attributes.push(attributeID: 'ADMINSESSIONFLD_LOGIN_NAME',
+      #                   value: { '@xsi:type': 'xsd:string', content!: q_username})
+      # end
+
+      resp = super(message: {
+        sessionID: session_id,
+        attributeSet: {
+          attributes: attributes
+        }
+        # fieldSet: { ... }
+        # queryOptions: { ... }
+      })
+
+      parse_response resp, :admin_session_query_response
+    end
+
+    def user_execute(session_id:, cmd:, attributes: [])
+      resp = super(message: {
+        sessionID: session_id,
+        cmd: cmd,
+        attributeSet: {
+          attributes: attributes
+        }
+      })
+
+      parse_response resp, :user_execute_response
+    end
+
+    def user_execute_VIEW(session_id:, username:, domain:)
+      user_execute(
+        session_id: session_id,
+        cmd: 'USERCMD_VIEW',
+        attributes: typed_attributes_list_from(
+          USERFLD_USERID: username,
+          USERFLD_DOMAIN: domain
+        )
+      )
+    end
+
+    def user_execute_CREATE(session_id:, attributes:)
+      user_execute(
+        session_id: session_id,
+        cmd: 'USERCMD_CREATE',
+        attributes: typed_attributes_list_from(attributes)
+      )
+    end
+
+    def user_execute_UPDATE(session_id:, attributes:)
+      user_execute(
+        session_id: session_id,
+        cmd: 'USERCMD_UPDATE',
+        attributes: typed_attributes_list_from(attributes)
+      )
+    end
+
+    def user_execute_DELETE(session_id:, username:, domain:)
+      user_execute(
+        session_id: session_id,
+        cmd: 'USERCMD_DELETE',
+        attributes: typed_attributes_list_from(
+          USERFLD_USERID: username,
+          USERFLD_DOMAIN: domain
+        )
+      )
+    end
+
+    def digipass_execute(session_id:, cmd:, attributes: [])
+      resp = super(message: {
+        sessionID: session_id,
+        cmd: cmd,
+        attributeSet: {
+          attributes: attributes
+        }
+      })
+
+      parse_response resp, :digipass_execute_response
+    end
+
+    def digipass_execute_VIEW(session_id:, serial_no:)
+      digipass_execute(
+        session_id: session_id,
+        cmd: 'DIGIPASSCMD_VIEW',
+        attributes: typed_attributes_list_from(
+          DIGIPASSFLD_SERNO: serial_no
+        )
+      )
+    end
+
+    def digipass_execute_UNASSIGN(session_id:, serial_no:)
+      digipass_execute(
+        session_id: session_id,
+        cmd: 'DIGIPASSCMD_UNASSIGN',
+        attributes: typed_attributes_list_from(
+          DIGIPASSFLD_SERNO: serial_no
+        )
+      )
+    end
+
+    def digipass_execute_ASSIGN(session_id:, serial_no:, username:, domain:, grace_period: 0)
+      digipass_execute(
+        session_id: session_id,
+        cmd: 'DIGIPASSCMD_ASSIGN',
+        attributes: typed_attributes_list_from(
+          DIGIPASSFLD_SERNO: serial_no,
+          DIGIPASSFLD_ASSIGNED_USERID: username,
+          DIGIPASSFLD_DOMAIN: domain,
+          DIGIPASSFLD_GRACE_PERIOD_DAYS: grace_period
+        )
+      )
+    end
+
+    def digipassappl_execute(session_id:, cmd:, attributes:)
+      resp = super(message: {
+        sessionID: session_id,
+        cmd: cmd,
+        attributeSet: {
+          attributes: attributes
+        }
+      })
+
+      parse_response resp, :digipassappl_execute_response
+    end
+
+    def digipassappl_execute_TEST_OTP(session_id:, serial_no:, appl:, otp:)
+      digipassappl_execute(
+        session_id: session_id,
+        cmd: 'DIGIPASSAPPLCMD_TEST_OTP',
+        attributes: typed_attributes_list_from(
+          DIGIPASSAPPLFLD_SERNO: serial_no,
+          DIGIPASSAPPLFLD_APPL_NAME: appl,
+          DIGIPASSAPPLFLD_RESPONSE: otp
+        )
+      )
+    end
+
+  end
+end

data/lib/identikey/authentication.rb

@@ -0,0 +1,56 @@
+require 'identikey/base'
+
+module Identikey
+  class Authentication < Base
+    client wsdl: './sdk/wsdl/authentication.wsdl'
+
+    operations :auth_user
+
+    def auth_user(user, domain, otp)
+      resp = super(message: {
+        credentialAttributeSet: {
+          attributes: typed_attributes_list_from(
+            CREDFLD_COMPONENT_TYPE: 'Administration Program',
+            CREDFLD_USERID: user,
+            CREDFLD_DOMAIN: domain,
+            CREDFLD_PASSWORD_FORMAT: Unsigned(0),
+            CREDFLD_PASSWORD: otp
+          )
+        }
+      })
+
+      parse_response resp, :auth_user_response
+    end
+
+    def self.valid_otp?(user, domain, otp)
+      status, result, _ = new.auth_user(user, domain, otp)
+      return otp_validated_ok?(status, result)
+    end
+
+    def self.validate!(user, domain, otp)
+      status, result, _ = new.auth_user(user, domain, otp)
+
+      if otp_validated_ok?(status, result)
+        return true
+      else
+        error_message = result['CREDFLD_STATUS_MESSAGE']
+        raise Identikey::Error, "OTP Validation error (#{status}): #{error_message}"
+      end
+    end
+
+    # Given an authentication status and result message, returns true if
+    # that defines a successful OTP validation or not.
+    #
+    # For all cases, except where the OTP is "push", Identikey returns a
+    # status that is != than `STAT_SUCCESS`. But when the OTP is "push",
+    # then Identikey returns a `STAT_SUCCESS` with a "password is wrong"
+    # message in the `CREDFLD_STATUS_MESSAGE`.
+    #
+    # This method checks for both cases.. Success means a `STAT_SUCCESS`
+    # and nothing in the `CREDFLD_STATUS_MESSAGE`.
+    #
+    def self.otp_validated_ok?(status, result)
+      status == 'STAT_SUCCESS' && !result.key?('CREDFLD_STATUS_MESSAGE')
+    end
+  end
+end

data/lib/identikey/base.rb

@@ -0,0 +1,272 @@
+module Identikey
+
+  class Base
+    extend Savon::Model
+
+    def self.configure(&block)
+      self.client.globals.instance_eval(&block)
+
+      # Work around a sillyness in Savon
+      if client.globals[:wsdl] != client.wsdl.document
+        client.wsdl.document = client.globals[:wsdl]
+      end
+    end
+
+    def self.client(options = nil)
+      return super() unless options
+
+      options = DEFAULTS.merge(options)
+      options = process_identikey_filters(options)
+
+      super options
+    end
+
+    def self.default_user_agent_header
+      {'User-Agent' => "ruby/identikey #{Identikey::VERSION}"}
+    end
+
+    # Loops over the filters option content and adds Identikey
+    # specific parameter filtering.
+    #
+    # Due to faulty design in the Identikey SOAP endpoint, the
+    # parameter filters require context-dependant logic as all
+    # attributes are passed in `<attributeID>` elements, while
+    # all values are passed in `<value>` elements.
+    #
+    # Identikey attributes to filter out are specified in the
+    # `filters` option with the `identikey:` prefix.
+    #
+    # Example, filter out the `CREDFLD_PASSWORD` field from
+    # the logs (done by default):
+    #
+    # configure do
+    #   filters [ 'identikey:CREDFLD_PASSWORD' ]
+    # end
+    #
+    def self.process_identikey_filters(options)
+      filters = options[:filters] || []
+
+      options[:filters] = filters.map do |filter|
+        if filter.to_s =~ /^identikey:(.+)/
+          filter = identikey_filter_proc_for($1)
+        end
+
+        filter
+      end
+
+      return options
+    end
+
+    def self.identikey_filter_proc_for(attribute)
+      lambda do |document|
+        document.xpath("//attributeID[text()='#{attribute}']/../value").each do |node|
+          node.content = '***FILTERED***'
+        end
+      end
+    end
+
+    DEFAULTS = {
+      endpoint: 'https://localhost:8888/',
+
+      ssl_version: :TLSv1_2,
+      ssl_verify_mode: :none,
+
+      headers: default_user_agent_header,
+
+      encoding: 'UTF-8',
+
+      logger: Logger.new('log/identikey.log'),
+      log_level: :debug,
+      log: true,
+      pretty_print_xml: true,
+
+      filters: [
+        'identikey:CREDFLD_PASSWORD',
+        'identikey:CREDFLD_STATIC_PASSWORD',
+        'identikey:CREDFLD_SESSION_ID'
+      ]
+    }.freeze
+
+    def endpoint
+      self.class.client.globals[:endpoint]
+    end
+
+    def wsdl
+      self.class.client.globals[:wsdl]
+    end
+
+    protected
+
+      # Parse the generic response types that the API returns.
+      #
+      # The returned attributes (up to now...) are always:
+      #
+      # - The given root element, whose name is derived from the SOAP command
+      #   that was invoked
+      # - The :results element, containing:
+      #   - :result_codes, containing :status_code_enum that is the operation
+      #     result code
+      #   - :result_attribute, that may either contain a single attributes list
+      #      or multiple ones.
+      #   - :error_stack, a list of error that occurred
+      #
+      # The returned value is a three-elements array, containing:
+      #
+      #   [Response code, Attribute(s) list, Errors list]
+      #
+      # The response code is a string from the IDENTIKEY Authentication Server
+      # Error Codes table.
+      #
+      # The attributes list is an Hash when a single object's attributes were
+      # requested, or is an Array of Hashes when the response contains a list
+      # of objects.
+      #
+      # The attributes list may be nil.
+      #
+      # The errors list is an array of strings containing error descriptions.
+      # The strings themselves contain the error code, albeit in different
+      # formats. TODO maybe create a separate class for errors, that includes
+      # the error code.
+      #
+      # TODO refactor and split in separate methods
+      #
+      def parse_response(resp, root_element)
+        body = resp.body
+
+        if body.size.zero?
+          raise Identikey::Error, "Empty response received"
+        end
+
+        unless body.key?(root_element)
+          raise Identikey::Error, "Expected response to have #{root_element}, found #{body.keys.join(', ')}"
+        end
+
+        # The root results element
+        #
+        root = body[root_element]
+
+        # ... that the authentication API wraps with another element
+        #
+        results_key = root_element.to_s.sub(/_response$/, '_results').to_sym
+        if root.keys.size == 1 && root.key?(results_key)
+          root = root[results_key]
+        end
+
+        # The results element
+        #
+        unless root.key?(:results)
+          raise Identikey::Error, "Results element not found below #{root_element}"
+        end
+
+        results = root[:results]
+
+        # Result code
+        #
+        unless results.key?(:result_codes)
+          raise Identikey::Error, "Result codes not found below #{root_element}"
+        end
+
+        result_code = results[:result_codes][:status_code_enum] || 'STAT_UNKNOWN'
+
+        # Result attributes
+        #
+        unless results.key?(:result_attribute)
+          raise Identikey::Error, "Result attribute not found below #{root_element}"
+        end
+
+        results_attr = results[:result_attribute]
+
+        result_attributes = if results_attr.key?(:attributes)
+          entries = [ results_attr[:attributes] ].flatten
+          parse_attributes entries
+
+        elsif results_attr.key?(:attribute_list)
+          # This attribute may contain a single entry or multiple ones. Lists of
+          # a single element are returned as a single attributes set.. but the
+          # caller expects a list so we return the single element in an Array.
+          #
+          entries = [ results_attr[:attribute_list] ].flatten
+          entries.inject([]) do |a, entry|
+            a.push parse_attributes(entry[:attributes])
+          end
+        else
+          nil
+        end
+
+        # Errors
+        #
+        errors = if results[:error_stack].key?(:errors)
+          parse_errors results[:error_stack][:errors]
+        else
+          nil
+        end
+
+        return result_code, result_attributes, errors
+      end
+
+      def parse_attributes(attributes)
+        attributes.inject({}) do |h, attribute|
+          h.update(attribute.fetch(:attribute_id) => attribute.fetch(:value))
+        end
+      end
+
+      def parse_errors(errors)
+        case errors
+        when Array
+          errors.map { |e| e.fetch(:error_desc) }
+        when Hash
+          errors.fetch(:error_desc)
+        end
+      end
+
+      # Converts and hash keyed by attribute name into an array of hashes
+      # whose keys are the attribute name as attributeID and the value as
+      # a Gyoku-compatible hash with the xsd:type annotation. The type is
+      # inferred from the Ruby value type and the contents are serialized
+      # as a string formatted as per the XSD DTD definition.
+      #
+      # <rant>
+      # This code should not exist, because defining argument types is what
+      # WSDL is for.  However, in the braindead web services implementation
+      # of Vasco there are infinite protocols that accept a variable number
+      # of attributes and their types are defined only in the documentation
+      # and in server code, making WSDL (and SOAP) only an annoynace rather
+      # than an aid.
+      # </rant>
+      #
+      def typed_attributes_list_from(hash)
+        hash.map do |name, value|
+          type, value = case value
+
+          when Unsigned
+            [ 'xsd:unsignedInt', value.to_s ]
+
+          when Integer
+            [ 'xsd:int', value.to_s ]
+
+          when DateTime, Time
+            [ 'xsd:datetime', value.utc.iso8601 ]
+
+          when TrueClass, FalseClass
+            [ 'xsd:boolean', value.to_s ]
+
+          when Symbol, String
+            [ 'xsd:string', value.to_s ]
+
+          when NilClass
+            next
+
+          else
+            raise Identikey::Error, "#{name} type #{value.class} is unsupported"
+          end
+
+          { attributeID: name.to_s,
+            value: { '@xsi:type': type, content!: value } }
+        end.compact
+      end
+
+    # protected
+
+  end
+
+end

data/lib/identikey/unsigned.rb

@@ -0,0 +1,28 @@
+#
+# Wrapper for an integer immediate value, that is used only as an annotation
+# for typed_attributes_list_from() in order to generate the correct XSD type
+# from an Object's class.
+#
+class Unsigned < BasicObject
+  def initialize(value)
+    @int = ::Kernel::Integer(value)
+
+    if @int < 0
+      raise ArgumentError, "Invalid input syntax for Unsigned integer: #{value}"
+    end
+  end
+
+  def class
+    ::Unsigned
+  end
+
+  def method_missing(meth, *args, &block)
+    @int.public_send(meth, *args, &block)
+  end
+end
+
+module Kernel
+  def Unsigned(value)
+    ::Unsigned.new(value)
+  end
+end

data/lib/identikey/version.rb

@@ -0,0 +1,3 @@
+module Identikey
+  VERSION = "0.3.0"
+end

data/lib/identikey.rb

@@ -0,0 +1,10 @@
+require 'savon'
+
+require 'identikey/version'
+require 'identikey/unsigned'
+require 'identikey/authentication'
+require 'identikey/administration'
+
+module Identikey
+  class Error < StandardError; end
+end