Falkor Authentication Server

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 <id>)] [(--port <port>)] [(--domain <domain>)] [(--host <host>)] [(--cookie <cookie>)]
    [(--ttl <ttl>)] [(--secret <secret>)] [(--user <user>)] [(--role <role>)] [(--db <db>)] [(--stamp <stamp>)]
    [(--level <level>)] [(--file <file>)]
falkor-auth-server [(--i <id>)] [(--p <port>)] [(--d <domain>)] [(--H <host>)] [(--c <cookie>)][(--t <ttl>)]
    [(--s <secret>)] [(--u <user>)] [(--r <role>)] [(--D <db>)] [(--S <stamp>)] [(--l <level>)] [(--f <file>)]
falkor-auth-server (-v | --version | -h | --help)

Options:

-v or --version: Show version and exit
-h or --help: Show help and exit
-i <id> or --id <id>: ID of server (default: falkor-auth)
-p <port> or --port <port>: Port of server (default: 9999)
-d <domain> or --domain <domain>: Domain of the cookies to set
-H <host> or --host <host>: Host of the server (default: 0.0.0.0)
-c <cookie> or --cookie <cookie>: Cookie name (default: @falkor_token)
-t <ttl> or --ttl <ttl>: Cookie TTL (default: 14400)
-s <secret> or --secret <secret>: 32 characters long secret for token and password encryption
-u <user> or --user <user>: User response header name (default: X-Falkor-Header)
-r <role> or --role <role>: Role response header name (default: X-Falkor-Role)
-D <db> or --db <db>: User database address (mongodb:// or mongodb+srv:// address)
-S <stamp> or --stamp <stamp>: Add timestamp to logs (default: true)
-l <level> or --level <level>: Log level (default: debug)
-f <file> or --file <file>: Log file destination, if set logs will be dumped here

SEE: config.js 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 <password>) (--secret <secret>)
falkor-auth-passwd (-p <password>) (-s <secret>)
falkor-auth-passwd (-v | --version | -h | --help)

Options:

-v or --version: Show version and exit -h or --help: Show help and exit -s <secret> or --secret <secret>: 32 characters long secret for token and password encryption -p <password> or --password <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>: ID of server (default: falkor-auth)
SERVER_PORT=<port>: Port of server (default: 9999)
SERVER_DOMAIN=<domain>: Domain of the cookies to set
SERVER_HOST=<host>: Host of the server (default: 0.0.0.0)
COOKIE_NAME=<cookie>: Cookie name (default: @falkor_token)
COOKIE_TTL=<ttl>: Cookie TTL (default: 14400)
AUTH_SECRET=<secret>: 32 characters long secret for token and password encryption
AUTH_HEADER_USER=<user>: User response header name (default: X-Falkor-Header)
AUTH_HEADER_ROLE=<role>: Role response header name (default: X-Falkor-Role)
AUTH_DB=<db>: User database address (mongodb:// or mongodb+srv:// address)
LOG_TIMESTAMP=<stamp>: Add timestamp to logs (default: true)
LOG_LEVEL=<level>: Log level (default: debug)
LOG_FILE=<file>: Log file destination, if set logs will be dumped here

SEE: Example config.env 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 <domain> or --domain <domain>
- SERVER_DOMAIN=<domain>
16 characters long secret for token encryption:
- -s <secret> or --secret <secret>
- AUTH_SECRET=<secret>
User database address (or relative path to .yml file in debug builds):
- -D <db> or --db <db>
- AUTH_DB=<db>

User Data

The server needs an existing MongoDB database, for testing purposes one can create a free account at MongoDB Atlas. The application will assume the following database setup:

Database: authentication
Collection: users
Entries:

{
    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 <your-secret> --password <your-password>

Or from the installed project's root:

$ npm run passwd -- --secret <your-secret> --password <your-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:

Further Development

The project uses the @falkor/falkor-bundler module to compile sources. To clone the repository and compile falkor-auth-server one can use the commands:

$ git clone --branch develop git@github.com:theonethread/falkor-auth-server.git
$ cd falkor-auth-server
$ npm install
$ npm run [ debug | release ]

SEE: "scripts" entry in package.json for further reference.

NOTE: Compiling the develop sources might need locally linked develop versions of downstream module:

@falkor/falkor-bundler

SEE: npm-link 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 - for further details see @falkor/falkor-bundler.

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:

users:
  - name: string
    pass: string
    roles: [string]

SEE: Example auth.yml 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 and man/passwd.md.

To recompile the manuals, make sure that Pandoc is installed, and present in the PATH, then run:

$ npm run man

Linting

The project uses prettier for code formatting and cspell 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 and cspell.config.cjs for further reference.

To fix formatting issues run $ npx prettier --write <path-to-file>. 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.

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, git tags are prefixed with a v character.

GitHub Actions

The workflows can be found here.

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 and Snyk 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 - based on disclose.io's best practices.

Free and Open Source

The latest sources can always be found on GitHub.

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 for a quick heads-up!

License

MIT