TagAuth

TagAuth is a Ruby gem designed to integrate tag-based authentication into Rails applications using Devise. This gem is particularly suitable for web applications deployed on kiosks.

TagAuth supports two methods of tag-based authentication:

  1. Direct Input (Ideal for Keyboard-Emulating Readers):

    • For kiosks with readers acting as keyboards, tags can be directly input into a designated field (to be implemented by the user of this gem).
    • This method utilizes the custom Devise strategy generated by TagAuth.

  2. External Reader Endpoint (For Serial Readers):

    • For kiosks where the reader cannot directly communicate with the web application, TagAuth provides an endpoint in the generated controller.
    • An external client or script operating the reader can access this endpoint to receive a one-time authentication token linked to a user's tag.
    • The client can then open a browser with a URL in the format www.some-web-app.com/tag_auth_tokens?token=received_token to authenticate the user.
    • TagAuth includes a sample Powershell script for Windows kiosks, demonstrating how to listen to a reader communicating via a serial port.

Installation

Add this line to your application's Gemfile:

gem 'tag_auth'

And then execute:

bundle install

Usage

TagAuth provides generators to set up the necessary components for tag-based authentication. Ensure you have Devise installed and configured in your Rails application before proceeding.

  1. TagAuth Generator: Generates a migration to add auth_tag, authentication_token, and authentication_token_valid_to columns to your model, along with necessary indexes.
   rails generate tag_auth:tag_auth [MODEL_NAME]

Replace [MODEL_NAME] with the name of your model (e.g., User) you wish to authenticate with a tag..

  1. TagAuthenticable Generator: Generates a custom Devise strategy for tag-based authentication. It is used for the direct inputs readers described above.
   rails generate tag_auth:tag_authenticable [MODEL_NAME]

Again, replace [MODEL_NAME] with the model name.

  1. Controller Generator: Generates a controller and initializer to handle tag-based authentication. It is the center point handling the authentication. To integrate with external readers, it uses the simple_token_authentication gem. It enhances token validation of the gem to include time-based validity checks.
   rails generate tag_auth:controller [MODEL_NAME]

Replace [MODEL_NAME] with the model name. Make sure you call it on the same model each time.

Authentication middleware

In the scripts directory, there is an example Powershell script that demonstrates how to connect the reader with the web application. In the script, replace the example URI with your own. Alternatively, adjust the reader properties to fit your usage. This script can be inserted into Windows Task that starts running after the user login. To register the task, open the Task scheduler and create a new task. Set up the trigger for the task ("At user log on" is recommended) and add new Action that will run the Powershell script. In the Program/Script option, insert PowerShell -File "path-to-your-ps-script".

Contributing

Contributions to TagAuth are welcome! Please follow the standard procedures for contributing to open-source projects.

License

TagAuth is released under MIT License.