jwt-user-service

A simple REST-based user authentication service, for SOA-Environments.

Installation

npm install jwt-user-service

Configuration

Configuration of the service should be done entirely by environment variables for security reasons.

Custom Configuration File

You can provide a customized configuration by setting its path in JWT_USER_SERVICE_CONFIG_FILE.
Your configuration file must be in JSON-Format, and provide the same keys found in config.json.

Service

| Environment Variable Name | Description | Default Value | | ----------------------------- |:-------------: | --------------:| | JWT_USER_SERVICE_PORT | Server TCP Port | 8080 | | JWT_USER_SERVICE_ADMIN_USERNAME | not used yet | "admin" | | JWT_USER_SERVICE_ADMIN_PASSWORD | not used yet | "changeit" |

JWT

| Environment Variable Name | Description | Default Value | | ----------------------------- |:-------------: | --------------:| | JWT_USER_SERVICE_JWT_SECRET | JWT Signature Secret - use when no RSA keys defined | "change it" | | JWT_USER_SERVICE_JWT_EXPIRE | Expiry offset in seconds | 3600 | | JWT_USER_SERVICE_JWT_PRIVATE_KEY | RSA Private Key (content, not file path) | null | | JWT_USER_SERVICE_JWT_PUBLIC_KEY | RSA Public Key (content, not file path) | null |

Storage / Persitence

| Environment Variable Name | Description | Default Value | | ----------------------------- |:-------------: | --------------:| | JWT_USER_SERVICE_STORAGE_DRIVER | Module name or path of a storage-module for persitence | "./lib/database/fs" | | JWT_USER_SERVICE_STORAGE_FILENAME | Filename for the built-in "FS"-storage driver | "./app-data/user.db" |

Encryption (for passwords)

| Environment Variable Name | Description | Default Value | | ----------------------------- |:-------------: | --------------:| | JWT_USER_SERVICE_CRYPT_MODULE | Module name or path of an encryption module | "./lib/crypt" | | JWT_USER_SERVICE_CRYPT_SALT | Salt-value for the built-in encryption module | "change this, too" |

Usage

Start the service on the command line with jwt-user-service.
There are no command line arguments currently.

REST API

| Method | Path | Parameters | Description | | -------| ------------- | ------------- | --------------:| | POST | / | { username, password, userData } | Create a new user | | POST | /token | { username, password } | Login / Get JW-Token | | PUT | /{userId} | { any } | Modify user data | | PUT | /{userId}/password | string | Change user password |

Storage Driver

You can (and propably should) provide a custom storage driver for persitence.
The driver is meant to be an interface for your database, filesystem or some other web-based service.
It should be simple to implement a storage driver for MySQL, MongoDB or whatever IO-device you choose.

A storage driver is a Node.JS-Module with a specific API:

module.exports = async function CustomStorageDriver(config /* from config.storage */) {
    // Initialize database / persitence layer....

    return {
        insert: async data => {
            // db.insert(data)...
            return data; // simply return the inserted data
        },
        findOne: async id => /* find entry by id in database */,
        update: async (id, changes) => {
            // find entry by id and update
            return entry; // return the modified entry
        },
        remove: async id => {
            // remove entry by id
            // return nothing
        }
    }
}

The storage driver is supposed to throw exceptions on errors.
You might need to provide a custom configuration file to access your database.

Password encryption

Of course, passwords shall never be stored as plain text.
Therefor, this service provides a simple hash module, to encrypt user passwords.
If you use an existing database (with your own storage driver), you may already have encrypted passwords.
To enable the login-feature you'll need the same encryption-algorithm to match a user's credentials.
In that case, providing a custom encryption module is necessary.

Encryption module API:

module.exports = function CustomCryptModule(config /* from config.crypt */) {
    return {
        encode: dataString => {
            // Encrypt data (don't forget to salt)
            return encryptedDataString;
        }
    }
}

Custom Configuration

The service configuration consists of an object containing sub-objects for each service module.

Minimal configuration:

{
    "server": {
        "port": 8080
    },
    "jwt": {
        "expire": 3600,
        "secret": "<some secret>",
        /* OR */
        "privateKey": "-----BEGIN RSA PRIVATE KEY........",
        "publicKey": "-----BEGIN RSA PUBLIC KEY........"
    },
    "storage-driver": "path/to/driver.module.js",
    "storage": {
        /* your custom driver configuration */
    },
    "crypt-module": "path/to/encryption.module.js",
    "crypt": {
        /* your custom encryption module configuration */
    }
}

Configuration with environment variables

As mentioned before, you should make use of the environment, instead of "hard-coding" configuration values.
Having a file on a server which includes keys, salts or secrets is always a security-issue.
To make use of variables inside your configuration file, use the following object-signature:

"configuration-key": { "env": "ENVIRONMENT_VARIABLE_NAME", "default": "some default value for testing" }

HINT Instead of a JSON-formatted configuration file, you can also provide a Node.JS-module, which exports a configuration object.