@hitchy/plugin-auth is a plugin for the server-side framework Hitchy (opens new window). It provides request handlers and policies for server-side request authentication and authorization. It processes authorization rules in runtime configuration (opens new window). There are ODM-based (opens new window) models (opens new window) for managing users, roles and their authorizations using rules at runtime, too.
Authentication refers to the process of assuring a user's identity.
This plugin includes request handlers for instantly supporting basic authentication against some local database managed with Odem (opens new window).
Supported authentication strategies
This plugin integrates with Passport (opens new window) to handle authentication. Passport provides a wide array of strategies (opens new window) that can handle all kinds of authentication which might work with external sources, as well. There is a built-in strategy for local authentication used by default.
Requests may include data for authenticating as a user selected by its name. Usually, this involves additional provision of some identification token such as a password.
Server-side sessions keep track of authentication requests once they succeeded to consider follow-up requests of same client as authenticated, too. This relies on separate plugins session (opens new window) and cookies (opens new window).
Authorization is the process of controlling an identified user's permissions to access certain resources such as features, functions, data etc.
# Administrator account
On every start of application, the plugin checks if there is a configurable user with full access to all routes and models and creates it if missing. Unless configured otherwise, that user's name is
admin and its password is
A resource is basically just a name, e.g. of a feature or some data entity in your application. It doesn't mean anything to this plugin on its own. In context of your application the name is meant to represent something you want to control access on.
Resource names work hierarchically by design. They consist of segments similar to a filesystem's pathname. However, segments of a resource name are separated by periods instead of slashes.
Roles are an addition to managing users. There is a model for managing roles in a database. Every role is meant to represent a group of users. They simplify access control based on authorization rules.
# An example
Let's assume your application provides a set of dedicated features and you want to control who's permitted to use what feature. Every such feature is a resource. For example, your application could have a print feature and an export feature. The latter could be divided into different supported export formats such as PDF and Excel spreadsheet.
On naming related resources, consider future improvements relying on resources not representing some feature, such as controlling access on individual data records of your application. Thus, you should start naming your resources with a type name such as
features. Group features as good as possible and pick a second-level name for either group, e.g.
export. If you've combined features in such a group, add another segment for either individual feature in that group, e.g.
excel for the
In this case, resulting resource names are
Authorization rules are capable of granting/revoking access on either particular feature selected by its name as given above. In addition, authorization rules may address groups of features or all features altogether by using partial resource names such as
platinum role are granted access to all features. Users with
gold role may access all export features. Eventually, users with
silver role may access all export features except for the PDF export. Without regards to being assigned to either role, user
john.doe has been granted access on PDF export feature.
On checking a user's authorization to access some resource, you provide that resource's qualified resource name. All rules addressing this resource or any of its superordinated resources will be checked for granting/revoking access to/from current user and/or some role this user is associated with.
Your application's code can check a user's authorization using some service. In addition, a policy generator is included with this plugin to create separate policies to be injected into your application's routing configuration.