Identikey

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.

Requirements

The gem requires the Vasco SDK, that is private intellectual property and cannot be redistributed here. You have to obtain it from VASCO / OneSpan as part of your subscription.

The gem interfaces against a running Identikey server, communicating on port 8888/TCP the SOAP protocol over HTTPS.

Installation

Add this line to your application's Gemfile:

gem 'identikey'

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) 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 to generate the PNG to serve to your users.

Configuration

By default the client expects WSDL files in the current working directory, into ./sdk/wsdl and it connects to an Identikey API endpoint on localhost port 8888 using TLSv1.2. Great for development, but definitely not good for production.

To configure the client, you should at least define where your WSDL files are and where the SOAP endpoint is. Given the WSDL file is different for the two API sets (Authentication and Administration), you need to configure the two classes separately.

Use the .configure method, that will run the block you give to it in the context of the Savon::Globals object as such all available configuration parameters are available as instance methods.

Example:

Identikey::Authentication.configure do
  wsdl     './path/to/your/authentication.wsdl'
  endpoint 'https://your-identikey.example.com:8888'

  # ... more configuration options as needed ...
end

Identikey::Administration.configure do
  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 ...
end

By default, all SOAP requests and responses are logged to log/identikey.log.

If you want to reduce the logging level please use:

Identikey::Authentication.configure do
  log_level :info # or one of [:debug, :warn, :error, :fatal]
end

Or to disable it altogether (not recommended):

Identikey::Authentication.configure do
  log false
end

The configure block accepts all Savon options, for which documentation is available here: http://savonrb.com/version2/globals.html feel free to amend it to suit your needs.

The only option whose semantics differ from the default is filters, as it adds handling the faulty parameter passing design in Identikey, where the same elements are used to transmit different business informations.

By default, sensitive values attribute are filtered out from the logs. Other attributes to filter out can be specified by prefixing them with identikey:.

Example, filter out CREDFLD_PASSWORD and CREDFLD_USERID:

Identikey::Authentication.configure do
  filters [ 'identikey:CREDFLD_PASSWORD', 'identikey:CREDFLD_USERID' ]
end

Please note that the following attributes are filtered out by default:

  • CREDFLD_PASSWORD
  • CREDFLD_STATIC_PASSWORD
  • CREDFLD_SESSION_ID

Please note that if you set your custom filters, these will override the defaults and you should also take care of filtering the above parameters in addition to the ones you want to filter out.

Usage

This is still in alpha stage, as such there is not much documentation. Have a look at the specs for sample usage.

  • Verify an end user OTP
Identikey::Authentication.valid_otp?('username', 'otp')
  • Start an administration session
s = Identikey::Administration::Session.new(username: 'admin', password: 'foobar')
s.logon
  • Find a digipass
d = s.find_digipass('serial')
  • Perform an OTP test
d = d.test_otp('1234567890')
  • Assign a digipass to an user
d.assign! 'username'
  • Unassign a digipass
d.unassign!
  • End an administrative session
s.logoff

Logging to separate files

You can and are encouraged to configure different logging destinations for the different API endpoints, as follows:

Identikey::Administration.configure do
  logger   Logger.new("log/#{Rails.env}.identikey.admin.log")
end

Identikey::Authentication.configure do
  logger   Logger.new("log/#{Rails.env}.identikey.admin.log")
end

However be aware of a caveat, as Identikey uses Savon that uses HTTPI and the latter has a global logger, that Savon sets (and overwrites) upon calls to logger.

In the above scenario, you can use a different logfile for HTTPI:

HTTPI.logger = Logger.new("log/#{Rails.env}.identikey.httpi.log")

However please be aware of side-effects with other components of your application.

Development

After checking out the repo, run bin/setup to install dependencies.

Then, please copy spec/test.env.example into spec/test.env and populate it with your Identikey Authentication Server host, username, password and domain.

You also need the Identikey SDK, that can be placed in sdk/ and its WSDL paths as well referenced in the spec/test.env file.

Then, run rake to run the tests.

You can also run bin/console for an interactive prompt that will allow you to experiment. It requires the same environment variables required by the specs.

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ifad/identikey.

License

The gem is available as open source under the terms of the MIT License.