@hitchy/plugin-auth 0.3.5 → 0.3.7

package/docs/guides/openid-connect.md

@@ -1,164 +0,0 @@
----
-prev: getting-started.md
-next: saml.md
----
-
-# OpenID Connect
-
-[OpenID Connect](https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)) is a security protocol for authenticating in distributed applications as a centrally managed user without exposing its credentials to either application. 
-
-OpenID Connect supports different flows. This example is about [Authorization Code Flow](https://auth0.com/docs/flows/authorization-code-flow).
-
-## Prerequisites
-
-This protocol depends on a remotely set up _identity provider_ (IdP). This tutorial is illustrating how to enable a Hitchy-based application to support authentication against such an IdP via OpenID Connect. Setting up an IdP is beyond its scope, though.
-
-There are plenty of solutions available for running your own IdP. There are multiple options including commercial and open-source software. [Keycloak](https://www.keycloak.org/) and [authentik](https://goauthentik.io/) are examples for the latter. See our rough [step-by-step tutorial for setting up Keycloak on a server using a stack of Docker containers](https://gist.github.com/soletan/02e141993a811221ce8347c5a6129021). This tutorial is based on Keycloak.
-
-## Create custom strategy
-
-This plugin relies on [passport.js](https://www.passportjs.org/) which in turn supports so called _strategies_ to support different kinds of authentication services and security protocols. The strategy used in this example is included with 3rd-party package [openid-client](https://www.npmjs.com/package/openid-client) which you need to install in context of your application:
-
-```bash
-npm i openid-client
-```
-
-**@hitchy/plugin-auth** is picking up all [strategies configured in its runtime configuration](../api/config.md#config-auth-strategies) on application start. It includes a factory service offering methods for generating strategies from a set of configuration options. That's what we use here. 
-
-Open file **config/auth.js** of your project and add the `oidc` property to the list of strategies as illustrated in this example:
-
-```javascript
-"use strict";
-
-module.exports = async function() {
-	const { service } = this.runtime;
-
-	return {
-		auth: {
-			strategies: {
-				oidc: await service.AuthenticationStrategies.generateOpenIdConnect( "oidc", {
-					// Provides URL of IdP for discovering settings for this
-					// application's authentication realm.
-					discovery_url: "https://idp.cepharum.de/auth/realms/hitchy-plugin-auth-ci-test",
-
-					// Provides this application's name in context of discovered
-					// IdP realm. Think of it as the application's username for
-					// authenticating itself at the IdP.
-					client_id: "ci-openid-test",
-
-					// Provides IdP-specific secret used to authenticate this
-					// application as a valid client of IdP. Think of it as the
-					// application's password for authenticating itself.
-					client_secret: "some-random-secret",
-
-					// Lists valid URLs user may be redirected to after logging
-					// in successfully at IdP.
-					redirect_uris: ["http://localhost:3000/api/auth/login/oidc"],
-
-					// Lists metadata/attributes of authenticated user to be
-					// delivered by IdP in redirect after successful login.
-					response_types: ["code"],
-
-					// Lists valid URLs user may be redirected to after logging
-					// out from IdP.
-					post_logout_redirect_uris: ["http://localhost:3000/api/auth/logout"],
-				} ),
-			},
-		}
-	};
-};
-```
-
-:::tip Multiple strategies?
-It's fine to have multiple strategies of different name being set up like that. Just make sure name of property is different, URL-safe and provided as first argument to the generator method.
-:::
-
-The strategy in this example is named `oidc`. Thus, the same name is given as first argument to the generator function, too. Its second argument provides configuration options for used to set up the strategy in detail. 
-
-:::warning Adapt to your IdP
-The configuration in code example is for illustration, only. You need to adapt the settings to work with your IdP.
-:::
-
-* The **discovery_url** is addressing your IdP's meta settings which is a computable set of configuration parameters the client will pick up and adapt to your IdP properly. In our case, which is based on Keycloak, it is [https://idp.cepharum.de/auth/realms/hitchy-plugin-auth-ci-test](https://idp.cepharum.de/auth/realms/hitchy-plugin-auth-ci-test). Click the link to see all meta settings related to a realm named `hitchy-plugin-auth-ci-test`.
-* **client_id** and **client_secret** are just like a user's name and password, but this time they are  suitable for authenticating your application at your IdP.
-* A list of **redirect_uris** can be provided, but usually it consists of a single URL, only. In Authorization Code Flow, users are redirected to that URL right after successful authentication. Additional data on authenticated user is passed in query parameters there. The strategy is required to process that request, too. Thus, in case of **hitchy/plugin-auth**, this is usually referring to the same login endpoint used to trigger the authentication in the first place, e.g. [http://localhost:3000/api/auth/login/oidc](http://localhost:3000/api/auth/login/oidc). This support is based on some [routing defaults](../api/routing.md).
-* Similar to that, another list of possible redirect URIs is given in **post_logout_redirect_uris**, this time for redirecting a user's browser after successful logout at IdP. The target is meant to finish the logout process on behalf of your application, thus you should point it to the logout URL [http://localhost:3000/api/auth/logout](http://localhost:3000/api/auth/logout) accordingly.
-* A list of required meta attributes to deliver on an authenticated user can be configured, too. Requesting `code` response type is essential to Authorization Code Flow. That's referring to the user's name. You might query for additional data such as the user's mail address or similar.
-
-:::tip Additional options
-All but the **discovery_url** are metadata options supported by the underlying **openid-client** package, thus you should look into [its documentation](https://github.com/panva/node-openid-client/blob/main/docs/README.md#new-clientmetadata-jwks-options) for additional options available. Some of them might be failing to work because of the way the client is integrated with Hitchy.
-:::
-
-## Restart and test
-
-Restart your hitchy instance. Open browser at [http://localhot:3000/api/auth/current](http://localhot:3000/api/auth/current) and get a response like this one:
-
-```json
-{"success":true,"authenticated":false}
-```
-
-The request has succeeded, but no user is authenticated currently. 
-
-Trigger authentication by opening URL [http://localhost:3000/api/auth/login/oidc](http://localhost:3000/api/auth/login/oidc) next. Last segment in this URL is referring to the strategy name you've picked when integrating it with the list of configured strategies.
-
-This will redirect the browser to your IdP for prompting to log in:
-
-![screenshot of IdP login](./idp-login.png)
-
-After logging in there, your browser is instantly redirected back to the URL [http://localhost:3000/api/auth/login/oidc](http://localhost:3000/api/auth/login/oidc) as given in configuration above. This time it is succeeding with a response:
-
-```json
-{"success":true,"authenticated":true}
-```
-
-You are authenticated! 
-
-Return to the first URL requested above. It's providing a different set of information this time:
-
-```json
-{"success":true,"authenticated":{"uuid":"d778afae-1234-4a58-a254-b56b1f36e914","name":"your-user","roles":[]}}
-```
-
-Try repeating this request if you like. Unless closing your browser, you stay authenticated. 
-
-If you happen to close the browser, just return to the login URL and - based on your IdP configuration - you will be re-authenticated instantly without being prompted for entering username and password again.
-
-Next send a request to [http://localhost:3000/api/auth/logout](http://localhost:3000/api/auth/logout). It gets approved:
-
-```json
-{"success":true}
-```
-
-Fetch current state of authentication at [https://localhost:3000/api/auth/current](https://localhost:3000/api/auth/current) once again.
-
-```json
-{"success":true,"authenticated":false}
-```
-
-Try to re-authenticate instantly at [http://localhost:3000/api/auth/login/oidc](http://localhost:3000/api/auth/login/oidc). It's going to prompt for username and password at your IdP again.
-
-## How to welcome users?
-
-Well, if you don't want your application's users to see the approval of logging in as raw JSON data, you simply have to replace the controller for route `GET /api/auth/login/oidc` and make it provide any other response, e.g. some redirection to a welcome page of your application.
-
-Adjust your application's file **config/routes.js** accordingly: 
-
-```javascript
-exports.routes = {
-    "GET /api/auth/login/oidc": ( _, res ) => res.redirect( 301, "/welcome" ),
-};
-```
-
-This is possible in a custom policy [processed after this plugin's policy](https://core.hitchy.org/internals/routing-basics.html#routing-slots), either. This could be your **config/policies.js** file:
-
-```javascript
-exports.policies = {
-    "GET /api/auth/login/oidc"( req, res, next ) {
-        if ( req.user ) {
-            res.redirect( 301, "/welcome" );
-        } else {
-            next();
-        }
-    },
-};
-```

package/docs/guides/readme.md

@@ -1,12 +0,0 @@
----
-prev: ../introduction.md
-next: false
----
-
-# Guides
-
-This section provides simple tutorials explaining how to work with this plugin:
-
-* [Getting started](getting-started.md)
-* [OpenID Connect](openid-connect.md)
-* [SAML 2.0](saml.md)

package/docs/guides/saml.md

@@ -1,161 +0,0 @@
----
-prev: openid-connect.md
-next: ../api/
----
-
-# SAML 2.0
-
-[SAML 2.0](https://en.wikipedia.org/wiki/SAML_2.0) is a security protocol for authenticating centrally managed users in multiple distributed applications without exposing their credentials to either application. 
-
-## Prerequisites
-
-This protocol depends on a remotely set up identity provider (IdP). This tutorial is illustrating how to enable a Hitchy-based application to support authentication against such an IdP via SAML 2.0. Setting up an IdP is beyond its scope, though.
-
-There are plenty of solutions available for running your own IdP. There are multiple options including commercial and open-source software. [Keycloak](https://www.keycloak.org/) and [authentik](https://goauthentik.io/) are examples for the latter. See our rough [step-by-step tutorial for setting up Keycloak on a server using a stack of Docker containers](https://gist.github.com/soletan/02e141993a811221ce8347c5a6129021). This tutorial is based on Keycloak.
-
-## Create custom strategy
-
-This plugin relies on [passport.js](https://www.passportjs.org/) which in turn supports so called _strategies_ to support different kinds of authentication services and security protocols. The strategy used in this example is included with 3rd-party package [passport-saml](https://www.npmjs.com/package/passport-saml) which you need to install in context of your application:
-
-```bash
-npm i passport-saml
-```
-**@hitchy/plugin-auth** is picking up all [strategies configured in its runtime configuration](../api/config.md#config-auth-strategies) on application start. It includes a factory service offering methods for generating strategies from a set of configuration options. That's what we use here.
-
-Open file **config/auth.js** of your project and add the `saml` property to the list of strategies as illustrated in this example:
-
-```javascript
-"use strict";
-
-module.exports = async function() {
-	const { service } = this.runtime;
-
-	return {
-		auth: {
-			strategies: {
-				saml: service.AuthenticationStrategies.generateSaml( "saml", {
-					// URL of IdP receiving SAML requests
-					entryPoint: "https://idp.cepharum.de/auth/realms/hitchy-plugin-auth-ci-test/protocol/saml",
-
-					// name of this client as registered with the IdP
-					issuer: "ci-saml-test",
-
-					// signature algorithm to use (set to prevent insecure 
-					// SHA-1 used by default)
-					signatureAlgorithm: "sha256",
-
-					// URL for redirecting user to after successful login
-					callbackUrl: "http://localhost:3000/api/auth/login/saml",
-
-					// URL of local application's endpoint for logging 
-					// out to be exposed as meta of this service provider
-					logoutCallbackUrl: "http://localhost:3000/api/auth/logout",
-
-					// public certificate of IdP's realm used for signing 
-					// SAML responses
-					cert: "MIICwzCCAasCfB5l4jANBg...SDuuWWgsPnlrNpCnOnM6ycT/PCDyad",
-				} ),
-			},
-		}
-	};
-};
-```
-
-:::tip Multiple strategies?
-It's fine to have multiple strategies of different name being set up like that. Just make sure name of property is different, URL-safe and provided as first argument to the generator method.
-:::
-
-The strategy in this example is named `saml`. Thus, the same name is given as first argument to the generator function, too. Its second argument provides configuration options for used to set up the strategy in detail.
-
-:::warning Adapt to your IdP
-The configuration in code example is for illustration, only. You need to adapt the settings to work with your IdP.
-:::
-
-* The **entryPoint** URL [https://idp.example.com/auth/realms/app-users/protocol/saml](https://idp.example.com/auth/realms/app-users/protocol/saml) is your IdP's URL for the realm of users meant to gain access to your application. In Keycloak this is called _Master SAML Processing URL_.
-* The **issuer** `ci-saml-test` is the name of your application as registered with your IdP. In Keycloak that's the name of a registered _client_.
-* The **signatureAlgorithm** must be changed due to `passport-saml` is defaulting to the more insecure `sha1` otherwise.
-* The **cert**ificate - it's been significantly shortened in example above - is provided by your IdP for validating its signatures. It is required by `passport-saml` to validate signatures on responses provided by IdP. 
-  
-  In Keycloak the certificate to be used is found in your realm's settings, in tab _Keys_:
-
-  ![screenshot of Keycloak providing signing certificate](./idp-saml-cert.png)
-
-* The **callbackUrl** [http://localhost:3000/api/auth/login/saml](http://localhost:3000/api/auth/login/saml) is your application's absolute URL processing login requests returning from IdP via redirecting the user's browser after successful authentication. The path should be addressing the same endpoint triggering the authentication, thus it should be very similar to the example. It works due to [routing defaults](../api/routing.md). 
-
-  No matter your eventual redirect URI, you have to configure it as a _valid redirect URI_ at your IdP.
-
-* According to that, the **logoutCallbackUrl** [http://localhost:3000/api/auth/logout](http://localhost:3000/api/auth/logout) is your application's absolute URL processing logout requests after returning from IdP via redirecting the user's browser. Just like before, the path should be addressing the same endpoint triggering the logout. Don't forget to declare it a _valid redirect URI_ at your IdP, too.
-
-## Restart and test
-
-Restart your hitchy instance. Open browser at [http://localhot:3000/api/auth/current](http://localhot:3000/api/auth/current) and get a response like this one:
-
-```json
-{"success":true,"authenticated":false}
-```
-
-The request has succeeded, but no user is authenticated currently. 
-
-Trigger authentication by opening URL [http://localhost:3000/api/auth/login/saml](http://localhost:3000/api/auth/login/saml) next. Last segment in this URL is referring to the strategy name you've picked when integrating it with the list of configured strategies.
-
-This will redirect the browser to your IdP for prompting to log in:
-
-![screenshot of IdP login](./idp-login.png)
-
-After logging in there, your browser is instantly redirected back to the URL [http://localhost:3000/api/auth/login/saml](http://localhost:3000/api/auth/login/saml) as given in configuration above. This time it is succeeding with a response:
-
-```json
-{"success":true,"authenticated":true}
-```
-
-You are authenticated! 
-
-Return to the first URL requested above. It's providing a different set of information this time:
-
-```json
-{"success":true,"authenticated":{"uuid":"d778afae-1234-4a58-a254-b56b1f36e914","name":"your-user","roles":[]}}
-```
-
-Try repeating this request if you like. Unless closing your browser, you stay authenticated. 
-
-If you happen to close the browser, just return to the login URL and - based on your IdP configuration - you will be re-authenticated instantly without being prompted for entering username and password again.
-
-Next send a request to [http://localhost:3000/api/auth/logout](http://localhost:3000/api/auth/logout). It gets approved:
-
-```json
-{"success":true}
-```
-
-Fetch current state of authentication at [https://localhost:3000/api/auth/current](https://localhost:3000/api/auth/current) once again.
-
-```json
-{"success":true,"authenticated":false}
-```
-
-Try to re-authenticate instantly at [http://localhost:3000/api/auth/login/saml](http://localhost:3000/api/auth/login/saml). It's going to prompt for username and password at your IdP again.
-
-## How to welcome users?
-
-Well, if you don't want your application's users to see the approval of logging in as raw JSON data, you simply have to replace the controller for route `GET /api/auth/login/saml` and make it provide any other response, e.g. some redirection to a welcome page of your application.
-
-Adjust your application's file **config/routes.js** accordingly: 
-
-```javascript
-exports.routes = {
-    "GET /api/auth/login/saml": ( _, res ) => res.redirect( 301, "/welcome" ),
-};
-```
-
-This is possible in a custom policy [processed after this plugin's policy](https://core.hitchy.org/internals/routing-basics.html#routing-slots), either. This could be your **config/policies.js** file:
-
-```javascript
-exports.policies = {
-    "GET /api/auth/login/saml"( req, res, next ) {
-        if ( req.user ) {
-            res.redirect( 301, "/welcome" );
-        } else {
-            next();
-        }
-    },
-};
-```

package/docs/introduction.md

@@ -1,78 +0,0 @@
----
-prev: /
-next: /guides/
----
-
-# Introduction
-
-**@hitchy/plugin-auth** is a plugin for the server-side framework [Hitchy](https://core.hitchy.org). It provides request handlers and policies for server-side request [authentication](#authentication) and [authorization](#authorization). It processes [authorization rules](api/config.md#config-auth-authorizations) in [runtime configuration](https://core.hitchy.org/api/hitchy.html#configuration). There are [ODM-based](https://odem.hitchy.org) [models](https://core.hitchy.org/internals/components.html#models) for managing [users](api/model/user.md), [roles](api/model/role) and their authorizations using [rules](api/model/authorization-rule.md) at runtime, too. 
-
-## Authentication
-
-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](https://odem.hitchy.org/).
-
-::: tip Supported authentication strategies  
-This plugin integrates with [Passport](http://www.passportjs.org/) to handle authentication. Passport provides a wide array of [strategies](http://www.passportjs.org/packages/) 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.  
-:::
-
-### Users
-
-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](https://www.npmjs.com/package/@hitchy/plugin-session) and [cookies](https://www.npmjs.com/package/@hitchy/plugin-cookies). 
-
-## Authorization
-
-Authorization is the process of controlling an [identified user's](#authentication) permissions to access certain resources such as features, functions, data etc.
-
-By intention, users have restricted access to your application. [Authorization rules](api/model/authorization-rule.md) associate a named resource with one or more [users](api/model/user.md) and/or [roles](api/model/role.md) for granting or revoking access on those resources.
-
-### Administrator account
-
-On every start of application, the plugin checks if there is a [configurable](api/config.md#config-auth-admin) [user](api/model/user.md) with full access to all routes and models and creates it if missing. Unless [configured](api/config.md#config-auth-admin) otherwise, that user's name is `admin` and its password is `nimda`.
-
-### Resources
-
-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
-
-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. `print` and `export`. If you've combined features in such a group, add another segment for either individual feature in that group, e.g. `pdf` and `excel` for the `export` group.
-
-```
-+- features
-   +- print
-   +- export
-      +- pdf
-      +- excel
-```
-
-In this case, resulting resource names are `features.print`, `features.export.pdf` and `features.export.excel`.
-
-[Authorization rules](api/model/authorization-rule.md) 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 `features` or `features.export`.
-
-```json
-{
-    "features": "@platinum",
-    "features.export": "@gold,@silver",
-    "features.export.pdf": "-@silver,john.doe"
-}
-```
-
-:::tip Example explained  
-Users with `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.

package/docs/readme.md

@@ -1,11 +0,0 @@
----
-sidebar: false
----
-
-# Authentication and authorization
-
-This plugin implements generic support for authentication and authorization and easily integrates with your [Hitchy](https://core.hitchy.org)-based application.
-
-* [Introduction](introduction.md)
-* [Getting Started](guides/getting-started.md)
-* [API](api)