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 for NetAuth, you will need to install from source. To install from source you will need a working Go environment at or above version 1.10. Your environment must also have the dep dependency manager available, either via native package or via installation with go get.

Obtain the Source

Obtain the source with go get as shown. Dependencies are not vendored, so this will not attempt to build the source.

$ go get -d github.com/NetAuth/NetAuth/cmd/...

This will download the source to your GOPATH. Now you should obtain the dependencies:

$ cd $GOPATH/src/github.com/NetAuth/NetAuth
$ dep ensure

Building the Binaries

Once you have obtained the source, you may build the server and client.

$ go get github.com/NetAuth/Netauth/cmd/...

Your compiled binaries will be in $GOPATH/bin/. As with all Go programs, the binary artifacts are statically compiled and may be copied anywhere on your filesystem.

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"

[server]
  bind = "localhost"
  bootstrap = ""
  port = 8080

[tls]
  certificate = "keys/tls.crt"
  key = "keys/tls.key"
  pwn_me = false

[token]
  backend = "jwt-rsa"
  lifetime = "10h0m0s"
  renewals = 5

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:

  • /etc/netauth/config.toml
  • $HOME/.netauth/config.toml
  • $(pwd)/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 database for persistence. You must choose what kind of database you wish to use with NetAuth. A discussion of available databases can be found below.

ProtoDB

ProtoDB is the default storage engine for NetAuth. This option will simply use directories and files on disk to store the protocol buffers that represent NetAuth's internal state. This option should be reasonably performant for many users and should scale well across small to medium installations.

ProtoDB is safe to synchronize across multiple servers for high availability and the disk state is consistent as much as possible, but a crash during a write may corrupt the entity or group that was being written, so it is recommended to backup the data directory regularly.

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.

netauth

Interact with the NetAuth system.

Synopsis

NetAuth is an authentication and authorization system for small to medium scale networks. This tool is designed to be the root point of interaction with the NetAuth system and is divided up into subsystems and subcommands for interaction with specific facets of the NetAuth ecosystem.

Options

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
  -h, --help            help for netauth
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth auth

Use and set authentication data

Synopsis

The auth subystem deals in authentication information. This includes secrets and tokens. Here you'll find the commands to change secrets, chec them, get and destroy tokens and other intesting tasks around authentication.

Options

  -h, --help   help for auth

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth auth change-secret

Change an entity secret

Synopsis

The change-secret command is used to change an entity's secret either reflexively (the entity requests the change) or administratively (another entity changes the secret).

netauth auth change-secret [flags]

Examples

$ netauth auth change-secret
Old Secret:
New Secret:
Verify Secret:
Secret Changed

$ netauth auth change-secret --csEntity demo
New Secret:
Verify Secret:
Secret Changed

Options

      --csEntity string   Entity to change secret
      --csSecret string   Secret (omit for prompt)
  -h, --help              help for change-secret

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth auth check

Check authentication credentials

Synopsis

The check command can be used to check authentication values without requesting a token. This command simply sends the values to the server and returns the status from the server with no other processing. The entity that is checked can be influenced with the global entity flag.

netauth auth check [flags]

Examples

$ netauth auth check
Secret:
Entity authentication succeeded

Options

  -h, --help   help for check

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth auth get-token

Request a new token from the server

Synopsis

get-token retrieves a token from the server if one is not already available locally. If a token is available locally and is still valid, the server will not be contacted.

netauth auth get-token [flags]

Options

  -h, --help   help for get-token

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth auth inspect-token

Inspect a token locally

Synopsis

inspect-token prints a token for inspection locally. Specifically it prints the claims held in an encoded token. Tokens are summoned on demand, and this command will trigger an implicit call to get-token if no local token is valid or available.

netauth auth inspect-token [flags]

Options

  -h, --help   help for inspect-token

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth auth validate-token

Validate a token with the server

Synopsis

validate-token sends the token to the server for validation. The server may perform additional scrutiny to satisfy the token's legitimacy, and the result will be returned with the status of the token.

netauth auth validate-token [flags]

Examples

$ netauth auth validate-token
Token verified

Options

  -h, --help   help for validate-token

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth auth destroy-token

Destroy an existing local token

Synopsis

destroy-token makes a best effort to remove the local token from the system. When this command returns the local token will either have been destroyed or an error will be printed. If this command returns an error you cannot assume that the token has been removed!

netauth auth destroy-token [flags]

Examples

$ netauth auth destroy-token
Token destroyed.

Options

  -h, --help   help for destroy-token

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity

Manage entities and associated data

Synopsis

Manage entities and associated data

Options

  -h, --help   help for entity

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity create

Create a new entity with the specified ID

Synopsis

Create an entity with the specified ID. Though there are no strict requirements on the ID beyond it being a single word that is globally unique, it is strongly encouraged to make it exclusively of lower case letters and numbers. For the best compatibility, it is recommended to start with a letter only.

Additional fields can be specified on the command line such as the number to assign or the initial secret to set. If left blank the number will be chosen as the next unassigned number, and the secret will be prompted for. To create an entity with an unset secret, specify the empty string as the initial secret.

The caller must posess the CREATE_ENTITY capability or be a GLOBAL_ROOT operator for this command to succeed.

netauth entity create <ID> [flags]

Options

  -h, --help                    help for create
      --initial-secret string   Initial secret.
      --number int              Number to assign. (default -1)

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity info

Fetch information on an existing entity

Synopsis

The info command can return information on any entity known to the server. The output may be filtered with the --fields option which takes a comma seperated list of field names to display.

netauth entity info <entity> [flags]

Options

      --fields string   Fields to be displayed
  -h, --help            help for info

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity search

Search entities on the server

Synopsis

The search command allows complex searching within entities. This command takes a single argument which is the search expression, be sure to quote the expression if making a complex query.

All set fields on returned entities will be displayed. To display only certain fields pass a comma seperated list to the --fields argument of the field names you wish to display.

Some fields on entities are part of the metadata, to address these fields in a search prefix them with 'meta.' as in 'meta.DisplayName'.

netauth entity search <expression> [flags]

Examples

$ netauth entity search 'ID:demo*'
ID: demo2
Number: 9
ID: demo3
Number: 10
ID: demo4
Number: 11

$ netauth entity search 'meta.Shell: /bin/bash'
ID: demo3
Number: 10
shell: /bin/bash

Options

      --fields string   Fields to be displayed
  -h, --help            help for search

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity update

Update metadata on an entity

Synopsis

The update command updates the typed metadata stored on an entity. Fields are updated with the flags from this command, and are overwritten with anything specified.

netauth entity update [flags]

Examples

netauth entity update demo2 --displayName "Demonstation User"
Metadata Updated

Options

      --GECOS string            GECOS
      --badgeNumber string      Badge number
      --displayName string      Display name
      --graphicalShell string   Graphical shell
  -h, --help                    help for update
      --homedir string          Home Directory
      --legalName string        Legal name
      --primary-group string    Primary group
      --shell string            User command interpreter

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity lock

Lock the entity with the specified ID

Synopsis

Lock an entity with the specified ID. A locked entity cannot authenticate successfully, even when presenting the correct secret.

The caller must posess the LOCK_ENTITY capability or be a GLOBAL_ROOT operator for this command to succeed.

netauth entity lock <ID> [flags]

Options

  -h, --help   help for lock

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity unlock

Unlock the entity with the specified ID

Synopsis

Unlock an entity with the specified ID. A locked entity cannot authenticate successfully, even when presenting the correct secret.

The caller must posess the UNLOCK_ENTITY capability or be a GLOBAL_ROOT operator for this command to succeed.

netauth entity unlock <ID> [flags]

Options

  -h, --help   help for unlock

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity key

Manage keys on an entity

Synopsis

The keys command manages the keys that are stored directly on an entity. Since the metadata for entities is public it is important to only ever store public keys on the entity. Most commonly this feature would be used to store SSH keys that should be trusted across the network.

The default key type is always SSH, and keys are matched exactly. It can be useful to copy and paste a key from the list output to remove it.

netauth entity key [flags]

Examples

$ netauth entity key add SSH "ssh-rsa this-is-too-short-but-whatever root@everywhere"
$ netauth entity key list
Type: SSH; Key: ssh-rsa this-is-too-short-but-whatever root@everywhere
$ netauth entity key del "ssh-rsa this-is-too-short-but-whatever root@everywhere"
$ netauth entity key list

Options

      --entityID string   Entity to change keys for (omit for request entity)
  -h, --help              help for key

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity kv

Manage KV storage on an entity

Synopsis

The KV subsystem allows NetAuth to store additional arbitrary metadata. Use of this system should be carefully balanced against the performance impact since this data is stored on entities directly, and as such can impact access times.

The KV system supports indexed keys, which are of the form key{index} and are sortable by the client. For example, if you had multiple phone numbers that you wanted to keep in order based on the order in which they are preferred. The following arrangement would accomplish this ordering:

phone{0}: 1 (555) 867-5309
phone{1}: 1 (555) 888-8888
phone{2}: 1 (555) 090-0461

If you wanted to change a single key, you could either upsert it which will insert or update as necessary, or you could remove it. To remove the key use either CLEARFUZZY or CLEAREXACT. The exact variant allows you to specify the exact key with index to clear, whereas the fuzzy version doesn't check the index before clearing (useful for bulk removing a key).

netauth entity kv <entity> <UPSERT|CLEARFUZZY|CLEAREXACT|READ> <key> [value] [flags]

Examples

$ netauth entity kv demo2 upsert phone{0} "1 (555) 867-5309"
$ netauth entity kv demo2 upsert phone{1} "1(555) 888-8888"
$ netauth entity kv demo2 upsert phone{2} "1(555) 090-0461"

$ netauth entity kv demo2 read phone
phone{0}: 1 (555) 867-5309
phone{1}: 1 (555) 888-8888
phone{2}: 1 (555) 090-0461

$ netauth entity kv demo2 clearexact phone{1}
$ netauth entity kv demo2 read phone
phone{0}: 1 (555) 867-5309
phone{2}: 1 (555) 090-0461

$ netauth entity kv demo2 clearfuzzy phone
$ neatuth entity kv demo2 read phone

Options

  -h, --help   help for kv

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity membership

Add or remove direct group memberships

Synopsis

The membership command adds and removes groups from an entity. These groups are direct memberships that are only influenced by EXCLUDE expansions.

The caller must posses the MODIFY_GROUP_MEMBERS capability or be a member of the group that is listed to manage the membership of the target group.

netauth entity membership <entity> <ADD|DROP> <group> [flags]

Examples

$ netauth entity membership demo2 add demo-group
Membership updated successfully

$ netauth entity membership demo2 drop demo-group
Membership updated successfully

Options

  -h, --help   help for membership

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity memberships

Memberships held by the specified entity

Synopsis

The membership command adds and removes groups from an entity. These groups are direct memberships that are only influenced by EXCLUDE expansions.

The caller must posses the MODIFY_GROUP_MEMBERS capability or be a member of the group that is listed to manage the membership of the target group.

netauth entity memberships <entity> [flags]

Examples

$ netauth entity memberships demo2
Name: demo-group
Display Name: Temporary Demo Group
Number: 9

$ netauth entity memberships demo2 --fields DisplayName
Display Name: Temporary Demo Group

Options

      --fields string   Fields to be displayed
  -h, --help            help for memberships
      --indirect        Include indirect memberships (default true)

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth entity destroy

Destroy an existing entity

Synopsis

Destroy the entity with the specified ID. The entity is deleted immediately and without confirmation, please ensure you have typed the ID correctly.

It is possible to remove the entity running the command, but this is not recommended and may leave your system without any administrative users.

The caller must posess the DESTROY_ENTITY capability or be a GLOBAL_ROOT operator for this command to succeed.

netauth entity destroy <ID> [flags]

Options

  -h, --help   help for destroy

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth group

Manage groups and associated data

Synopsis

Manage groups and associated data

Options

  -h, --help   help for group

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth group create

Create a new group

Synopsis

Create an group with the specified name. Though there are no strict requirements on the name beyond it being a single word that is globally unique, it is strongly encouraged to make it exclusively of lower case letters and numbers. For the best compatibility, it is recommended to start with a letter only.

Additional fields can be specified on the command line such as the display name, or a group to defer management capability to. If desired a custom number can be provided, but the default behavior is sufficient to select a valid unallocated number for the new group.

The caller must posess the CREATE_GROUP capability or be a GLOBAL_ROOT operator for this command to succeed.

netauth group create <name> [flags]

Examples

$ netauth group create demo-group
New group created successfully

Options

      --display-name string   Group display name
  -h, --help                  help for create
      --managed-by string     Delegate management to this group
      --number int            Number to assign. (default -1)

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth group info

Fetch information on an existing group

Synopsis

The info command retursn information on any group known to the server. The output may be filtered with the --fields option which takes a comma seperated list of field names to display.

netauth group info <group> [flags]

Examples

$ netauth group info example-group
Name: example-group
Display Name:
Number: 10
Expansion: INCLUDE:example-group2

Options

      --fields string   Fields to be displayed
  -h, --help            help for info

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth group search

Search entities on the server

Synopsis

The search command allows complex searching within groups. This command takes a single argument which is the search expression, be sure to quote the expression if making a complex query.

All set fields on returned groups will be displayed. To display only certain fields pass a comma seperated list to the --fields argument of the field names you wish to display.

netauth group search <expression> [flags]

Examples

$ netauth group search 'Name:example*'
Name: example-group
Display Name:
Number: 10
Expansion: INCLUDE:example-group2
Name: example-group2
Display Name:
Number: 11

Options

      --fields string   Fields to be displayed
  -h, --help            help for search

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth group update

Update metadata on an group

Synopsis

The update command updates the typed metadata stored on an group. Fields are updated with the flags from this command, and are overwritten with anything specified.

netauth group update [flags]

Examples

netuath group update example-group --display-name "Example Group"
Group modified successfully

Options

      --display-name string   Display Name
  -h, --help                  help for update
      --managed-by string     Dlegated management group

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth group kv

Manage KV storage on an group

Synopsis

The KV subsystem allows NetAuth to store additional arbitrary metadata. Use of this system should be carefully balanced against the performance impact since this data is stored on groups directly, and as such can impact access times.

The KV system supports indexed keys, which are of the form key{index} and are sortable by the client. For example, if you had multiple phone numbers that you wanted to keep in order based on the order in which they are preferred. The following arrangement would accomplish this ordering:

phone{0}: 1 (555) 867-5309
phone{1}: 1 (555) 888-8888
phone{2}: 1 (555) 090-0461

If you wanted to change a single key, you could either upsert it which will insert or update as necessary, or you could remove it. To remove the key use either CLEARFUZZY or CLEAREXACT. The exact variant allows you to specify the exact key with index to clear, whereas the fuzzy version doesn't check the index before clearing (useful for bulk removing a key).

netauth group kv <group> <UPSERT|CLEARFUZZY|CLEAREXACT|READ> <key> [value] [flags]

Examples

$ netauth group kv demo2 upsert phone{0} "1 (555) 867-5309"
$ netauth group kv demo2 upsert phone{1} "1(555) 888-8888"
$ netauth group kv demo2 upsert phone{2} "1(555) 090-0461"

$ netauth group kv demo2 read phone
phone{0}: 1 (555) 867-5309
phone{1}: 1 (555) 888-8888
phone{2}: 1 (555) 090-0461

$ netauth group kv demo2 clearexact phone{1}
$ netauth group kv demo2 read phone
phone{0}: 1 (555) 867-5309
phone{2}: 1 (555) 090-0461

$ netauth group kv demo2 clearfuzzy phone
$ neatuth group kv demo2 read phone

Options

  -h, --help   help for kv

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth group expansion

Alter group expansions

Synopsis

The expansion command manages expansion rules for groups. Expansions can be a powerful tool to make your server's memberships easier to manage, but care should be taken to ensure your expansions remain maintainable. The expansions system will ensure that cycles are not introduced to the membership graph, but no checks are performed for the sanity of the rules requested or the maintainability of the resulting graph. Rules require the membership tree to be parsed for rules at all levels, and use of expansion rules should be carefully weighed against the performance requirements of your organization.

There are two types of expansions in NetAuth: INCLUDE and EXCLUDE. Both of these expansions take a target to act on and are applied to a single group. In writing, group expansions should be formatted as :target. For example INCLUDE:sub-group.

The INCLUDE expansion does exactly what the name implies. Members of the target group gain membership in the named group without being added to it directly. This expansion is convenient for building up organizational trees where you might want to translate some easily statable relation into a group membership. For example the group "eng" might include all members of "dev" and "ops". By adding these exansions the membership of "eng" is kept up to date without additional effort.

The EXCLUDE expansion is slightly more complicated. Members of the target group are excluded from membership in the source group even if they are otherwise directly members. This can be useful if you have a need to prune out some memberships without removing groups from individuals. For example if you have contractors that can't access production data but otherwise need to be members of groups that grant such access, you could create a new group "production-data" that gates this access and has an expansion of EXCLUDE:contractors where "contractors" contains all contractor owned users (possibly even via includes). This would allow you to maintain groups that make sense to humans while still removing people from groups they shouldn't logically be in.

Removing an expansion can be done by adding an expansion of the DROP type. DROP expansions aren't actually expansions, but they select existing rules to remove.

netauth group expansion <group> <INCLUDE|EXCLUDE|DROP> <target> [flags]

Examples

$ netauth group expansion example-group include example-group2
Nesting updated successfully

Options

  -h, --help   help for expansion

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth group destroy

Destroy an existing group

Synopsis

Destroy the group with the specified name. The group is deleted immediately and without confirmation, please ensure you have typed the ID correctly.

Referential integrity is not checked before deletion. You are strongly encouraged to empty groups before deleting them as well as remove any expansions that target the group to be deleted.

The caller must posess the DESTROY_GROUP capability or be a GLOBAL_ROOT operator for this command to succeed.

netauth group destroy <name> [flags]

Examples

$ netauth group destroy demo-group
Group removed successfully

Options

  -h, --help   help for destroy

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth system

Internal system functions

Synopsis

Internal system functions

Options

  -h, --help   help for system

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth system capability

Manage internal system capabilities

Synopsis

NetAuth makes use of a capabilities based system for internal access control. The capabilities command can add and remove capabilities from entities and groups. The preferred mechanism for access control should always be to gain capabilities by being in a group that has them, rather than having access applied to entities directly. A description of each capability follows:

GLOBAL_ROOT - Confers all other capabilities implicitly. This power is used to bootstrap the server and should be reserved to super administrators that would otherwise be able to obtain this power.

CREATE_ENTITY - Allow the creation of entities.

DESTROY_ENTITY - Allows the destruction of entities.

MODIFY_ENTITY_META - Allows modification of entity metadata.

MODIFY_ENTITY_KEYS - Allows modification of entity public keys. Entities are able to change their own keys without this capability.

CHANGE_ENTITY_SECRET - Allows modification of entity secrest. Entities are able to change their own secrets without this capability.

LOCK_ENTITY - Allows setting an entity lock. Locked entities cannot successfully authenticate, even with a correct secret.

UNLOCK_ENTITY - Allows unlocking an entity.

CREATE_GROUP - Allows creation of groups.

DESTROY_GROUP - Allows destruction of groups.

MODIFY_GROUP_META - Allows the modification of group level metadata. This should generally be assigned in conjunction with.

MODIFY_GROUP_MEMBERS - Allows the modification of group memberships. This capability is not needed if the requesting entity is a member of a groups designated management group.

netauth system capability <identifier> <ADD|DEL> <capability> [flags]

Examples

$ netauth system capability example-group add MODIFY_GROUP_META
Capability Modified

$ netauth system capability --direct demo2 add MODIFY_GROUP_META
You are attempting to add a capability directly to an entity.  This is discouraged!
Capability Modified

Options

      --direct   Provided identifier is an entity
  -h, --help     help for capability

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth system ping

Ping the server and print the reply

Synopsis

The ping command provides an easy way to interogate a server and find if it is behaving as expected. The ping command requests a server to pong back if with its health status.

netauth system ping [flags]

Examples

$ netauth system ping
NetAuth server on theGibson is ready to serve!

Options

  -h, --help   help for ping

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth system cli

Extra utilities for the CLI

Synopsis

Extra utilities for the CLI

Options

  -h, --help   help for cli

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth system cli bash

Generate bash completions at

Synopsis

Generate bash completions at

netauth system cli bash <path> [flags]

Options

  -h, --help   help for bash

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth system cli zsh

Generate zsh completions at

Synopsis

Generate zsh completions at

netauth system cli zsh <path> [flags]

Options

  -h, --help   help for zsh

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth system cli man

Generate man pages at

Synopsis

Generate man pages at

netauth system cli man <path> [flags]

Options

  -h, --help   help for man

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019

netauth system cli md

Generate md pages at

Synopsis

Generate md pages at

netauth system cli md <path> [flags]

Options

  -h, --help   help for md

Options inherited from parent commands

      --config string   Use an alternate config file
      --entity string   Specify a non-default entity to make requests as
      --secret string   Specify the request secret on the command line

SEE ALSO

Auto generated by spf13/cobra on 18-Aug-2019