@hitchy/plugin-auth 0.2.0 → 0.3.2

package/docs/.vuepress/config.js

@@ -42,10 +42,13 @@ module.exports = {
 			{ text: "API", link: "/api/" },
 			{ text: "Hitchy", items: [
 					{ text: "Core", link: "https://core.hitchy.org/" },
-					{ text: "", items: [
+					{ text: "Plugins", items: [
 							{ text: "Odem", link: "https://odem.hitchy.org/" },
 							{ text: "Auth", link: "/" },
-						]}
+						] },
+					{ text: "Tools", items: [
+							{ text: "SDT", link: "https://sdt.hitchy.org/" },
+						] }
 				] },
 		],
 	},

package/docs/api/config.md

@@ -1,5 +1,5 @@
 ---
-prev: ../service/
+prev: /api/service/
 next: routing.md
 ---
 
@@ -48,6 +48,18 @@ module.exports = {
 Environment variables **HITCHY_ADMIN_NAME**, **HITCHY_ADMIN_PASSWORD** and **HITCHY_ADMIN_ROLE** can be used to override any configuration provided here to e.g. support container-driven setups.   
 :::
 
+## config.auth.roles
+
+Lists role names to create on boot if missing in local database. This list is empty by default.
+
+```javascript
+module.exports = {
+	auth: {
+		roles: [ "guest", "customer", "manager" ],
+	},
+};
+```
+
 ## config.auth.authorizations
 
 This section grants or revokes access on named resources to/from users and/or roles. These _authorizations_ are loaded on application start before reading custom rules from local database. 
@@ -165,4 +177,4 @@ Provide a custom local strategy in property `local` here to prevent built-in [lo
 
 This optional string names strategy to use by default. Defaults to `local` itself. 
 
-Any custom strategy named here must be [set up](#config-auth-strategies) properly.
+Any custom strategy named here must be [set up](#config-auth-strategies) properly.

package/docs/api/model/authorization-rule.md

@@ -1,6 +1,6 @@
 ---
 prev: user-to-role.md
-next: ../service/
+next: /api/service/
 ---
 
 # AuthorizationRule

package/docs/api/model/user.md

@@ -25,9 +25,9 @@ Passwords for use with local authentication are implicitly hashed with [SCRYPT](
 
 Every user can be associated with a particular passport strategy to use for authentication. This [string](https://odem.hitchy.org/guides/defining-models.html#strings) property is picking a strategy by its name. Default strategy as configured is used in case this property is empty or unset.
 
-### provider
+### strategyData
 
-This [string](https://odem.hitchy.org/guides/defining-models.html#strings) property is meant to provide a custom parameter specific to selected strategy (except for the local one used by default). It's format is specific to that strategy and usually selects a remote service providing user authentication and additional meta data on it.
+This [string](https://odem.hitchy.org/guides/defining-models.html#strings) property is meant to provide custom data specific to selected strategy. It's format is specific to that strategy. It might be used to pick a remote service confirming the user's authentication or represent additional meta data on it.
 
 ## Methods
 

package/docs/api/service/authentication-passport.md

@@ -1,5 +1,5 @@
 ---
-prev: ../service/
+prev: /api/service/
 next: authentication-strategies.md
 ---
 

package/docs/guides/getting-started.md

@@ -1,6 +1,6 @@
 ---
 prev: ../guides/
-next: ../api/
+next: openid-connect.md
 ---
 
 # Quick Start
@@ -66,4 +66,4 @@ Content-Type: application/x-www-form-urlencoded
 username=admin&password=nimda
 ```
 
-This works due to the default [configuration](../api/config.md#config-auth-admin) for implicitly [setting up administrator account](../api/service/auth-manager.md#createadminifmissing) on application start.
+This works due to the default [configuration](../api/config.md#config-auth-admin) for implicitly [setting up administrator account](/api/service/auth-manager.md#createadminifmissing) on application start.

package/docs/guides/openid-connect.md

@@ -0,0 +1,164 @@
+---
+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

@@ -8,3 +8,5 @@ next: false
 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

@@ -0,0 +1,161 @@
+---
+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

@@ -5,7 +5,7 @@ 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/models/user.md), [roles](api/models/role) and their authorizations using [rules](api/models/authorization-rule.md) at runtime, too. 
+**@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
 
@@ -25,13 +25,13 @@ Server-side sessions keep track of authentication requests once they succeeded t
 
 ## Authorization
 
-Authorization is the process of controlling an [identified users](#authentication) permissions to access certain resources such as features, functions, data etc.
+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/models/auth-rule.md) associate a named resource with one or more [users](api/models/user.md) and/or [roles](api/models/role.md) for granting or revoking access on those resources.
+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/models/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`.
+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
 
@@ -59,7 +59,7 @@ On naming related resources, consider future improvements relying on resources n
 
 In this case, resulting resource names are `features.print`, `features.export.pdf` and `features.export.excel`.
 
-[Authorization rules](api/models/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`.
+[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
 {

package/index.js

@@ -1,31 +1,3 @@
-/**
- * (c) 2021 cepharum GmbH, Berlin, http://cepharum.de
- *
- * The MIT License (MIT)
- *
- * Copyright (c) 2021 cepharum GmbH
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- *
- * @author: cepharum
- */
-
 "use strict";
 
 module.exports = function( options, plugins ) {
@@ -33,17 +5,7 @@ module.exports = function( options, plugins ) {
 
 	const pluginApi = {
 		configure() {
-			if ( !api.config.auth ) {
-				api.config.auth = {};
-			}
-
-			const { auth } = api.config;
-
-			if ( !auth.strategies ) {
-				auth.strategies = {};
-			}
-
-			const { strategies } = auth;
+			const { strategies } = api.config.auth;
 
 			if ( !strategies.local ) {
 				strategies.local = api.runtime.services.AuthenticationStrategies.generateLocal();
@@ -55,15 +17,28 @@ module.exports = function( options, plugins ) {
 		 *
 		 * @returns {Promise<void>} promises plugin being set up
 		 */
-		initialize() {
-			const { services: { AuthorizationTree, AuthenticationPassport, AuthManager } } = api.runtime;
+		async initialize() {
+			const {
+				services: { AuthorizationTree, AuthenticationPassport, AuthManager },
+			} = api.runtime;
 			const { current } = AuthorizationTree;
 
-
 			AuthenticationPassport.integrateWithHitchy();
 
 			current.loadFromConfiguration( api.config.auth );
 
+			const roles = api.config.auth.roles;
+
+			if ( Array.isArray( roles ) && roles.length > 0 ) {
+				for ( const roleName of roles ) {
+					if ( typeof roleName === "string" && roleName && !/\s/.test( roleName.trim() ) ) {
+						await AuthManager.asRole( roleName.trim(), true ); // eslint-disable-line no-await-in-loop
+					} else {
+						throw new TypeError( "invalid name of role in runtime configuration" );
+					}
+				}
+			}
+
 			return Promise.all( [
 				AuthManager.createAdminUserIfMissing(),
 				current.loadFromDatabase(),
@@ -71,10 +46,13 @@ module.exports = function( options, plugins ) {
 		},
 
 		policies() {
-			const { config: { auth: { prefix = "/api/auth" } } } = this;
+			const { config: { auth: { prefix } } } = this;
 
 			const policies = {
-				"/": "authentication.initialize",
+				"/": [
+					"authentication.initialize",
+					"authentication.handleBasicAuth",
+				],
 			};
 
 			return prefix === false ? policies : {
@@ -88,15 +66,17 @@ module.exports = function( options, plugins ) {
 		},
 
 		routes() {
-			const { config: { auth: { prefix = "/api/auth" } } } = this;
+			const { config: { auth: { prefix } } } = this;
 
 			return prefix === false ? {} : {
-				[`POST ${prefix}/login/:strategy?`]: "user.authenticate",
-				[`GET ${prefix}/login/:strategy`]: "user.authenticate",
-				[`GET ${prefix}/current`]: "user.getCurrent",
-				[`GET ${prefix}/logout`]: "user.unauthenticate",
-				[`POST ${prefix}/password`]: ["user.changePassword"],
-				[`PATCH ${prefix}/password`]: ["user.changePassword"],
+				after: {
+					[`POST ${prefix}/login/:strategy?`]: "user.authenticate",
+					[`GET ${prefix}/login/:strategy`]: "user.authenticate",
+					[`GET ${prefix}/current`]: "user.getCurrent",
+					[`GET ${prefix}/logout`]: "user.unauthenticate",
+					[`POST ${prefix}/password`]: ["user.changePassword"],
+					[`PATCH ${prefix}/password`]: ["user.changePassword"],
+				},
 			};
 		},
 	};

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "@hitchy/plugin-auth",
-	"version": "0.2.0",
+	"version": "0.3.2",
 	"description": "user authentication and authorization for Hitchy",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"scripts": {
-		"test": "hitchy-pm session cookies odem --exec c8 -r text -r html mocha --recursive --exclude **/*.dist.js ./test/scripts --ui bdd",
 		"lint": "eslint .",
-		"start": "hitchy-pm session cookies odem --exec hitchy --project test/project/oAuth --plugins . --debug",
+		"test": "hitchy-pm session cookies odem --exec c8 -r text -r html mocha --recursive --exclude **/*.dist.js ./test/scripts --ui bdd",
+		"test:smoke": "hitchy-pm session cookies odem --exec hitchy --project test/project/testbed --plugins . --plugin . --debug",
 		"docs:dev": "vuepress dev docs",
 		"docs:build": "vuepress build docs"
 	},
@@ -21,23 +21,28 @@
 		"url": "https://gitlab.com/hitchy/plugin-auth/-/issues"
 	},
 	"homepage": "https://auth.hitchy.org",
+	"peerDependencies": {
+		"@hitchy/core": "^0.6.18"
+	},
 	"devDependencies": {
-		"@hitchy/server-dev-tools": "^0.2.11",
+		"@hitchy/server-dev-tools": "^0.4.2",
 		"@hitchy/types": "^0.1.0",
-		"c8": "^7.8.0",
-		"eslint": "^7.32.0",
+		"c8": "^7.11.0",
+		"eslint": "^8.12.0",
 		"eslint-config-cepharum": "^1.0.12",
-		"eslint-plugin-promise": "^5.1.0",
-		"mocha": "^9.1.0",
+		"eslint-plugin-promise": "^6.0.0",
+		"mocha": "^9.2.2",
+		"openid-client": "^5.1.4",
+		"passport-saml": "^3.2.1",
 		"should": "^13.2.3",
 		"should-http": "^0.1.1",
-		"vuepress": "^1.8.2"
+		"vuepress": "^1.9.7"
 	},
 	"dependencies": {
-		"@hitchy/plugin-cookies": "^0.1.5",
-		"@hitchy/plugin-odem": "^0.5.9",
-		"@hitchy/plugin-session": "^0.1.6",
-		"passport": "^0.4.1",
+		"@hitchy/plugin-cookies": "^0.1.6",
+		"@hitchy/plugin-odem": "^0.5.10",
+		"@hitchy/plugin-session": "^0.1.10",
+		"passport": "^0.5.2",
 		"passport-local": "^1.0.0"
 	}
 }