WWPass-ruby-sdk

The WWPass Ruby SDK allows a service provider to provide authentication using WWPass. WWPass's Authentication Service is an alternative to or replacement for other authentication methods such as username and password. The Authentication Service works with the WWPass PassKey or WWPass PassKey Lite application on your smart phone.

The WWPass PassKey or WWPass PassKey Lite is a requirement for user authentication. PassKey is a hardware device that enables authentication and access for a given user. A major component of the WWPass authentication capability is the software that supports the PassKey itself. Without this software, requests to an end user to authenticate their identity will fail since this software is used to directly access information stored on the PassKey and communicate with WWPass. To allow Administrator testing of the authentication infrastructure, this client software and an accompanying PassKey is required. PassKey Lite is an application for Android and iOS smartphones and tablets. The application is used to scan QR codes to authenticate into WWPass-enabled sites. Alternatively, when browsing with these mobile devices, you can tap the QR code image to authenticate into the site to access protected information directly on your phone or tablet. For more information about how to obtain a PassKey and register it, please refer to the WWPass web site (http://www.wwpass.com)

The WWPass Python SDK is licensed under the Apache 2.0 license. This license applies to all source code, code examples and accompanying documentation contained herein. You can modify and re-distribute the code with the appropriate attribution. This software is subject to change without notice and should not be construed as a commitment by WWPass.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, the software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

If you encounter a problem or have a question, you can contact the WWPass Service Desk as follows: Phone - 1-888-WWPASS1 (+1-888-997-2771) Email - support@wwpass.com Online - Support form

Add this line to your application's Gemfile:

gem 'wwpass-ruby-sdk'

And then execute:

$ bundle

Or install it yourself as:

$ gem install wwpass-ruby-sdk

WWPass requires access to the certificates that were installed as part of your WWPass installation as described here. We recommend creating a configuration file like config/wwpass.yml with contents like

default: &default
  :sp_name: 'your_sp_name'
  :cert_file: '/etc/ssl/certs/your_sp_name.crt'
  :key_file: '/etc/ssl/certs/your_sp_name.key'
  :cert_ca: '/etc/ssl/certs/wwpass.ca.cer'
development:
  <<: *default
test: 
  <<: *default
production: 
  <<: *default

You can then create code (typically in a controller class) that connects to the WWPass Service Provider Front End (spfe) and, for example, fetches a ticket:

begin
  @connection = WWPassRubySDK::WWPassConnection.new(WWPASS_CONFIG[:cert_file], WWPASS_CONFIG[:key_file], WWPASS_CONFIG[:cert_ca])
rescue WWPassException => e
  # Handle exception
end
@ticket = @connection.get_ticket(':p')    # Requires access code entry

After checking out the repo, run bin/setup to install dependencies. 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.

Bug reports and pull requests are welcome on GitHub at https://github.com/wwpass/wwpass-ruby-sdk.

WWPASSConnection(cert_file, key_file, cafile, timeout, spfe_addr)

WWPassConnection is the class for a WWPass SPFE connection, and a new connection is initiated every time a connection request is made. The WWPass CA certificate is required for validating the SPFE certificate and can be downloaded at https://developers.wwpass.com/downloads/wwpass.ca

getName()

Gets the service provider name on the certificate which was used initiate this WWPassConnection instance.

The service provider name

WWPassException is thrown if there is an internal formatting error

getTicket(auth_type, ttl)

Gets a newly-issued ticket from SPFE. This ticket is required in all other functions.

Ticket string

getPUID(ticket, auth_type)

Gets the id of the user from the Service Provider Front End. This ID is unique for each Service Provider.

User ID

putTicket(ticket, ttl, auth_type)

Checks the authentication of the ticket and may issue a new ticket from SPFE. All subsequent operations should use a returned ticket instead of one provided to putTicket.

Possibly new ticket

The new ticket should be used in further operations with the SPFE.  

readData(ticket, container)

Requests data stored in the user’s data container.

Data string

readDataAndLock(ticket, lock_timeout, container)

Requests data stored in the user’s data container and tries to atomically lock an associated lock.

Data string

writeData(ticket, data, container)

Write data into the user’s data container.

(True, None) or (False, <error message>)

writeDataAndUnlock(ticket, data, container)

Writes data into the user's data container and unlocks an associated lock. If the lock is already unlocked, the write will succeed, but the function will return an appropriate error.

lock(ticket, lockTimeout, lockid)

Tries to lock a lock identified by the user (by authenticated ticket) and lock ID.

unlock(ticket, lockid)

Tries to unlock a lock identified by the user (by authenticated ticket) and lock ID.