Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/theonethread/falkor-auth-server
Nginx authentication preflight proxy server
https://github.com/theonethread/falkor-auth-server
authentication falkor nginx server
Last synced: 27 days ago
JSON representation
Nginx authentication preflight proxy server
- Host: GitHub
- URL: https://github.com/theonethread/falkor-auth-server
- Owner: theonethread
- License: mit
- Created: 2021-07-07T09:02:56.000Z (over 3 years ago)
- Default Branch: develop
- Last Pushed: 2023-06-21T15:39:48.000Z (over 1 year ago)
- Last Synced: 2024-09-28T01:40:57.485Z (about 1 month ago)
- Topics: authentication, falkor, nginx, server
- Language: JavaScript
- Homepage: https://falkor.world
- Size: 672 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license.txt
Awesome Lists containing this project
README
# **Falkor Authentication Server**
[](https://www.npmjs.com/package/@falkor/falkor-auth-server "Visit") [](https://www.npmjs.com/package/@falkor/falkor-auth-server "Visit") [](https://nodejs.org/ "Visit") [](https://github.com/theonethread/falkor-auth-server/actions "Visit") [](https://github.com/theonethread/falkor-auth-server/actions "Visit") [](https://github.com/theonethread/falkor-auth-server "Visit") [](https://www.npmjs.com/package/@falkor/falkor-bundler "Visit") [](https://www.npmjs.com/package/fastify "Visit") [](https://snyk.io/test/github/theonethread/falkor-auth-server "Visit") [](https://github.com/theonethread/falkor-auth-server/blob/master/license.txt "Visit")
The `falkor-auth-server` project is a standalone `npm` command-line application written in JavaScript to be used as an Nginx authentication proxy server (mainly to be used with the **Falkor Framework**).
## **Installation**
Install the package globally, so it's available in your `PATH`:
```
$ npm install --global @falkor/falkor-auth-server
```
## **Usage**
### **Command Line Interface**
#### `falkor-auth-server`
Usage:
```
falkor-auth-server [(--id )] [(--port )] [(--domain )] [(--host )] [(--cookie )]
[(--ttl )] [(--secret )] [(--user )] [(--role )] [(--db )] [(--stamp )]
[(--level )] [(--file )]
falkor-auth-server [(--i )] [(--p )] [(--d )] [(--H )] [(--c )][(--t )]
[(--s )] [(--u )] [(--r )] [(--D )] [(--S )] [(--l )] [(--f )]
falkor-auth-server (-v | --version | -h | --help)
```
Options:
- `-v` or `--version`: Show version and exit
- `-h` or `--help`: Show help and exit
- `-i ` or `--id `: ID of server (default: `falkor-auth`)
- `-p ` or `--port `: Port of server (default: `9999`)
- `-d ` or `--domain `: Domain of the cookies to set
- `-H ` or `--host `: Host of the server (default: `0.0.0.0`)
- `-c ` or `--cookie `: Cookie name (default: `@falkor_token`)
- `-t ` or `--ttl `: Cookie TTL (default: `14400`)
- `-s ` or `--secret `: 32 characters long secret for token and password encryption
- `-u ` or `--user `: User response header name (default: `X-Falkor-Header`)
- `-r ` or `--role `: Role response header name (default: `X-Falkor-Role`)
- `-D ` or `--db `: User database address (`mongodb://` or `mongodb+srv://` address)
- `-S ` or `--stamp `: Add timestamp to logs (default: `true`)
- `-l ` or `--level `: Log level (default: `debug`)
- `-f ` or `--file `: Log file destination, if set logs will be dumped here
> _**SEE:** [`config.js`](https://github.com/theonethread/falkor-auth-server/blob/master/src/util/config.js "Open") for further reference._
#### `falkor-auth-passwd`
The accompanying `falkor-auth-passwd` binary is also a standalone `npm` command-line application written in JavaScript to be used with the `falkor-auth-server`. It generates hashes out of passwords based on the server's secret to be stored in the database.
Usage:
```
falkor-auth-passwd (--password ) (--secret )
falkor-auth-passwd (-p ) (-s )
falkor-auth-passwd (-v | --version | -h | --help)
```
Options:
`-v` or `--version`: Show version and exit `-h` or `--help`: Show help and exit `-s ` or `--secret `: 32 characters long secret for token and password encryption `-p ` or `--password `: Password to create encrypted hash for
### **Environment Variables**
All `falkor-auth-server` CLI options can be set as environment variables too, though CLI flags overpower them.
- `SERVER_ID=`: ID of server (default: `falkor-auth`)
- `SERVER_PORT=`: Port of server (default: `9999`)
- `SERVER_DOMAIN=`: Domain of the cookies to set
- `SERVER_HOST=`: Host of the server (default: `0.0.0.0`)
- `COOKIE_NAME=`: Cookie name (default: `@falkor_token`)
- `COOKIE_TTL=`: Cookie TTL (default: `14400`)
- `AUTH_SECRET=`: 32 characters long secret for token and password encryption
- `AUTH_HEADER_USER=`: User response header name (default: `X-Falkor-Header`)
- `AUTH_HEADER_ROLE=`: Role response header name (default: `X-Falkor-Role`)
- `AUTH_DB=`: User database address (`mongodb://` or `mongodb+srv://` address)
- `LOG_TIMESTAMP=`: Add timestamp to logs (default: `true`)
- `LOG_LEVEL=`: Log level (default: `debug`)
- `LOG_FILE=`: Log file destination, if set logs will be dumped here
> _**SEE:** Example [`config.env`](https://github.com/theonethread/falkor-auth-server/blob/master/res/config.env "Open") for further reference._
### **Must Have Settings**
The following settings must be present either running the application with CLI options, or using environment variables:
- Domain of the cookies to set:
- `-d ` or `--domain `
- `SERVER_DOMAIN=`
- 16 characters long secret for token encryption:
- `-s ` or `--secret `
- `AUTH_SECRET=`
- User database address (or relative path to `.yml` file in `debug` builds):
- `-D ` or `--db `
- `AUTH_DB=`
## **User Data**
The server needs an existing MongoDB database, for testing purposes one can create a free account at [MongoDB Atlas](https://www.mongodb.com/atlas "Visit"). The application will assume the following database setup:
- Database: `authentication`
- Collection: `users`
- Entries:
```javascript
{
name: { type: "string" }
pwd: { type: "string" }
roles: {
type: "array",
items: { type: "string" }
}
}
```
The `pwd` entry must be an encoded password hash. To generate one with the application's `crypto` library, with a global install run:
```
$ falkor-auth-passwd --secret --password
```
Or from the installed project's root:
```
$ npm run passwd -- --secret --password
```
> _**NOTE:** Since randomization, you will get different values running this command multiple times._
## **Server Setup**
To set up a Fedora-based Nginx webserver using Node.js as authentication service you can follow my tutorials in the Hetzner Community:
- [Setting Up a Secure Fedora Webserver](https://community.hetzner.com/tutorials/secure-fedora-webserver "Visit")
- [Nginx Authentication Preflight Request with Node.js Backend](https://community.hetzner.com/tutorials/nginx-auth-preflight-nodejs-api "Visit")
## **Further Development**
The project uses the [`@falkor/falkor-bundler`](https://www.npmjs.com/package/@falkor/falkor-bundler "Visit") module to compile sources. To clone the repository and compile `falkor-auth-server` one can use the commands:
```
$ git clone --branch develop [email protected]:theonethread/falkor-auth-server.git
$ cd falkor-auth-server
$ npm install
$ npm run [ debug | release ]
```
> _**SEE:** `"scripts"` entry in [`package.json`](https://github.com/theonethread/falkor-auth-server/blob/master/package.json "Open") for further reference._
> _**NOTE:** Compiling the `develop` sources might need locally linked `develop` versions of downstream module:_
>
> - _[`@falkor/falkor-bundler`](https://github.com/theonethread/falkor-bundler/tree/develop "Visit")_
>
> _**SEE:** [`npm-link`](https://docs.npmjs.com/cli/v7/commands/npm-link "Visit") for further reference._
### **Database**
If compiled in `debug` mode, and the application finds user data in MongoDB with unencrypted `pass` field (when logging a user in), **it will update the user record** with an encrypted `pwd` field, and unset `pass`. This behavior can be controlled with the `#UPDATE_PWD` context variable in the `"scripts"` block of [`package.json`](https://github.com/theonethread/falkor-auth-server/blob/master/package.json "Open") - for further details see [`@falkor/falkor-bundler`](https://www.npmjs.com/package/@falkor/falkor-bundler "Visit").
#### **Database Mock**
If compiled in `debug` mode and the DB option does not start with `mongodb://` or `mongodb+srv://`, the application will assume a relative path to a `.yml` file with the following structure:
```yaml
users:
- name: string
pass: string
roles: [string]
```
> _**SEE:** Example [`auth.yml`](https://github.com/theonethread/falkor-auth-server/blob/master/res/auth.yml "Open") for further reference._
### **Man Page**
By default the `falkor-auth-server` project ships with pre-compiled man pages when installed on Unix-like operating systems. The manuals were created by converting the files [`man/man.md`](https://github.com/theonethread/falkor-auth-server/blob/master/man/man.md "Open") and [`man/passwd.md`](https://github.com/theonethread/falkor-auth-server/blob/master/man/passwd.md "Open").
To recompile the manuals, make sure that [`Pandoc`](https://pandoc.org/ "Visit") is installed, and present in the `PATH`, then run:
```
$ npm run man
```
### **Linting**
The project uses [`prettier`](https://www.npmjs.com/package/prettier "Visit") for code formatting and [`cspell`](https://www.npmjs.com/package/cspell "Visit") to avoid general typos in both sources and documentation - it is advised to install these packages as extensions in your IDE to prevent CI errors beforehand. To lint the project run:
```
$ npm run lint
```
> _**SEE:** [`.prettierrc.cjs`](https://github.com/theonethread/falkor-auth-server/blob/develop/.prettierrc.cjs "Open") and [`cspell.config.cjs`](https://github.com/theonethread/falkor-auth-server/blob/develop/cspell.config.cjs "Open") for further reference._
- To fix formatting issues run `$ npx prettier --write `. This will overwrite the file with the default formatting applied locally, so then you can review the changes in `git` and **ensure those did not affect production artifacts**.
- To fix spelling errors run `$ npx cspell lint --wordsOnly --unique --gitignore --exclude .git ** .*` for details, and either make the fixes in the sources listed, add `cspell` favored comments, or extend the project-wide `cspell.config.cjs` accordingly.
### **Versioning and Branching Strategy**
Release sources can be found on the `master` branch, this one always points to the latest tagged release. Previous sources of releases can be found using `git` version tags (or browsing GitHub releases). Released packages can be found on [npmjs](https://www.npmjs.com/package/@falkor/falkor-auth-server "Visit").
The repository's main branch is `develop` (due to technical reasons), this holds all developments that are already decided to be included in the next release. Usually this branch is ahead of `master` one patch version (but based on upcoming features to include this can become minor, or major), so prepared external links may yet be broken.
The `feature/*` branches usually hold ideas and POC code, these will only be merged into `develop` once their impact measured and quality meets release requirements.
> _The project uses [SemVer](https://semver.org "Visit"), `git` tags are prefixed with a `v` character._
### **GitHub Actions**
The workflows can be found [here](https://github.com/theonethread/falkor-auth-server/blob/develop/.github/workflows "Open").
#### **Continuous Integration**
Automatic builds are achieved via GitHub actions, CI will make nightly builds of the `develop` branch (using Ubuntu image), and test `master` when there is a pull request, or commit on it (using Ubuntu - Win - MacOS image matrix).
### **Security**
The project uses [CodeQL](https://codeql.github.com "Visit") and [Snyk](https://snyk.io "Visit") to ensure standard security.
> _The **Falkor Framework** supports a healthy and ubiquitous Internet Immune System enabled by security research, reporting, and disclosure. Check out our [Vulnerability Disclosure Policy](https://github.com/theonethread/falkor-auth-server/security/policy "Open") - based on [disclose.io](https://disclose.io "Visit")'s best practices._
### **Free and Open Source**
The latest sources can always be found on [GitHub](https://github.com/theonethread/falkor-auth-server "Visit").
#### **Getting Involved**
We believe - and we hope you do too - that learning how to code, how to think, and how to contribute to free- and open source software can empower the next generation of coders and creators. We **value** first time contributors just the same as rock stars of the OSS world, so if you're interested in getting involved, just head over to our [Contribution Guidelines](https://github.com/theonethread/.github/blob/master/.github/contributing.md "Open") for a quick heads-up!
#### **License**
[MIT](https://github.com/theonethread/falkor-auth-server/blob/master/license.txt "Open")
##
---
_©2020-2023 Barnabas Bucsy - All rights reserved._