identikey 0.7.1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eb968c0e5dd54488d15939d79d81ebccbf7052c93e3da22ff77bad6fc623106
-  data.tar.gz: d90c163b2fdebaf21e6386a721c8f17b4ec0248dd44394e234c646007842a5fd
+  metadata.gz: 7ca7bba53578f15faed142b15d7938712cc93733eb62dce480a139fe42f49a91
+  data.tar.gz: b90c1e4451d845d80c2de47d9bf4ad5e6d17318819b2201aa0afca6f0fcc9090
 SHA512:
-  metadata.gz: 984d1e2f3b20b1d882568d70e338420062ba54b89b26b5f7c9495fd92ee2f5507db7d1da38c4d45662c32fc478c68ac88622d3b69a8c50bb6a617b01a9761d7b
-  data.tar.gz: 1c8092afbd35a441141c9830422a26467fc1fd851cbb9eee3109e8e69edea710de97b1ab22041c66869f5a84ea2bc6a29d6e465142b0dba3727f2453cd0831a5
+  metadata.gz: b1f3749db40bb5656106906424383f94dd05887587bca7897ba68d2c936e8f5ee7641aba9be8730a19a03b37f80c3df5f4cad757308e37d07320e70e0d8e5f28
+  data.tar.gz: 3a4a6ef801813a63153a14c93f8365efd08f2d450fa562a86cc6dc4415a44ede0026168c5a1cc7097de8f3ce48bf8c355084adacbda0d3ab8be89c2ae9adbb16

data/README.md

@@ -1,6 +1,6 @@
 # Identikey
 
-This library is a thin yet incomplete wrapper of the VASCO Identikey SOAP API.
+This library is a thin yet featureful wrapper of the VASCO Identikey SOAP API.
 
 Vasco Identikey has been recently re-branded as OneSpan Authentication Server.
 
@@ -25,6 +25,49 @@ And then execute:
 
     $ bundle
 
+## Features
+
+This client implements the Authentication, Administration and Provisioning
+SOAP APIs.
+
+### Authentication
+
+* `auth_user`: end user authentication with OTP / static password / back-end
+
+
+### Administration
+
+* `logon` / `logoff`: log on or log off an administrative session.
+  You are advised to use a connection pool ([such as
+  mperham's](https://github.com/mperham/connection_pool)) to keep multiple
+  instances of administration sessions alive. This gem is used in production
+  with puma, and has been extensively tested so it is thread-safe.
+
+* `alive?`: checks whether an administrative session is alive. You can use
+  `.logon` again when `.alive?` returns `false`.
+
+* `admin_session_query`: returns active admin sessions
+
+* `user_execute`: `view`, `create`, `update`, `delete`, `reset_password`,
+  `set_password`, and `unlock` user accounts.
+
+* `user_query`: search for users
+
+* `digipass_execute`: `view`, `assign`, `unassign` digipasses
+
+* `digipass_query`: search for digipasses
+
+* `digipassappl_execute`: `test_otp`, `set_pin` on applicable digipasses
+
+
+### Provisioning
+
+* `provisioning_execute`: `mdl_register`, `dsapp_srp_register`. bonus:
+  generation of CRONTO images for online activation, for use with the push
+  notification gateways. You can use [this gem](https://github.com/ifad/cronto)
+  to generate the PNG to serve to your users.
+
+
 ## Configuration
 
 By default the client expects WSDL files in the current working directory,
@@ -53,7 +96,14 @@ Identikey::Authentication.configure do
 end
 
 Identikey::Administration.configure do
-  wsdl     './path/to/your/administrtaion.wsdl'
+  wsdl     './path/to/your/administrtation.wsdl'
+  endpoint 'https://your-identikey.example.com:8888'
+
+  # ... more configuration options as needed ...
+end
+
+Identikey::Provisioning.configure do
+  wsdl     './path/to/your/provisioning.wsdl'
   endpoint 'https://your-identikey.example.com:8888'
 
   # ... more configuration options as needed ...

data/bin/console

@@ -17,6 +17,13 @@ end
 
 puts "Configured Admin WSDL #{ENV.fetch('IK_WSDL_ADMIN')} against #{ENV.fetch('IK_HOST')}"
 
+Identikey::Provisioning.configure do
+  wsdl ENV.fetch('IK_WSDL_PROVN')
+  endpoint ENV.fetch('IK_HOST')
+end
+
+puts "Configured Provisioning WSDL #{ENV.fetch('IK_WSDL_PROVN')} against #{ENV.fetch('IK_HOST')}"
+
 $ik = Identikey::Administration::Session.new(
   username: ENV.fetch('IK_USER'),
   password: ENV.fetch('IK_PASS'),

data/identikey.gemspec

@@ -18,11 +18,10 @@ Gem::Specification.new do |spec|
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) 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 "savon", "~> 2.0"
+  spec.add_dependency "wasabi", "~> 3.5.0"
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", ">= 12.3.3"

data/lib/identikey.rb

@@ -5,3 +5,4 @@ require 'identikey/error'
 require 'identikey/unsigned'
 require 'identikey/authentication'
 require 'identikey/administration'
+require 'identikey/provisioning'

data/lib/identikey/administration.rb

@@ -18,6 +18,10 @@ module Identikey
       :admin_session_query, :user_execute, :user_query,
       :digipass_execute, :digipass_query, :digipassappl_execute
 
+    ###
+    ## LOGON/LOGOFF/PING
+    ###
+
     def logon(username:, password:, domain:)
       resp = super(message: {
         attributeSet: {
@@ -95,6 +99,10 @@ module Identikey
       parse_response resp, :admin_session_query_response
     end
 
+    ###
+    ## USER_EXECUTE
+    ###
+
     def user_execute(session_id:, cmd:, attributes: [])
       resp = super(message: {
         sessionID: session_id,
@@ -180,6 +188,10 @@ module Identikey
       )
     end
 
+    ###
+    ## USER_QUERY
+    ###
+
     # Executes a userQuery command that searches users. By default, it doesn't
     # log anywhere. To enable logging to a specific destination, pass a logger
     # as the log: option. To log to the default destination, pass `true` as
@@ -199,6 +211,9 @@ module Identikey
       end
     end
 
+    ###
+    ## DIGIPASS_EXECUTE
+    ###
 
     def digipass_execute(session_id:, cmd:, attributes: [])
       resp = super(message: {
@@ -245,6 +260,9 @@ module Identikey
       )
     end
 
+    ###
+    ## DIGIPASS_QUERY
+    ###
 
     def digipass_query(session_id:, attributes:, query_options:)
       resp = super(message: {
@@ -258,6 +276,9 @@ module Identikey
       parse_response resp, :digipass_query_response
     end
 
+    ###
+    ## DIGIPASSAPPL_EXECUTE
+    ###
 
     def digipassappl_execute(session_id:, cmd:, attributes:)
       resp = super(message: {
@@ -314,6 +335,5 @@ module Identikey
         client.globals[:log] = old_log
       end
 
-
   end
 end

data/lib/identikey/administration/session.rb

@@ -6,12 +6,21 @@ module Identikey
       attr_reader :session_id, :product, :version
       attr_reader :privileges, :location
 
-      def initialize(username:, password:, domain: 'master')
+      def initialize(username:, password: nil, apikey: nil, domain: 'master')
+        if password.nil? && apikey.nil?
+          raise Identikey::UsageError, "Either a password or an API Key is required"
+        end
+
         @client = Identikey::Administration.new
 
         @username = username
         @password = password
         @domain   = domain
+
+        if apikey
+          @service_user = true
+          @session_id = "Apikey #{username}:#{apikey}"
+        end
       end
 
       def endpoint
@@ -23,6 +32,8 @@ module Identikey
       end
 
       def logon
+        require_classic_user!
+
         stat, sess, error = @client.logon(username: @username, password: @password, domain: @domain)
 
         if stat != 'STAT_SUCCESS'
@@ -42,6 +53,7 @@ module Identikey
       end
 
       def logoff
+        require_classic_user!
         require_logged_on!
 
         stat, _, error = @client.logoff session_id: @session_id
@@ -60,6 +72,8 @@ module Identikey
       end
 
       def alive?(log: true)
+        require_classic_user!
+
         return false unless logged_on?
 
         stat, _ = @client.ping session_id: @session_id, log: log
@@ -108,7 +122,17 @@ module Identikey
       end
 
       def inspect
-        "#<#{self.class.name} sid=#@session_id username=#@username domain=#@domain product=#@product>"
+        descr = if service_user?
+          "SERVICE USER"
+        else
+          "domain=#@domain product=#@product"
+        end
+
+        "#<#{self.class.name} sid=#@session_id username=#@username #{descr}>"
+      end
+
+      def service_user?
+        !!@service_user
       end
 
       alias sid session_id
@@ -123,6 +147,12 @@ module Identikey
         end
       end
 
+      def require_classic_user!
+        if service_user?
+          raise Identikey::UsageError, "This command is not supported with Service users"
+        end
+      end
+
       def parse_privileges(privileges)
         privileges.split(', ').inject({}) do |h, priv|
           privilege, status = priv.split(' ')

data/lib/identikey/administration/user.rb

@@ -161,6 +161,16 @@ module Identikey
         true
       end
 
+      def set_local_auth!(value)
+        ensure_persisted!
+
+        self.local_auth = value
+
+        self.save!
+
+        self
+      end
+
       def unlock!
         ensure_persisted!
 

data/lib/identikey/authentication.rb

@@ -6,11 +6,13 @@ module Identikey
 
     operations :auth_user
 
-    def auth_user(user, domain, otp)
+    def auth_user(user, domain, otp, client = nil)
+      client ||= 'Administration Program'
+
       resp = super(message: {
         credentialAttributeSet: {
           attributes: typed_attributes_list_from(
-            CREDFLD_COMPONENT_TYPE: 'Administration Program',
+            CREDFLD_COMPONENT_TYPE: client,
             CREDFLD_USERID: user,
             CREDFLD_DOMAIN: domain,
             CREDFLD_PASSWORD_FORMAT: Unsigned(0),
@@ -22,18 +24,18 @@ module Identikey
       parse_response resp, :auth_user_response
     end
 
-    def self.valid_otp?(user, domain, otp)
-      status, result, _ = new.auth_user(user, domain, otp)
+    def self.valid_otp?(user, domain, otp, client = nil)
+      status, result, _ = new.auth_user(user, domain, otp, client)
       return otp_validated_ok?(status, result)
     end
 
-    def self.validate!(user, domain, otp)
-      status, result, error_stack = new.auth_user(user, domain, otp)
+    def self.validate!(user, domain, otp, client = nil)
+      status, result, error_stack = new.auth_user(user, domain, otp, client)
 
       if otp_validated_ok?(status, result)
         return true
       else
-        error_message = result['CREDFLD_STATUS_MESSAGE']
+        error_message = result ? result['CREDFLD_STATUS_MESSAGE'] : 'no status returned'
         raise Identikey::OperationFailed.new("OTP Validation error (#{status}): #{error_message}", error_stack)
       end
     end
@@ -52,5 +54,16 @@ module Identikey
     def self.otp_validated_ok?(status, result)
       status == 'STAT_SUCCESS' && !result.key?('CREDFLD_STATUS_MESSAGE')
     end
+
+
+    protected
+      def parse_result_root(body, root_element)
+        root = super
+
+        # The authentication API wraps the results with another element
+        #
+        results_key = root_element.to_s.sub(/_response$/, '_results').to_sym
+        return root[results_key]
+      end
   end
 end

data/lib/identikey/base.rb

@@ -82,6 +82,7 @@ module Identikey
 
       filters: [
         'sessionID',
+        'staticPassword',
         'identikey:CREDFLD_PASSWORD',
         'identikey:CREDFLD_STATIC_PASSWORD',
         'identikey:CREDFLD_SESSION_ID'
@@ -100,7 +101,7 @@ module Identikey
 
       # Parse the generic response types that the API returns.
       #
-      # The returned attributes (up to now...) are always:
+      # The returned attributes in the Administration API are:
       #
       # - The given root element, whose name is derived from the SOAP command
       #   that was invoked
@@ -111,6 +112,11 @@ module Identikey
       #      or multiple ones.
       #   - :error_stack, a list of error that occurred
       #
+      # The authentication API wraps the results element in another one
+      #
+      # The provisioning API uses a status element for the result code and
+      # error stack, and a result element for the results.
+      #
       # The returned value is a three-elements array, containing:
       #
       #   [Response code, Attribute(s) list, Errors list]
@@ -129,11 +135,19 @@ module Identikey
       # 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
+        root = parse_result_root(resp.body, root_element)
+
+        results = parse_result_element(root, root_element)
+
+        result_code       = parse_result_code(results, root_element)
+        result_attributes = parse_result_attributes(results, root_element)
+        result_errors     = parse_result_errors(results, root_element)
 
+        return result_code, result_attributes, result_errors
+      end
+
+      def parse_result_root(body, root_element)
         if body.size.zero?
           raise Identikey::ParseError, "Empty response received"
         end
@@ -144,40 +158,35 @@ module Identikey
 
         # 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
+        return body[root_element]
+      end
 
+      def parse_result_element(root, root_element)
         # The results element
         #
         unless root.key?(:results)
           raise Identikey::ParseError, "Results element not found below #{root_element}"
         end
 
-        results = root[:results]
+        return root[:results]
+      end
 
-        # Result code
-        #
+      def parse_result_code(results, root_element)
         unless results.key?(:result_codes)
           raise Identikey::ParseError, "Result codes not found below #{root_element}"
         end
 
-        result_code = results[:result_codes][:status_code_enum] || 'STAT_UNKNOWN'
+        results[:result_codes][:status_code_enum] || 'STAT_UNKNOWN'
+      end
 
-        # Result attributes
-        #
+      def parse_result_attributes(results, root_element)
         unless results.key?(:result_attribute)
           raise Identikey::ParseError, "Result attribute not found below #{root_element}"
         end
 
         results_attr = results[:result_attribute]
 
-        result_attributes = if results_attr.key?(:attributes)
+        if results_attr.key?(:attributes)
           entries = [ results_attr[:attributes] ].flatten
           parse_attributes entries
 
@@ -193,16 +202,14 @@ module Identikey
         else
           nil
         end
+      end
 
-        # Errors
-        #
-        errors = if results[:error_stack].key?(:errors)
+      def parse_result_errors(results, root_element)
+        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)

data/lib/identikey/provisioning.rb

@@ -0,0 +1,150 @@
+require 'identikey/base'
+
+module Identikey
+  # This class wraps the Provisioning API.
+  #
+  class Provisioning < Base
+    client wsdl: './sdk/wsdl/provisioning.wsdl'
+
+    operations :provisioning_execute, :dsapp_srp_register
+
+    ###
+    ## PROVISIONING_EXECUTE
+    ###
+
+    def provisioning_execute(cmd:, attributes:)
+      resp = super(message: {
+        cmd: cmd,
+        attributeSet: {
+          attributes: attributes
+        }
+      })
+
+      parse_response resp, :provisioning_execute_response
+    end
+
+    def provisioning_execute_MDL_REGISTER(component:, user:, domain:, password:)
+      provisioning_execute(
+        cmd: 'PROVISIONCMD_MDL_REGISTER',
+        attributes: typed_attributes_list_from(
+          PROVFLD_USERID:          user,
+          PROVFLD_DOMAIN:          domain,
+          PROVFLD_COMPONENT_TYPE:  component,
+          PROVFLD_STATIC_PASSWORD: password,
+          PROVFLD_ACTIVATION_TYPE: Unsigned(0),
+        )
+      )
+    end
+
+    ###
+    ## dsappSRPRegister
+    ###
+
+    def dsapp_srp_register(component:, user:, domain:, password:)
+      resp = super(message: {
+        componentType: component,
+        user: {
+          userID: user,
+          domain: domain,
+        },
+        credential: {
+          staticPassword: password
+        }
+      })
+
+      parse_response resp, :dsapp_srp_register_response
+    end
+
+    ###
+    ## Wraps dsapp_srp_register and returns directly the activation
+    ## message through which a CRONTO image can be generated, to be
+    ## used for push notifications setups in combination with a MDC
+    ## configured on your OneSpan control panel and on Identikey.
+    ##
+    ## You may want to look into https://github.com/ifad/cronto for
+    ## a generator to produce PNGs to deliver to your clients.
+    ####
+    def self.cronto_code_for_srp_registration(gateway:, **kwargs)
+      status, result, error = new.dsapp_srp_register(**kwargs)
+
+      if status != 'STAT_SUCCESS'
+        raise Identikey::OperationFailed, "Error while assigning DAL: #{status} - #{[error].flatten.join('; ')}"
+      end
+
+      # Compose proprietary string
+      message = '01;01;%s;%s;%s;%s;%s' % [
+        result[:user][:user_id],
+        result[:user][:domain],
+        result[:registration_id],
+        result[:activation_password],
+        gateway
+      ]
+
+      # Encode it as hex
+      return message.split(//).map {|c| '%x' % c.ord}.join
+    end
+
+    protected
+      # The provisioningExecute command has the same
+      # design as the rest of the API, with a single
+      # multi-purpose `results` element that carries
+      # key-value results.
+      #
+      # Instead, dsappSRPRegister and other commands
+      # use a different design with return types and
+      # values predefined in the WSDL.
+      #
+      # So if we have a `results` element, this is a
+      # old-style response, and we delegate parsing
+      # to the parent class, otherwise if we detect
+      # the `result` and `status` elements, we parse
+      # in this class, basically just returning the
+      # values that Savon parsed for us.
+      #
+      def parse_result_element(root, root_element)
+        if root.key?(:results)
+          root[:results]
+        else
+          root
+        end
+      end
+
+      def parse_result_code(root, root_element)
+        if root.key?(:status)
+          super root[:status], root_element
+        else
+          super
+        end
+      end
+
+      # This may be an old or a new style response.
+      #
+      # New style responses may have both `result`
+      # and `status` elements, or only a `status`
+      # element.
+      #
+      # If there is no `result` but there is a
+      # `status`, then consider this a new style
+      # response and return an empty result. Else,
+      # pass along to the superclass to parse the
+      # old style response.
+      #
+      def parse_result_attributes(root, root_element)
+        if root.key?(:result)
+          root[:result]
+        elsif root.key?(:status)
+          nil
+        else
+          super
+        end
+      end
+
+      def parse_result_errors(root, root_element)
+        if root.key?(:status)
+          super root[:status], root_element
+        else
+          super
+        end
+      end
+  end
+end

data/lib/identikey/version.rb

@@ -1,3 +1,3 @@
 module Identikey
-  VERSION = "0.7.1"
+  VERSION = "0.9.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: identikey
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.9.1
 platform: ruby
 authors:
 - Marcello Barnaba
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2020-06-14 00:00:00.000000000 Z
+date: 2020-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: savon
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: wasabi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -206,6 +220,7 @@ files:
 - lib/identikey/authentication.rb
 - lib/identikey/base.rb
 - lib/identikey/error.rb
+- lib/identikey/provisioning.rb
 - lib/identikey/unsigned.rb
 - lib/identikey/version.rb
 - log/.keep