Keycard provides authentication support and user/request information, especially in Rails applications.
Keycard is designed to give you sound guidelines and integration between authentication and authorization without constraining your application. It takes inspiration from Sorcery, but has four important distinctions:
- It does not use mixins to configure a "model that can log in".
- It provides a way to retrieve user and session attributes like directory information or IP address-based region, rather than being strictly about logging in and out.
- It only provides one built-in strategy for logins, focused on single sign-on scenarios.
- It offers an optional group implementation for whatever objects your application manages as accounts or users.
The ultimate goal is to provide useful tools that integrate easily and simplify building applications that have clean, well-factored designs. Keycard should help you focus on solving your application problems, while remaining invisible -- not magical -- to most of your application.
Add this line to your application's Gemfile:
And then execute:
There are two aspects of Keycard that are configurable: the database for IP ranges as they map to institutions (IP blocks map to networks, and networks are associated with institutions), and the access mode (whether your application is served directly or behind a reverse proxy). These will be unified eventually, but for now, they are configured separately.
For the Database
For the database, there is a Railtie that, when running in a Rails app,
attempts to use the same connection information as ActiveRecord. If you are
running in this configuration, you will need to run a
rake db:migrate to
create the Keycard tables and add them to your
db/schema.rb. From there forward,
db:schema:load will create these tables for you. There is
keycard:migrate Rake task if you want to run it separately, but it hooks into
db:migrate by default for convenience.
If you need to customize the database configuration, which will be typical for
at least the production environment, the easiest way is to define an
initializer. In a multi-application environment, the database may be read-only,
which will require the
Keycard::DB.config to have its
readonly property set
true. You can also set either the
Keycard::DB.config.opts to the options
to pass to the Sequel connection or set
Keycard::DB.config.url to use a
connction string. The latter is equivalent to setting the
For the Access Mode
To extract the username and client IP from each request, Keycard must be
configured for an "access mode". This can be set in an initializer, under the
Keycard.config.access property, and should be either
:direct if clients
will make HTTP requests directly to the Ruby webserver, or
:proxy if a
reverse proxy will be used.
Under the hood, these modes amount to using either
REMOTE_ADDR in the environment set by the Ruby webserver for direct mode or
X-Forwarded-For headers set by a reverse proxy.
Keycard is licensed under the BSD-3-Clause license. See LICENSE.md.