sorah/clarion repository overview

⁠Clarion: Web-based FIDO U2F helper for CLI operations (e.g. SSH Log in)

Clarion is a web-based frontend to allow remote,non-browser operations (CLI) to perform 2FA on their users.

⁠How it works

Any software/scripts want to perform 2FA (app) creates a request on Clarion. Then app requests user to visit a request specific path on Clarion. Clarion then performs 2FA on behalf of app, and finally returns an authentication result to app.

Clarion also provides a way to retrieve user's U2F keyhandle and public key.

Note that Clarion itself doesn't manage users' keyhandle and public key. User information should be provided every time when requesting authentication.

⁠Set up

Clarion is a Rack application. Docker image is also available.

See config.ru⁠ for detailed configuration. The following environment variable is supported by the bundled config.ru.

• SECRET_KEY_BASE (required)
• CLARION_REGISTRATION_ALLOWED_URL (required): Regexp that matches against URLs. Only matched URLs are allowed for key registration callback.
• CLARION_AUTHN_DEFAULT_EXPIRES_IN (default: 300): authn lifetime in seconds.
• CLARION_STORE (required, default: s3): See docs/stores.md⁠
• S3 store:
  • CLARION_STORE_S3_BUCKET
  • CLARION_STORE_S3_REGION
  • CLARION_STORE_S3_PREFIX (optional, recommended to end with /)
• CLARION_COUNTER (optional, default: dynamodb): See docs/counters.md⁠
  • CLARION_COUNTER_DYNAMODB_TABLE
  • CLARION_COUNTER_DYNAMODB_REGION

⁠Usage

⁠Real world example: SSH log in

See ./examples/pam-u2f⁠

⁠Test implementation

Visit /test exists in your application. This endpoint doesn't work for multi-process/multi-threaded deployment.

See app/views/test.erb⁠, app/views/test_callback.erb⁠, app/public/test.js⁠ for implementation.

⁠API

See docs/api.md⁠

⁠Development

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

⁠To-dos

• Write an integration test
• Write a unit test

⁠Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sorah/clarion⁠.

⁠License

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