Introduction

NetAuth is a secure authentication and authorization provider for small to medium scale installations. It provides a complete directory solution suitable for Linux systems operated in a domain-style environment and is suitable as a backend identity provider for arbitrary systems.

Key features of NetAuth include:

Only one binary for the authentication and authorization provider. This greatly simplifies deployment, upgrades, and management.
Simple and easy to use control binaries that do the right thing.
Documentation that is not from a defunct company.
An easy to build for RPC interface based on gRPC.

Getting Started

To get started with NetAuth, you will need to install the NetAuth binaries, create certificates, and initialize the server.

This manual includes recommendations for all options, but you can of course choose your own adventure.

Installation

To use NetAuth you will obviously need to install it. You may either install from source or from a packaged binary. The NetAuth project does not provide binaries for download.

From Packages

If your distribution provides a package for NetAuth that is likely the easiest way to install it. Make sure that your distribution packages a recent version if you choose to go this route.

At present, the following distributions are known to package NetAuth:

Void Linux

From Source

If your distribution does not provide packages, or if you do not wish to use them, you can compile from source:

$ git clone -b <version> git://github.com/netauth/netauth
$ cd netauth
$ go build -o netauthd github.com/netauth/netauth/cmd/netauthd
$ go build -o netauth github.com/netauth/netauth/cmd/netauth
$ go build -o nsutil github.com/netauth/netauth/cmd/nsutil

You can now copy the binaries to wherever your system stores binaries that are locally managed. Typically this will be /usr/local/bin.

Setup

Once you have installed the server, you will need to set it up.

NetAuth has a single configuration file which configures both clients and servers. The configuration file is handled by Viper and can be parsed as TOML, JSON, or YAML. TOML is the canonical format and the format that will be shown in the documentation.

These are the defaults for the config file:

[core]
  home = ""

[crypto]
  backend = "bcrypt"

  [crypto.bcrypt]
    cost = 15

[db]
  backend = "ProtoDB"

[log]
  level = "INFO"

[pdb]
  watch-interval = "1s"
  watcher = false

[plugin]
  path = "plugins"

[server]
  bind = "localhost"
  port = 1729

[tls]
  certificate = "keys/tls.pem"
  key = "keys/tls.key"

[token]
  backend = "jwt-rsa"
  lifetime = "10m0s"

  [token.jwt]
    bits = 2048
    generate = false

A suitable configuration file can be as little as:

[core]
  home = "/var/lib/netauth"
[server]
  bind = "0.0.0.0"

Configuration files are resolved on a first-found basis from the following locations:

$(pwd)/config.toml
$HOME/.netauth/config.toml
/etc/netauth/config.toml

It is recommended to use a job control system to run the NetAuth server, this can be be handily done with runit which is available for many distributions. A complete runit service file is shown below:

#!/bin/sh

cd /var/lib/netauthd || exit 1

exec chpst -u _netauthd:_netauthd netauthd 2>&1

Database

All entities and groups are stored in a key/value store. These key/value stores are indexed at server startup to be searchable, and are considered an opaque storage solution. A brief discussion of the available storage engines follows:

Filesystem

The filesystem backend is cross platform and will work on all operating systems that Go can target. It writes out keys as individual regular files to the filesystem. This backend is great for getting started, but can suffer from performance problems with very large numbers of entities or groups.

You can select this backend with the following configuration:

[db]
  backend = "filesystem"

Bitcask

Bitcask is a highly performant memory mapped storage option that is only supported on select platforms. In general if running on a Linux platform, this is the backend to use. Bitcask stores the data in a memory mapped datastore that is extremely fast up to tens of thousands of entities and groups.

You can select this backend with the following configuration:

[db]
  backend = "bitcask"

Cryptography

NetAuth stores secrets for entities. These secrets need to be cryptographically armored so that they can be stored with confidence. The cryptography engines of NetAuth are implemented on a plugin architecture, and can be chosen based on the needs of a particular site.

Swapping cryptography systems is not supported, so choose carefully. It is possible to build an engine that supports reencryption or re-hashing, but the provided engines do not do this.

bcrypt

The bcrypt engine is the only one compiled in by default. From Wikipedia:

bcrypt is a password hashing function designed by Niels Provos and David Mazières, based on the Blowfish cipher, and presented at USENIX in 1999. Besides incorporating a salt to protect against rainbow table attacks, bcrypt is an adaptive function: over time, the iteration count can be increased to make it slower, so it remains resistant to brute-force search attacks even with increasing computation power.

bcrypt is the default engine and unless you have a good reason why you should implement another cryptography engine, stick with the defaults. It is selected in configuration with the following values:


[crypto]
  backend = "bcrypt"

  [crypto.bcrypt]
    cost = 15

The cost value may be adjusted to change the hashing difficulty. Higher cost roughly translates to better resistance to attack for the hashes.

Plugins

Plugins are a mechanism to extend the behavior of the NetAuth server. Additional information can be read in the original release announcement.

The plugins are stored in a directory that the NetAuth server will look at on startup, controlled by values in the [plugin] stanza of the configuration file. By default the plugins will be loaded from ${HOME}/plugins/, where ${HOME} is the server's defined home directory.

Additional values in the plugin stanza of note:

enabled - By default the plugin subsystem is enabled by default. If for some reason you wish to disable the plugin system set this value false.
path - This is the path that plugins will be searched in. If this path is relative it will be computed relative to the server's home directory.
loadstatic - This variable controls whether or not the server will perform automatic discovery of plugins in teh path defined by the variable above. If this is set then list must also be defined.
list - This is a list of plugins which can be loaded from the path defined above.

netauth

Interact with the NetAuth system.

NetAuth Administrative Manual