NAV Navbar

Notakey Authentication Appliance

Introduction

Notakey Authentication Appliance (NAA) is a Linux-based virtual machine, which contains the Notakey API software, as well as a RADIUS proxy for transparently integrating the Notakey API into existing RADIUS-based workflows.

Product Versions in Appliance

This user manual’s version number will match the corresponding appliance’s version number.

Each appliance contains the following software:

  • Notakey Authentication Server (NtkAs) (version: 2.13.5)
  • Notakey Authentication Proxy (NtkAp) (version: 1.0.4)
  • VRRP agent (VRRPa) (version: 2.0.6)
  • Notakey SSO (NtkSSO) (version: 2.3.3)

The appliance version number, or this user manual’s version number, will not typically match the version numbers of either NtkAs or NtkAp.

Technical Summary

The appliance is a self-contained environment, with no (mandatory) external dependencies, where the Notakey software is pre-installed.

It is stripped down as much as possible - only the bare minimum system components, which are required for the software to operate, are left on the system. This keeps the potential attack surface to a minimum.

No root-level user is available, to not negatively impact the appliance’s functions. In case critical system-component patches need to be applied, a new appliance version will have to be deployed. Tools will be provided to transfer appliance state between different versions.

Default management user

Username Password
ntkadmin ntkadmin

This user does not have root access, but it does have the permissions to perform administrative changes to the appliance using the ntk utility (see below).

Appliance licences and versions

Each appliance has an associated licence-type and an associated version.

Appliances with the same version, but different licences, support the same features. Feature availability is determined by the licence version. Throughout this document, features whose availability depends on the licence type, will be specially annotated.

Licence Type Description
Express Entry-level licence meant for small deployments (sub-50 users) and lower security/availability requirements.
Enterprise Full-featured licence, with no limitations.

System Requirements

Hypervisor Compatibility

The following table is a appliance version/hypervisor compatibility matrix:

Appliance Version Supported Virtualization Environments
<= 3.* Hyper-V (Windows Server 2012 R2 and newer)
VMware ESXi 5.5 (and newer)

VMware Information

The following table contains information about different appliance versions, as it pertains to VMware ESXi.

Appliance Version Virtual Hardware Version
<= 3.* vmx-09

Hardware Requirements

The Notakey service is typically CPU bound. Most operations are reading from an in-memory store.

Minimum Requirements (Less Than 1000 Users)

For a deployment with less than 1000 users, the suggested requirements are:

Resource Value
RAM 2 GB
vCPU 2
CPU type 2.3 GHz Intel Xeon® E5-2686 v4 (Broadwell)
Storage 32 GB SSD

Suggested Requirements

For a typical deployment, with up to 300 000 users, the suggested hardware requirements are:

Resource Value
RAM 8 GB
vCPU 8
CPU type 2.3 GHz Intel Xeon® E5-2686 v4 (Broadwell)
Storage 256 GB SSD

High Availability

You can check a node’s health status via the exposed API

$ curl -XGET https://demo.notakey.com/api/health
{"STATUS":"LIVE"}

The Notakey Authentication Server exposes a health-check HTTP endpoint, which can be used by load-balancers, to dynamically route traffic.

An HTTP GET request to /api/health should return JSON object with key STATUS and value LIVE.

If not, the node should be considered unhealthy.

Extended Healthcheck

The healthcheck API can return more detailed information about the Authentication Server health, than just OK. To retrieve more detailed information, append the ?ext query parameter to GET /api/health. E.g.:

$ curl -XGET https://demo.notakey.com/api/health?ext
{"STATUS":"LIVE","PID":"58","VIRT":"1564024","RES":"449556","SHR":"10096","S":"S","%CPU":"0.0","%MEM":"21.9","TIME+":"3:04.99"}

The returned information will be a representation of the resources consumed by the Authentication Server process on the appliance.

Key Description
PID Server’s process ID on the appliance.
VIRT Virtual size of the server’s process (i.e. the sum of the memory it is actually using).
RES Resident size of the server’s process (i.e. the amount of physical memory the process is consuming).
SHR Indicates the amount of virtual memory (VIRT) that is shareable with other processes.
S The server’s process state code. Available codes are:
D - uninterruptible sleep
R - running
S - sleeping
T - traced
Z - zombie
%CPU Percentage of the CPU that is currently being consumed by the Authentication Server.
%MEM Percentage of the available physical memory that is currently being consumed by the Authentication Server.
TIME+ Total CPU-time the Authentication Server process has consumed since starting.

Node Configuration in the Cluster

Licence type Node configuration
Express active/active - each node can process requests meant for either node.
Enterprise N-to-N - each node can process requests meant for either node.

Availability considerations

In case of 2-node deployments, if 1 node fails its healthcheck (or becomes unavailable), traffic can be routed to the other route.

NOTE: both nodes are required to be operational, for full service. If 1 nodes is not operational, then the remaining node will operate in a limited capacity.

It will allow:

  • new authorization requests for existing users

It will not allow:

  • onboarding new users
  • changing onboarding requirements
  • creating new applications
  • editing existing applications or users

In addition, the partially operational node will not log authorization requests in the web user interface. It will still be possible, however, to log these requests to rsyslog (if so configured).

General failure tolerance depends on the total number of nodes. To maintain data integrity, a quorum of servers must be available, which can be calculated with the formula Cquorum = FLOOR(Cservers / 2) + 1.

The failure tolerance can be calculated by FT = Cservers - Cquorum.

In other words - more than half of the total available servers must be available and operational.

Total servers Quorum size Failure tolerance
1 1 0
2 2 0
3 2 1
4 3 1
5 3 2
6 4 2
7 4 3
8 5 3
9 5 4
10 6 4

Network Connectivity

NtkP will communicate with its RADIUS clients and the downstream RADIUS server via one UDP port. This port can be different for clients and the downstream server, but it can not be different for different clients.

Additionally, the TCP port 443 is required to be open between NtkP and the designated Notakey API endpoint.

Network Connectivity Chart

General Configuration & Maintenance

Raw Configuration Management

On a low-level, the appliance configuration happens via the ntk cfg command.

It has a set and a get subcommand, which you can use to, respectively, set and retrieve configuration values. The general syntax to set a value is:

ntk cfg setc <key> <value> [--json-input|--load-file]

and to read a value:

ntk cfg getc <key>

All relevant configuration keys are hierarchical, separated by a dot. E.g. the configuration key for the node’s name would be node.name and the configuration key for the node’s datacenter description would be node.datacenter.

Adding emoji to appliance configuration

It is possible to add standard emojis to configuration used to generate authentication requests. Appliance stores all configuration strings using UTF-16 encoding internally, so codes for emoji should be formatted as UTF-16 character pairs and must be used in a valid combination. No character escaping is necessary.

Here is an example of configuring :sunglasses: emoji:

ntk cfg setc notakey.proxy.message_description "Hello {0}, ready to do some off-site work \uD83D\uDE0E ?"

First-time Configuration

The goal for first-time configuration is typically to get the Notakey Authentication Server up and running. The command to do so is ntk wizard followed by ntk as start.

Each time you run ntk as start, it will perform configuration sanity-checks, and output information about missing or invalid configuration values. Try it now:

$ ntk as start
==> Validating Notakey Authentication Server configuration
    Checking security settings
    Checking virtual network configuration
        required: traefik-net
    Checking software images
        required: notakey/dashboard:2.13.5
    Checking host
❌     Please set 'host' config value to the public domain

This means you need to set the configuration key with the name host.

For descriptions on what each configuration value means, see Appendix I - Configuration Keys.

The keys you will need to configure initially will be:

  • host
  • cluster.bootstrap_expect
  • cluster.is_root
  • node.advertise_ip
  • ssl.acme.status (on/off)
  • ssl.acme.email (only if ssl.acme.status is on)
  • ssl.pem (only if ssl.acme.status is off)
  • ssl.key (only if ssl.acme.status is off)

Selected values can be configured by ntk wizard configuration helper or manually with ntk cfg setc ... commands. After setting all these values, you may want to set the network settings via the ntk net subcommand. This is optional.

Finally, you are ready to start the Authentication Server via ntk as start.

$ ntk as start
[...]

# You can always query the status of the Authentication Server via
# ntk as status
$ ntk as status
Notakey Authentication Server status:
    running  (health: healthy )
Data store status:
    running  (health:  health unknown)
Reverse proxy status:
    running  (health:  health unknown)
notakey.local accessible via HTTPS: no

It is alright for the data store and reverse proxy to have an unknown health status.

TLS Settings

There are two ways to set TLS certificates:

  • setting certificates and keys directly via the configuration utility, or
  • using built-in support for the Let’s Encrypt service

Let’s Encrypt

$ ntk cfg setc ssl.acme.status on

When this configuration key is set to on, the service will attempt to request a valid certificate upon startup.

Certificate renewal will be managed automatically as well.

Setting Certificates Directly

$ ntk cfg setc ssl.acme.status off
$ ntk cfg setc ssl.pem <path/to/certificate.pem> --load-file
$ ntk cfg setc ssl.key <path/to/key.pem> --load-file

Assembling multi node cluster

Any licensing model allows cluster setup starting from two nodes. Nodes in cluster can be located in single virtual datacenter or can be deployed on multiple datacenters provided that there is a reliable communications link between nodes. If no L2 network cannot be provided between datacenters advanced configuration is possible deploying a private routed network between nodes.

Configuration of first node

  • Start with basic configuration wizard.
[ntkadmin@appserver-1/mydomain]$ ntk wizard

 _______          __          __
 \      \   _____/  |______  |  | __ ____ ___.__.
 /   |   \ /  _ \   __\__  \ |  |/ // __ <   |  |
/    |    (  <_> )  |  / __ \|    <\  ___/\___  |
\____|__  /\____/|__| (____  /__|_ \___  > ____|
        \/                 \/     \/    \/\/

    Welcome to the Notakey Authentication Appliance
    configuration wizard.

    This wizard is meant to guide you through the initial
    setup.

    Advanced configuration is always available via the 'ntk'
    command. Consult the user manual for more details.


==> Detecting network interfaces
==> Gathering information
    Enter the desired domain name (e.g. ntk.example.com): ntk.example.com
    Enter the node hostname: appserver-1
    Enter the cluster datacenter name/local domain: mydomain
    Detected interfaces: eth0
    Enter interface for processing HTTP requests: eth0
    Use DHCP? (y/n): n

        NOTE: This wizard does not support IPv6 IP settings

              Consult the appliance user manual for more details on
              using IPv6.

    Enter the static IPv4 in CIDR notation (e.g. 10.0.1.2/24): 192.168.1.2/24
    Enter the static IPv4 gateway (e.g. 10.0.1.1): 192.168.1.1
    Enter the DNS server addresses (separate values with ,): 192.168.1.1
    Use automated SSL (Lets Encrypt?) (y/n): y
    Enter e-mail address to use for requesting SSL certificate: helpdesk@example.com
==> Please review the entered information
    Network interface: eth0
    Use DHCP: n
    Static IPv4: 192.168.1.2/24
    Static gateway: 192.168.1.1
    DNS servers: 192.168.1.1
    External domain: ntk.example.com
    Use Lets Encrypt (automatic SSL): y
    E-mail for Lets Encrypt: helpdesk@example.com
    Are these values OK? (y/n): y
==> Applying configuration
    acme... ok
    network settings... ok
    basic settings... ok
  • Configure to run management on separate port, if required.
[ntkadmin@appserver-1/mydomain]$ ntk cfg setc mgmt_port 8443
  • Apply settings by restarting appliance.
[ntkadmin@appserver-1/mydomain]$ ntk sys reboot
  • Start application and datastore in single node mode.
[ntkadmin@appserver-1/mydomain]$ ntk as start
==> Validating Notakey Authentication Server configuration
    Checking security settings
    Checking virtual network configuration
        required: traefik-net
    network exists
    Checking software images
        required: notakey/dashboard:2.5.0
    Checking host
==> Validating Notakey Authentication Server cluster configuration
    Checking node name
    Checking cluster size
    Checking if this node is cluster root... yes (root)
    Checking advertise IP
    Checking data center name
    Checking SSL
        using Lets Encrypt certificates

        IMPORTANT: make sure this instance is publicly accessible via ntk.example.com

=> Starting NAS data store
    client address: 172.17.0.1
    cluster advertise address: 192.168.1.2
    cluster size (minimum): 1
    is cluster root: 1
    started bebf41523ad60c6a222ec5b34be7bb64fd94751a95392d188c9eaa38320fc732

=> Starting new NAS instance
    net: traefik-net
    image: notakey/dashboard:2.5.0
    consulimg: consul:0.7.5
    host: naa.4.0.0.notakey.com
    cluster backend: http://172.17.0.1:8500/main-dashboard
    loglevel: info
    env: production
    secret_key_base: RYElfTFqPWP3yrUNmLyTEy/c90Lm2/1I6pg/byD15XMQtMqTUYdtMVw6FqLMWyitGRUyO
    started 4de38ddc53a013445ab2b2c3c4c33537af26e4e0e44f935c2bd1e000bec6df04

=> Starting the reverse proxy
    ACME status: on
    ACME e-mail: ingemars@ltnet.lv
    started 49fcfdada52f3d5495ae1e03b517c90578ed3dd768ee154cdf72357c898d5f7b

Subsequent node configuration

  • As on first node, start with basic configuration wizard.
[ntkadmin@appserver-2/mydomain]$ ntk wizard

 _______          __          __
 \      \   _____/  |______  |  | __ ____ ___.__.
 /   |   \ /  _ \   __\__  \ |  |/ // __ <   |  |
/    |    (  <_> )  |  / __ \|    <\  ___/\___  |
\____|__  /\____/|__| (____  /__|_ \___  > ____|
        \/                 \/     \/    \/\/

    Welcome to the Notakey Authentication Appliance
    configuration wizard.

    This wizard is meant to guide you through the initial
    setup.

    Advanced configuration is always available via the 'ntk'
    command. Consult the user manual for more details.


==> Detecting network interfaces
==> Gathering information
    Enter the desired domain name (e.g. ntk.example.com): ntk.example.com
    Enter the node hostname: appserver-2
    Enter the cluster datacenter name/local domain: mydomain
    Detected interfaces: eth0
    Enter interface for processing HTTP requests: eth0
    Use DHCP? (y/n): n

        NOTE: This wizard does not support IPv6 IP settings

              Consult the appliance user manual for more details on
              using IPv6.

    Enter the static IPv4 in CIDR notation (e.g. 10.0.1.2/24): 192.168.1.3/24
    Enter the static IPv4 gateway (e.g. 10.0.1.1): 192.168.1.1
    Enter the DNS server addresses (separate values with ,): 192.168.1.1
    Use automated SSL (Lets Encrypt?) (y/n): y
    Enter e-mail address to use for requesting SSL certificate: helpdesk@example.com
==> Please review the entered information
    Network interface: eth0
    Use DHCP: n
    Static IPv4: 192.168.1.2/24
    Static gateway: 192.168.1.1
    DNS servers: 192.168.1.1
    External domain: ntk.example.com
    Use Lets Encrypt (automatic SSL): y
    E-mail for Lets Encrypt: helpdesk@example.com
    Are these values OK? (y/n): y
==> Applying configuration
    acme... ok
    network settings... ok
    basic settings... ok
  • Setup the current node in slave mode, allowing to join to external master nodes.
[ntkadmin@appserver-2/mydomain]$ ntk cfg setc cluster.is_root 0
  • Management port should be set individually on each node, if required
[ntkadmin@appserver-2/mydomain]$ ntk cfg setc mgmt_port 8443
  • Apply settings by restarting appliance.
[ntkadmin@appserver-2/mydomain]$ ntk sys reboot
  • Issue cluster join command that will contact the root node and start data replication. This will automatically start local datastore.
[ntkadmin@appserver-2/mydomain]$ ntk cluster join 192.168.1.2
  • Verify that the nodes have successfully synced.
[ntkadmin@appserver-2/mydomain]$ ntk cluster nodes
Node           Status  IP Address  Data Center
appserver-1    alive   192.168.1.2 mydomain
appserver-2    alive   192.168.1.3 mydomain
  • When all nodes are added, on root node configure the number of total nodes in cluster, e.g. in this case two nodes.
[ntkadmin@appserver-1/mydomain]$ ntk cfg setc cluster.bootstrap_expect 2
[ntkadmin@appserver-1/mydomain]$ ntk as restart

Further steps

To get the service fully up and running here is the list of steps required:

  • VRRP configuration, if built in VRRP is used - please consult Virtual Router Redundancy Protocol (VRRP) section.
  • Dashboard configuration - upload license, configure required services, onboarding requirements and user sources.
  • Notakey Authentication Proxy configuration - please consult Authentication Proxy section.

Command Reference

Configuration Management

Commands in section ntk cfg provide unified interface for configuration management.

ntk cfg getc

Usage:

ntk cfg getc [<cfg_key>]

Description:

Retieve a configuration key. Configuration keys can be hierarchical, meaning that keys can contain subkeys. Enter parent key to get overview on child configuration keys and values.

ntk cfg setc

Usage:

ntk cfg setc <cfg_key> <value>

ntk cfg setc <cfg_key> <file> --load-file

ntk cfg setc <cfg_key> <value_struct> --json-input

Description:

Set configuration key to specified value. Configuration keys can be hierarchical, meaning that keys can contain subkeys. Option –json-input can be used to populate child keys, parent value will be taken form specified . Value for single key can also be loaded from file using –load-file. Usage of –load-file is exclusive and cannot be mixed with –json-input option. Configuration can be stored both locally and in cluster, shared between nodes. The shared configuration is always prefixed with : (semicolon). Use two semicolons (::) to retrieve configuration values from cluster and, if value is not present, fall back to locally stored value.

Partial vs Full Configuration Keys

You can retrieve values using their full key (e.g. node.name) or you can retrieve parts of the configuration key by specifying a partial key (e.g. just node for all the values underneath it).

# Example illustrating that configuration values can be retrieved
# using both full and partial keys.

# Full key
$ ntk cfg getc node.name
NotakeyNode1

# Full key
$ ntk cfg getc node.datacenter
DefaultDC

# Partial key will retrieve all keys underneath it
$ ntk cfg getc node
{
  "name": "NotakeyNode1",
  "datacenter": "DefaultDC"
}

# Store key in cluster configuration
$ ntk cfg setc :sso.host sso.example.com
sso.example.com

# Get key from cluster configuration
$ ntk cfg getc :sso.host
sso.example.com

# Store key locally and retrieve with fallback to local value
# If there is a cluster stored value, it will override local value
$ ntk cfg delc :sso.host
$ ntk cfg setc sso.host mysso.example.com
sso.example.com
$ ntk cfg getc ::sso.host
mysso.example.com

Setting Nested Values (--json-input)

An important parameter to know is --json-input, which is sometimes necessary for setting values. It directs the configuration engine to interpret the configuration value as JSON values. This allows setting multiple nested values at once.

By default, values will be interpreted as a string or a number. This is usually fine. However, when using a partial configuration key, it may override values nested below. For example:

# Example of how node.name and node.datacenter
# values can be overridden by accident.

$ ntk cfg setc node { "name": "NodeName", "datacenter": "NodeDC" }
{ name: NodeName, datacenter: NodeDC }

# Without --json-input, the value was
# interpreted as one long string
$ ntk cfg getc node
{ name: NodeName, datacenter: NodeDC }

# The nested value node.name does not exist
# anymore
$ ntk cfg getc node.name


Alternatively, if we use --json-input, then the values are set hierarchically:

# Note the use of single quotes around
# the value
$ ntk cfg setc node '{ "name": "NodeName", "datacenter": "NodeDC" }' --json-input
{
  "name": "NodeName",
  "datacenter": "NodeDC"
}

# Multi-line output hints that the value
# is not a simple string anymore
$ ntk cfg getc node
{
  "name": "NodeName",
  "datacenter": "NodeDC"
}

$ ntk cfg getc node.name
NodeName

Loading Values From a File (--load-file)

You can load values from a file by passing the --load-file argument to ntk cfg setc.... The value argument will be interpreted as a path to file, and the contents of this file will be used as the real configuration value.

ntk cfg setc <key> <path_to_file> --load-file

$ echo "Hello World" > /tmp/value_file
$ ntk cfg setc test_value /tmp/value_file --load-file
Hello World
$ ntk cfg getc test_value
Hello World

The parameter is useful when setting these configuration keys, which are cumbersome to set directly:

Key Description
ssl.pem HTTPS certificate in PEM format
ssl.key Certificate key in PEM format

ntk cfg migrate

Usage:

ntk cfg migrate <cfg_key_src> <cfg_key_dst>

Description:

Retrieve configuration key and store into destination key. Use :keyname for global cluster backed configuration keys and keyname without any prefix for local persistent configuration. If source key is empty, destination value will be effectively deleted.

Cron job processing

Commands in ntk cron enable or disable running of maintenance jobs in subscribed services. This must be enabled on at least one of nodes in cluster and can be safely enabled on all nodes. Services like NAS, SSO subscribe to incoming events in cron and run their maintenance jobs as needed in daily / hourly / weekly and mothly schedule.

ntk cron enable

Usage:

ntk cron enable

Description:

Enables cron task processing globally on node. Full node restart required.

ntk cron disable

Usage:

ntk cron disable

Description:

Disables global cron task processing on node.

ntk cron run

Usage:

ntk cron run

Description:

Allows you to debug tasks processing. Output will show tasks that will be run and their output.

Reverse proxy

Commands in ntk rp section manage Reverse Proxy configuration and status. Reverse Proxy handles all incoming HTTP(S) requests and routes them to corresponding providers.

Configuration settings

The following configuration settings must be present to start this service.

Key Description
host DNS name by which the Authentication Server will be accessible (e.g. ntk.example.com). If ssl.acme.status is on, then this should be a publicly accessible address.
ssl.acme.status On/off flag. When on - TLS certificates will be created and auto-renewed, using Let’s Encrypt. When off, TLS certificates must be set via the ssl.pem and ssl.key configuration values.
ssl.acme.email When using Let’s Encrypt TLS certificates, this will be sent as the contact address.
ssl.pem TLS certificate (in PEM format). This is used only when ssl.acme.status is not on. You can set this value directly. It should begin with -----BEGIN CERTIFICATE----- and have newlines escaped as \n.
ssl.key TLS certificate key (in PEM format). This is used only when ssl.acme.status is not on. You can set this value directly. It should begin with -----BEGIN PRIVATE KEY----- and have newlines escaped as \n.
ssl.acme.mgmt_enable Enable management interface SSL certificate acquired from ACME. If ACME is used and this is not enabled, management will use self signed certificate.

Change settings using ntk cfg setc command.

ntk rp restart

Usage:

ntk rp restart

Description:

Stops and start Reverse Proxy. Use this command to apply configuration changes.

ntk rp start

Usage:

ntk rp start [--force]

Description:

Starts Reverse Proxy. Use –force option to skip SSL certificate validation matching configured DNS hostname e.g. useful during initial setup.

ntk rp stop

Usage:

ntk rp stop

Description:

Stops Reverse Proxy. Service will be stopped and will not be started until ntk as start is called. The stopped state persists across appliance restarts.

ntk rp status

Usage:

ntk rp status [--short]

Description:

Shows status of all Reverse Proxy components. Use –short to display only status (useful for scripting).

ntk rp validate

Usage:

ntk rp validate

Description:

Validates Reverse Proxy configuration, checks SSL certificate validity, cluster and networking configuration.

Authentication Server

Commands in ntk as section govern Notakey Authentication Server state and configuration.

Configuration settings

The following configuration settings must be present to start this service.

Key Description
mgmt_port Set port number, used for management, see below for details.
messenger_url Set URL used for push notification and SMS sending.
nas.healthcheck Set to "off” to disable internal service consistency check. Use only if experiencing issues with service becoming unhealthy due unhandled spikes in load.

Change settings using ntk cfg setc command.

Running management dashboard on non-default port

It is possible to configure management dashboard on port other than default 443, that is used for device API. To set this to different port run e.g. ntk cfg setc mgmt_port 8443, so that management data is separated from payload data.

ntk as restart

Usage:

ntk as restart

Description:

Stops and start Notakey Authentication Server. Use this command to apply configuration changes.

ntk as start

Usage:

ntk as start [--force]

Description:

Starts Notakey Authentication Server. Use –force option to skip SSL certificate validation matching configured DNS hostname e.g. useful during initial setup.

ntk as stop

Usage:

ntk as stop

Description:

Stops Notakey Authentication Server. Service will be stopped and will not be started until ntk as start is called. The stopped state persists across appliance restarts.

ntk as status [–short]

Usage:

ntk as status

Description:

Shows status of all Notakey Authentication Server components.

ntk as validate

Usage:

ntk as validate

Description:

Validates Notakey Authentication Server configuration, checks SSL certificate validity, cluster and networking configuration.

Single Sign-On Server

Commands in ntk sso section govern Notakey Single Sign-On Server state and configuration.

Configuration settings

The following configuration settings must be present to start this service.

Key Description
sso.host DNS name by which will be used by users to access SSO service (e.g. sso.example.com). If ssl.acme.status is on, then this should be a publicly accessible address.
sso.base.“admin.protectindexpage” Do not allow direct access to admin startpage without authentication, true / false value.
sso.base.“admin.protectmetadata” Do not allow direct anonymous access to metadata used by service providers, true / false value.
sso.base.“auth.adminpassword” Sets local admin password, allows acess to metadata and diagnostics.
sso.base.errorreporting Enables user error reporting form when problems occur, true / false value.
sso.base.technicalcontact_name Contact name for error reporting form.
sso.base.technicalcontact_email Email where to send error reports from error reporting form.
sso.base.debug Enable debugging of authenticatio processes.
sso.base.“logging.level” Sets log level, integer value from 0 to 7, 7 being most verbose, used with debug.
sso.base.theme.use Sets custom theme, string value in format “module:theme”.
sso.base.“session.duration” Maximum duration of authenticated session in seconds, default 8 hours.
sso.base.“language.default” Sets default ISO 639-1 language code for UI language.
sso.base.“authproc.idp” Objects containing applied filters during authentication process, see below for details.
sso.auth Contains objects that describe access to user repositories. At least one user repository must be configured. Please see below for details.
sso.“saml-sp” Objects describing all service provider (SP) metadata - these are web applications that consume the identity assertions. Please see below for details.
sso.“saml-idp” Objects describing names for this IdP. Only one IdP must be defined. Please see below for details.
sso.certificates Objects describing all certificates used by SSO e.g. used for SAML assertion signing. Please see below for details.
sso.modules List of enabled modules. Only required modules should be enabled as this affects performance. Please see below for details.
ssl.sso.pem TLS certificate (in PEM format). This is used only when ssl.acme.status is not on. You can set this value directly. It should begin with -----BEGIN CERTIFICATE----- and have newlines escaped as \n.
ssl.sso.key TLS certificate key (in PEM format). This is used only when ssl.acme.status is not on. You can set this value directly. It should begin with -----BEGIN PRIVATE KEY----- and have newlines escaped as \n.

Change settings using ntk cfg setc command.

Basic service configuration

Basic settings

$ ntk cfg setc sso.host sso.example.com
sso.example.com
$ ntk cfg setc sso.base.technicalcontact_name "Example.com support"
Example.com support
$ ntk cfg setc sso.base.technicalcontact_email support@example.com
support@example.com
$ ntk cfg setc 'sso.base."auth.adminpassword"' "myadminpass"
myadminpass

Configuring user repository access

NAS user repository

$ ntk cfg setc sso.auth.ntkauth '{ "module": "notakey:Process",
        "endpoints": [
          {
            "name": "SSO service",
            "url": "https://demo.notakey.com/",
            "service_id": "bcd05d09-40cb-4965-8d94-da1825b57f00",
            "service_logo": "https://demo.notakey.com/_cimg/b5d3d0f7-e430-4a30-bd34-cea6bab9c904?size=300x150"
          }
          ]}' --json-input

Description:

Configure a user repository from Notakey Authentication Server. Name can be any string and will be shown on authentication request. Service ID is the value issued after service creation and shown in NAA admin dashboard.

LDAP based user repository

$ ntk cfg setc sso.auth.myauth '{ "module": "ldap:LDAP",
        "hostname": "ldaps://192.168.1.2",
        "enable_tls": true,
        "attributes": [
          "sAMAccountName",
          "cn",
          "sn",
          "mail",
          "givenName",
          "telephoneNumber",
          "objectGUID"
        ],
        "timeout": 10,
        "referrals": false,
        "dnpattern": "sAMAccountName=%username%,OU=MyOU,DC=example,DC=com"}' --json-input

Description:

Configure a user repository from LDAP, in this example from Microsoft Active Directory. Username matching is done by sAMAccountName attribute, but this could be configured as any other unique attribute. “search.attributes” defines which attributes are used for user ID matching.

SSO Certificate Configuration

To configure static SSL certificates for SSO HTTPS follow these steps: - Use scp or similar utility to transfer certificate and key files to appliance. - Use ntk cfg setc ssl.sso.pem and ntk cfg setc ssl.sso.key to load data from files into appliance configuration as shown below: shell ntk cfg setc ssl.sso.pem /home/ntkadmin/ssossl.pem --load-file ... certificate output follows ... ntk cfg setc ssl.sso.key /home/ntkadmin/ssossl.key --load-file ... key output follows ... - Ensure that ACME certificates are disabled (ntk cfg getc ssl.acme.status returns “off”).

Configuring Identity Provider

Typical ID provider configuration

$ ntk cfg setc sso.\"saml-idp\".\"sso.example.com\" '{
  "host": "__DEFAULT__",
  "privatekey": "server.key",
  "certificate": "server.pem",
  "auth": "myauth"
  }' --json-input

Description:

Configures an IdP with defined certificate and selected user repository. If multi-tenant mode is used, multiple IdPs can be configured and selection will be done by HTTP host header matching to “host” configuration parameter. Fallback value is DEFAULT as in configuration above. The key and certificate has to be set with command ntk cfg setc sso.certificates.server.key and ntk cfg setc sso.certificates.server.pem respectively. Name for certificate can be any valid filename.

Configuring service providers

Generic Google Gapps configuration

$ ntk cfg setc sso.\"saml-sp\".\"google.com\" '{
"AssertionConsumerService": "https://www.google.com/a/example.com/acs",
"NameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
"simplesaml.attributes": false,
"startpage.logo": "gapps.png",
"startpage.link": "http://mail.google.com/a/example.com",
"name": "Google Gapps"
  }' --json-input

Description:

Google Gapps for business customers can be configured to authenticate to remote SAML IdP. Here is the server side configuration for this setup. Use ntk cfg delc sso.\"saml-sp\".\"google.com\" to delete configured SP.

Amazon AWS console configuration

$ ntk cfg setc sso.\"saml-sp\".\"urn:amazon:webservices\" '{
  "entityid": "urn:amazon:webservices",
  "OrganizationName":   { "en": "Amazon Web Services, Inc." },
  "name":  { "en": "AWS Management Console" },
  "startpage.logo": "aws-logo.png",
  "startpage.link": "https://sso.example.com/sso/saml2/idp/SSOService.php?spentityid=urn:amazon:webservices",
  "OrganizationDisplayName":  { "en": "AWS" },
  "url":  { "en": "https://aws.amazon.com" },
  "OrganizationURL":  { "en": "https://aws.amazon.com" },
  "metadata-set": "saml20-sp-remote",
  "AssertionConsumerService":  [ {
      "Binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
      "Location": "https://signin.aws.amazon.com/saml",
      "index": 1,
      "isDefault": true
    } ],
  "SingleLogoutService":  "",
  "NameIDFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
  "attributes.required":   [ "https://aws.amazon.com/SAML/Attributes/Role", "https://aws.amazon.com/SAML/Attributes/RoleSessionName" ],
  "keys":  [  {
      "encryption": false,
      "signing": true,
      "type": "X509Certificate",
      "X509Certificate": "MIIDbTCCAlWgAwIBAgIEKJJQLzANBgkqhkiG9w0BAQsFADBnMR8wHQYDVQQDExZ1\ncm46YW1hem9uOndlYnNlcnZpY2VzMSIwIAYDVQQKExlBbWF6b24gV2ViIFNlcnZp\nY2VzLCBJbmMuMRMwEQYDVQQIEwpXYXNoaW5ndG9uMQswCQYDVQQGEwJVUzAeFw0x\nNzA2MDYwMDAwMDBaFw0xODA2MDYwMDAwMDBaMGcxHzAdBgNVBAMTFnVybjphbWF6\nb246d2Vic2VydmljZXMxIjAgBgNVBAoTGUFtYXpvbiBXZWIgU2VydmljZXMsIElu\nYy4xEzARBgNVBAgTCldhc2hpbmd0b24xCzAJBgNVBAYTAlVTMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnmVupB5TWNR4Jfr8xU0aTXkGZrIptctNUuUU\nfA5wt7lEAgoH7JeIsw7I3/QYwfA0BkGcUxLiW4sj7vqtdXwLK5yHHOg3NYsN2wCU\noSnsw/msH7nyeyUXXRr9f+dyJRRViBnlaJ3RHNk6UZEbS/DJG/W4OMlthdzIXJbA\n0G0xQid96lUZOgeLuz1olWiAIbJRPqeBRcVlY8MvHzVE82ufvSgkGnMZAt6B4Q6T\n9PsIDdhRDbTBTtUAmaKF3NXl/IPq5eybM6Pw3gcVlsrtgq0LHsdhgRdMz6UeBaA9\nTn/dgmeWM+UKEXkHbtnsq6q9X+8Nq/HwGylI/p3cPZ8WuOjXeQIDAQABoyEwHzAd\nBgNVHQ4EFgQU7F4XurLqS7Bsxj8NKcA9BvHkEE0wDQYJKoZIhvcNAQELBQADggEB\nAJItHBnpD62VaOTSPqIzVabkpXWkmnclnkENAdndjvMcLJ3qrzqKb3xMQiEGCVzF\ni9ZXU3ucMAwufIoBaSjcuFNYT1Wuqn+Jed2xH5rUOAjeDndB7IjziU5kyW+6Zw9C\nFmSN8t0FFW2f3IALgWfrrJ6VWPzen9SJrNPmVralau66pDaZbGgpBkVi2rSfJiyM\nleau9hDNBhV+oPuvwDlbceXOdmJKUTkjyID9r+CmtHq7NL6omIH6xQw8DNFfa2vY\n17w2WzOcd50R6UUfF3PwGgEyjdiigWYOdaSpe0SWFkFLjtcEGUfFzeh03sLwOyLw\nWcxennNbKTXbm1Qu2zVgsks="
    } ],
  "saml20.sign.assertion": true,
  "authproc": {
    "91": {
      "class": "core:AttributeAdd",
      "https://aws.amazon.com/SAML/Attributes/Role": [ "arn:aws:iam::540274555001:role/SamlRoleAdmin,arn:aws:iam::540274555001:saml-provider/NTKSSO" ]
    },
    "92": {
      "class": "core:PHP",
      "code": "$attributes[\"https://aws.amazon.com/SAML/Attributes/RoleSessionName\"][0] = $attributes[\"uid\"][0];"
    }
  }
}' --json-input

Description:

Example above shows a more complex scenario where SP requires specific attributes present in assertion. The role SamlRoleAdmin therefore has to be created in AWS IAM module configuration. RoleSessionName in this case is simply copied from user ID value, a more elaborate setup would be required in production environment.

Configuring filters

Setup additional 2FA

$ ntk cfg setc sso.base.\"authproc.idp\" '{
      "90": {
        "class": "notakey:Filter",
        "user_id.attr": "sAMAccountName",
        "endpoints": [
          {
            "name": "Mobile ID validation",
            "url": "https://demo.notakey.com/",
            "service_id": "bcd05d09-40cb-4965-8d94-da1825b57f00",
            "service_logo": "https://demo.notakey.com/_cimg/b5d3d0f7-e430-4a30-bd34-cea6bab9c904?size=300x150"
          }
        ]
      }
    }' --json-input

Description:

Once you have configured a user repository as authentication backend in Identity Provider configuration, it is possible to add additional checks to authentication flow. Example above shows adding a NAA based backend for ID validation. Key “user_id.attr” is used to discover matching user in NAA, in this case sAMAccountName from Active Directory. It is possible to use additional modules and filters for languange provisioning with service providers, attribute mapping and alteration, etc.

Managing certificates

Adding a certificate

$ ntk cfg setc sso.certificates.server '{
    "description": "Demo certificate",
    "pem": "-----BEGIN CERTIFICATE-----\nMIIDdDCCAlwCCQC30UW2PPlkQjANBgkqhkiG9w0BAQsFADB8MQswCQYDVQQGEwJM\nVjETMBEGA1UECBMKU29tZS1TdGF0ZTENMAsGA1UEBxMEUmlnYTEQMA4GA1UEChMH\nTm90YWtleTEWMBQGA1UEAxMNbm90YWtleS5sb2NhbDEfMB0GCSqGSIb3DQEJARYQ\naW5mb0Bub3Rha2V5LmNvbTAeFw0xNzAzMjExMjM4MzZaFw0yNzAzMTkxMjM4MzZa\nMHwxCzAJBgNVBAYTAkxWMRMwEQYDVQQIEwpTb21lLVN0YXRlMQ0wCwYDVQQHEwRS\naWdhMRAwDgYDVQQKEwdOb3Rha2V5MRYwFAYDVQQDEw1ub3Rha2V5LmxvY2FsMR8w\nHQYJKoZIhvcNAQkBFhBpbmZvQG5vdGFrZXkuY29tMIIBIjANBgkqhkiG9w0BAQEF\nAAOCAQ8AMIIBCgKCAQEA5L/rjXT0dEBmN3BSnsmLCwF9goOZWb5RNvvc+dnUQnaG\n5nJ8xMPSpEAm4y2ZlC8Uhm56H+7A2cUf/ogkUcKkyQHyXQrjjPzec5h3+734Mmit\nvHAAzC/j9smDOvdde9evMUDH9Sn7oJtpz+MKckTFvsBoLGuBPiuLn8P9HCmLKlMN\njR2hfJab+DZG+eysAGkoiGS9zOxMVF9Xsvk/EHxm5p3ZPF2oOEr8cimgQO/ew29+\nfF4etwskre/AA8KCw/6Bg2XwZ3HmFPJ9nd/zJSzqm5U96WFEth4ABVqZE4MS4rRo\n2K+eQy2rXzDnmiL3cGiLuL9aal+9JCFRxKE1RSIdEQIDAQABMA0GCSqGSIb3DQEB\nCwUAA4IBAQC7T9Yqu0+ONT/MP8ZNmbUs5B6+/S0yIreLC1pMmJymxMDIFQCnxeRf\naxDtDfEJVzkiMAl2Q3q/HApCDh/l+hpbn4oKoDXTQvWiZpOWhSR/QcOfpuPGnk09\nmhcZIbI5WSYfsPQbXpu02mnmanXgl7Pt4teQGdQBTq0cO4xj7FOdEIcxD8WAmF9E\ntS+DhrNoOaaR2mwicHZ5+cfMKviNWw3qmolDWZKm8tIZTU21+lU+LyB6uMwCgQ/y\nCZG4eY0O+CKlzn6nlsOLgpKhZDtiNgPN3eGcIHfw+oxCECH6de/Ewuk3Co6Thnh1\nRu6Lt+g/od2IYvKl0R6efBTeuwozoubJ\n-----END CERTIFICATE-----\n",
    "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA5L/rjXT0dEBmN3BSnsmLCwF9goOZWb5RNvvc+dnUQnaG5nJ8\nxMPSpEAm4y2ZlC8Uhm56H+7A2cUf/ogkUcKkyQHyXQrjjPzec5h3+734MmitvHAA\nzC/j9smDOvdde9evMUDH9Sn7oJtpz+MKckTFvsBoLGuBPiuLn8P9HCmLKlMNjR2h\nfJab+DZG+eysAGkoiGS9zOxMVF9Xsvk/EHxm5p3ZPF2oOEr8cimgQO/ew29+fF4e\ntwskre/AA8KCw/6Bg2XwZ3HmFPJ9nd/zJSzqm5U96WFEth4ABVqZE4MS4rRo2K+e\nQy2rXzDnmiL3cGiLuL9aal+9JCFRxKE1RSIdEQIDAQABAoIBAHmnb/itKIzi6vm0\n7NuxyBa0VjGhF19ZDgw16pGePXqTWq8YWC61DkN4MrZDPBhI6ZuNCboN2dZ3NcrC\nUL6Cy+xy8ph1AAutOAk2HyltIKB+d1duIZ52IcDP7tDfWYJRdMS29SD3kPEbdiyv\nTJD07k3COiTVj8imk/0F2Iivt2lr/GLyPSKFckNzCC3Tfz7pCaq2+JBxt08QtZPl\nqL81or7+BpcUNgmZyA1WLZsMpoYeXX6fsndUrVcfZIayaIXjX9NJYxQuwW44EYxq\nhBRS+goxXo+xQSKCSEuPf36pc82sxUiNEszAOd5Iqjrl1pRVVoLFdVLXFaQ0f0J8\nq7PXjYECgYEA/mhXuoTQuVsJvqCfZSLs/bZnJotSi9na4oOmZBp+LokRzHYbmchm\nSjX1scc9fm5MMOe82WAUMBYZhBVJrjqk/rQvGBMpRqut6JiujpSDR27xAcpJD79P\ngBre3PSDJ84koI8PTyGTcPTa3RqY5+5Iv4JsFPFCshFGMI/ldwRxickCgYEA5i52\nuSyMohMrAfHyS3IG1c/bGrhSZ7O790nUakEGpwi8paD/qi4klb5LYmJLQbaZOKes\nh6voXQ3Zhvd0j6sXzi2d802OlB9LIq+FcctiiS3wR1YykbAq3RDAfYMEEnSdRnp3\noz8i3l1y/a1bP3RnjSmeaMVG/nITFlfMbfCEnQkCgYBemQvt9g7qrVhdQrqiT69R\n0+5dHbcu+23xhkRrupIq2Zr9rPksYKDwfUoDtfM+vOKl2LWXGqvHCaCpRYUlPPc3\nImbUi+NwPMwozgUyTTTXbgA9yysJqPh1yQgPnvfZ6EQkU628nd6GRPXQ+1/Z9fel\nBmkMDH3hWpz/17HaZJOXSQKBgETamUEDBn5k5XSLf0L6NPk4V/5CLMRAi3WJbDTs\nhqTohCW3Z0Ls0pzIc5xWctSRXnwIDB/5WGSdg/hPhVqEf3Z5RspE5OWCBuO1RWGo\nySznxPxR2Iaj/+5o2GuzCUDMCU/PyoHWnQOPSJqBhM4Sb/dV/8CvYnEyhmskkE5C\nqCihAoGBAJr0fISYmFtX36HurmFl+uCAcOPXy6qEX3Im6BA6GiNGmByk+qFVP5e9\nLRjX7LouGlWyPridkODdWAwCTxn1T7FcGFRZlK0Ns3l8Bp+FMznXX05TlkNZpC6X\nV9F0GVQtrwsos605Z8OG4iMRkn+3Qk6FZ8QnlBX807killRcGlC4\n-----END RSA PRIVATE KEY-----\n"
 }' --json-input

Description:

Adds a certificate to be used in SSO configuration. Certificate data have to be line delimited with \n character and may contain —–BEGIN and —–END comments. Refer to certificate later in configuration with <name>.key for key and <name>.pem for certificate. After every change in certificate store SSO service must be restarted. To delete a certificate use ntk cfg delc sso.certificates.server.

Enabling modules

Typical module configuration

$ ntk cfg setc sso.modules '[ "cron", "startpage", "ldap", "notakey" ]' --json-input

Description:

Configure a list of enabled modules. User repositories and authentication filters define which modules are required. For basic setup with LDAP (or Active Directory) the list above is sufficient. Follow each change with ntk sso restart.

Adding service provider logos

Use scp to copy logo files to /home/ntkadmin/userlogos directory. Files can be in any format, PNG with transparent background preferred, use 250x80px for optimal scaling.

$ scp mylogo.png ntkadmin@ntk.example.com:/home/ntkadmin/userlogos/

You can use URL https://sso.example.com/userlogos/mylogo.png later as startpage logo for required SP.

Authentication Proxy

Commands in ntk ap section control Notakey Authentication Proxy.

Configuration settings

The following configuration settings must be present to start this service.

Key Description Default Possible values
notakey.proxy.vpn_port_in Incoming RADIUS service port that the Notakey Authentication Proxy listens for inbound requests from VPN access gateways. 1812 1-65000
notakey.proxy.vpn_port_out RADIUS server port where Notakey Authentication Proxy will send upstream requests. 1812 1-65000
notakey.proxy.vpn_radius_address RADIUS server hostname or IP address that Notakey Authentication Proxy forwards the requests. (none) string
notakey.proxy.vpn_secret_in CHAP secret for incoming requests from VPN access gateways. (none) string, max 16 characters
notakey.proxy.vpn_secret_out CHAP secret for outgoing requests to the RADIUS server. (none) string, max 16 characters
notakey.proxy.vpn_access_id Application Access ID as seen on Dashboard Application settings page. (none) string
notakey.proxy.vpn_message_ttl Authentication message time to live time in seconds. Should match the RADIUS timeout value of VPN gateway. 300 integer
notakey.proxy.message_title Authentication message title. Title is shown in application inbox for each authentication message, e.g. “VPN login to example.com” “VPN authentication” string
notakey.proxy.message_description Authentication message contents. Message is shown in push notification and inbox. Use {0} as a placeholder for username. “Allow user {0} VPN login?” string
notakey.proxy.proxy_receive_timeout RADIUS message internal receive timeout. 5 integer
notakey.proxy.proxy_send_timeout RADIUS message internal send timeout. 5 integer
notakey.proxy.api_provider Backend API provider. Do not configure if using local instance. URL needs to be in format https://host/api string
notakey.proxy.api_timeout Backend API call request timeout. 5 integer
notakey.proxy.cisco_acl_passthrough Cisco ownloadable ACL support, when using Cisco ACS as RADIUS server false true,false

Change settings using ntk cfg setc command.

ntk ap start

Usage:

ntk ap start

Description:

Starts Notakey Authentication Proxy.

ntk ap stop

Usage:

ntk ap stop

Description:

Stops Notakey Authentication Proxy. Service will be stopped and will not be started until ntk ap start is called. The stopped state persists across appliance restarts.

ntk ap status

Usage:

ntk ap status

Description:

Shows status of Notakey Authentication Proxy container instance.

ntk ap validate

Usage:

ntk ap validate

Description:

Validates Notakey Authentication Proxy configuration, checks port, RADIUS server and CHAP secret configuration, validates service Access ID.

Command Line Utility

COmmands in section ntk cli simplify management tool updates and automate install of new versions.

ntk cli check

Usage:

ntk cli check

Description:

Checks if new version of configuration utility is available.

ntk cli tag

Usage:

ntk cli tag

ntk cli tag <new tag>

Description:

Set tag of configuration utility. Tag configuration represents an update channel. Use this option to control the update flow and load new functionality. Updates in single tag include fixes for current functionality, but do not contain new functionality. Please consult your support representative for compatibility of your appliance with non-standard tag versions.

ntk cli update

Usage:

ntk cli update

Description:

Load the latest release of configuration utility respecting the tag (update channel).

Networking Configuration

To configure network settings, you must use the ntk net command.

The general syntax is net ntk <interface> <command>, where interface is e.g. eth0.

ntk net hostname

Usage:

ntk net hostname

ntk net hostname <new hostname>

Description:

Displays or sets the Notakey Authentication Appliance hostname. The hostname will be also used to identify node in cluster environment. Hostname cannot contain dots or any special symbols.

ntk net domain

Usage:

ntk net domain

ntk net domain <new domain>

Description:

Displays or sets the Notakey Authentication Appliance domain. The domain will be used to group nodes in cluster environment. Nodes in single L2 network should share domain value. Domain value cannot contain dots or any special symbols.

ntk net address

Usage:

ntk net eth0 address

ntk net eth0 address <ip address/cidr mask>

Description:

Type ntk net <interface> address to see the appliance’s IP addresses.

Type ntk net <interface> address <ip_in_cidr> to set the IP address for the specified network interface.

The IP address must be in CIDR notation - e.g. 10.0.1.5/24.

Please use IP subnet calculator to convert netmask to subnet mask bits. Changes are applied immediately, so in case of SSH connection ensure that

ntk net dhcp

Usage:

ntk net eth0 dhcp

ntk net eth0 dhcp on

ntk net eth0 dhcp off

Description:

Type ntk net <interface> dhcp to see if the specified interface is using DHCP.

To turn DHCP on or off, type ntk net <interface> dhcp [on|off], e.g. ntk net eth0 dhcp off to disable DHCP.

ntk net gateway

Usage:

ntk net eth0 gateway

ntk net eth0 gateway <gateway ip>

Description:

Type ntk net <interface> gateway to see the interface’s gateway.

Type ntk net <interface> gateway <ip> to set the interface’s gateway. E.g. ntk net eth0 gateway 10.0.1.1.

ntk net dns

Usage:

ntk net dns

ntk net dns <server1,server2>

Description:

Display or configure one or more DNS servers. Separate multiple IP addresses by (,) comma. Changes are applied immediately.

ntk net proxy

Usage:

ntk net proxy

ntk net proxy on

ntk net proxy off

Description:

Enable or disable proxy server for outbound connections. Server can be configured with ntk net proxy_host command. Change is applied after full appliance restart.

ntk net proxy_host

Usage:

ntk net proxy_host

ntk net proxy_host <http[s]://proxy-host:port>

Description:

Display or set the proxy server used for outbound HTTP/HTTPS connections. Use https:// prefix if TLS is used on proxy server.

Backup and Restore

Command in backup section provide interface for saving and restoring appliance configuration to and from file.

ntk backup save

Usage:

ntk backup save <path to file>

Description:

Save database and configuration backup to file. Files are usually located in user’s home directory e.g. /home/ntkadmin for persistent storage or in /tmp for temporary location. Utility scp can be used to transfer files between nodes or to backup location.

ntk backup load

Usage:

ntk backup load <path to file>

ntk backup load --skip-net <path to file>

Description:

Restore configuration from backup. Use –skip-net to avoid locally set network configuration overwrite. Appliance must be fully restarted for changes to be applied and all services manually started after restart.

VRRP configuration

The appliance has built-in support for the Virtual Router Redundancy Protocol (VRRP) protocol. VRRP provides functionality to share single IP address between multiple nodes in cluster and It can be managed with the ntk vrrp command line utility.

Available subcommands are:

Command Description
address Get/set the virtual IP address
interface Get/set the network interface
peers Get/set the list of physical unicast peers
status See VRRP status
vrid Get the virtual router ID
start Enable the VRRP service
stop Stop the VRRP service

ntk vrrp address

Usage:

ntk vrrp address

ntk vrrp address <server ip>

Description:

Type ntk vrrp address to see the configured virtual IP address.

Type ntk vrrp address <address> to set the configured virtual IP address. It must be in decimal notation - aaa.bbb.ccc.ddd.

ntk vrrp interface

Usage:

ntk vrrp interface

ntk vrrp interface eth0

Description:

Type ntk vrrp interface to see the configured network interface.

Type ntk vrrp interface <iface> to set the network interface. It must match one of the detected network interfaces on the appliance (e.g. eth0).

ntk vrrp peers

Usage:

ntk vrrp peers

ntk vrrp peers clear

ntk vrrp peers set 10.0.1.5,10.0.1.6

Description:

Type ntk vrrp peers to see the list of unicast peers.

Type ntk vrrp peers clear remove all peers from the list.

Type ntk vrrp peers set <peer_list> to set a comma-separated peer list. E.g. 10.0.1.5, 10.0.1.6.

By default multicast is used for communication between nodes. If no multicast is available on transport layer please configure all cluster members using this command.

ntk vrrp status

Usage:

ntk vrrp status

Description:

Type ntk vrrp status to see if the VRRP status is enabled. The command will output enabled or disabled.

To see a more comprehensive overview, enter ntk vrrp status --verbose.

ntk vrrp vrid

Usage:

ntk vrrp vrid

ntk vrrp vrid 51

Description:

Type ntk vrrp vrid to get the virtual router ID.

Type ntk vrrp vrid <vrrp ID> to set the virtual router ID.

All members is cluster must share the same vrid. Take care to avoid using this value on other services as this might cause interference.

Default value for virtual router ID is 51.

ntk vrrp start

Usage:

ntk vrrp start

Description:

Type ntk vrrp start to start the VRRP service.

ntk vrrp stop

Usage:

ntk vrrp stop

Description:

Type ntk vrrp stop to stop the VRRP service.

ntk vrrp restart

Usage:

ntk vrrp restart

Description:

Type ntk vrrp restart to restart the VRRP service.

ntk vrrp preempt

Usage:

ntk vrrp preempt

ntk vrrp preempt on

ntk vrrp preempt off

Description:

Type ntk vrrp preempt to see if the preempt mode is enabled.

Type ntk vrrp preempt on enable preempt mode.

Type ntk vrrp preempt off disable preempt mode.

Preempt mode allows to guarantee that service will be served by the server with the highest priority when cluster is fully functional. Preempt mode is disabled by default and the service will remain with the last working node, even if new nodes appear online with higher priority.

ntk vrrp prio

Usage:

ntk vrrp prio

ntk vrrp prio 100

Description:

Type ntk vrrp prio to get the node priority.

Type ntk vrrp prio <prio> to set the node priority.

Priority controls the service takeover conditions with respect to preempt setting. If active node fails, service will be taken over by a node with next highest prio value. To guarantee preempt takeover when all nodes ar functional, priority difference has to be at least 50.

Cluster Management

When Notakey Authentication Appliance is deployed in cluster environment, commands in ntk cluster allow individual node state management in cluster and provides cluster health overview.

ntk cluster start

Usage:

ntk cluster start [--if-not-running]

Description:

Starts local cluster member datastore node. Node can work standalone or can be joined to other nodes, if datacenter settings are consistent. Use conditional start --if-not-running to avoid error if datastore is already started.

ntk cluster stop

Usage:

ntk cluster stop

Description:

Stops local cluster member datastore node. If after stop cluster no longer holds quorum, this command can lead to read-only datastore on other nodes, use with care.

ntk cluster restart

Usage:

ntk cluster restart

Description:

Restarts local cluster member datastore node. This command can lead to read-only datastore on other nodes, use with care.

ntk cluster status

Usage:

ntk cluster status

Description:

Shows datastore status.

ntk cluster validate

Usage:

ntk cluster validate

Description:

Validates datastore configuration settings. Checks include node name validity, datacenter and cluster IP configuration.

ntk cluster cleardata

Usage:

ntk cluster cleardata

Description:

This command is intended for use, where cluster leader/follower data stores can not be reconciled. Clear the data on followers, and allow cluster leader to replicate to them.

Overview of cluster rebuild steps :

  • Issue ntk cluster leave on nodes out of sync.

  • Use ntk cluster cleardata to purge all local data.

  • Use ntk cluster reset to purge data about remote nodes.

  • Restart appliance to purge any in-memory saved state.

  • Issue ntk cluster join ... to join to root node.

  • Verify that cluster is in sync with ntk cluster nodes

ntk cluster join

Usage:

ntk cluster join <ip address of root node>

Description:

Joins existing cluster node and starts data replication. ACME certificates will also be replicated during join.

ntk cluster health

Usage:

ntk cluster health

Description:

Displays health information about the cluster nodes and datastore replication status. A warning information will be shown if cluster is in degraded state. RAFT and internal protocol information is required during upgrades as different versions supporting different sets of versions cannot coexist in the same cluster.

$ ntk cluster health
=> Cluster Datastore status
    RAFT version:     v3
    protocol version: v2
    Leader:           ntknode1

=> Cluster members
Node        IP address  Status  Member ID
ntknode1    172.16.112.136  alive   47804985-5aab-2e37-6c87-b60aa22d3925
ntknode2    172.16.112.137  alive   23423985-34ab-2e37-6123-b60aa22d4524
ntknode3    172.16.112.138  alive   34535985-123b-2e37-1287-b60aa22d3932

ntk cluster myid

Usage:

ntk cluster myid

Description:

Shows persistent ID number of member node. This information is relevant for troubleshooting when reassembling cluster after general failure.

ntk cluster leave

Usage:

ntk cluster leave

Description:

Informs other cluster members about leave intent and removes reference data for cluster. Cluster will remain functional and other nodes will continue to serve requests. This command is not recommended when leave candidate node is in active state serving requests, as data loss is imminent. Please use VRRP configuration to demote node from active state and then issue leave command.

ntk cluster nodes

Usage:

ntk cluster nodes

Description:

Provides overview about known nodes and their state in cluster. Use this command to identify failures in cluster mode.

$ ntk cluster nodes
Node           Status  IP Address  Data Center
as-1           alive   10.1.1.62   master-dc
as-4           alive   10.1.1.61   master-dc
as-3           alive   10.1.1.65   master-dc
as-2           alive   10.1.1.66   master-dc

ntk cluster reset

Usage:

ntk cluster reset <comma_separated_peer_list>

Description:

Use this command for cluster recovery, if quorum has been lost due to failed nodes. Pass a comma-separated peer list, and a new cluster will be initialized, inheriting data from the previous cluster.

Steps to take for recovery:

  1. Run this command on every node specified in the peer list

  2. On every node execute ‘ntk as restart’

Built-in Troubleshooter

Use doctor command to validate your configuration.

ntk doctor

Usage:

ntk doctor

Description:

Run ntk doctor to attempt identify common problems with configuration, and suggest solutions.

Setup Wizard

Issue ntk wizard on every node to configure the initial settings to get applicance connected to network and acquire SSL certificates.

ntk wizard

Usage:

ntk wizard

Description:

Run ntk wizard to setup initial configuration required to start Notakey Authentication Server service in a single node mode. Wizard will require networking, external DNS name and SSL configuration. Configuration can then be later adjusted using specific commands.

System Maintenance

Commands in ntk sys control Notakey Authentication Server state and allows maintenance operations.

ntk sys passwd

Usage:

ntk sys passwd

Description:

Prompts user for new password. Use this command to change password after appliance image deployment.

ntk sys reboot

Usage:

ntk sys reboot

Description:

Requests an immediate appliance restart.

ntk sys shutdown

Usage:

ntk sys shutdown

Description:

Shuts down appliance.

ntk sys vmtools

Usage:

ntk sys vmtools enable

ntk sys vmtools disable

Description:

Enables or disables VMware tools service. Must be enabled only in VMware based deployment e.g. when using VMware ESXi. Tools installation allows external power state control of appliance OS and provides diagnostic and networking information to hypervisor.

ntk sys docker

Usage:

ntk sys docker

ntk sys docker 17.04.0-ce

Description:

$ ntk sys docker
    Refreshing package state...ok
    Current version: 17.05.0
    Available versions:
      1.10.3
      1.11.2
      1.12.6
      1.13.1
      17.03.1-ce
      17.04.0-ce
      17.05.0-ce

$ ntk sys docker 17.05.0-ce
    Refreshing package state...ok
    Downloading install image...ok
    Changing docker version to 17.05.0-ce...ok
    Please reboot appliance with "ntk sys reboot" to apply docker engine switch.

All services on NAA node are deployed as docker container. Sometimes it is neccessary to change docker. Call command without arguments to discover the available docker engine versions. To change version pass new version as the argument. Available versions are loaded from repository URL configured with “ntk sys repo” command. Use this command with care as changes in docker version can affect all user services. A full system restart is required after version switch.

ntk sys ntp

Usage:

ntk sys ntp <server1,server2>

ntk sys ntp

Description:

Configure or verify NTP time servers. NTP service uses unicast UDP/123 for communication, please ensure the required port is open in firewall.

ntk sys arp

Usage:

ntk sys arp

Description:

Check local IPv4 MAC arp table. Useful for network connectivity validation.

ntk sys ping

Usage:

ntk sys ping <host>

Description:

Ping specified host with ICMP packets. Useful for network connectivity validation.

ntk sys traceroute

Usage:

ntk sys traceroute <host>

Description:

Check IP routing path to specified host. Useful for network connectivity validation.

ntk sys perf

Usage:

ntk sys perf

Description:

Check overall system load and memory usage. Shows list of most active processes.

ntk sys repo

Usage:

ntk sys repo https://index.notakey.com/notakey-support/appliance/raw/v<version> --auth <user:pass>

ntk sys repo

Description:

Configure source repository for update status check and new package download. Default value is https://index.notakey.com/notakey-support/appliance/raw/v\<version\> where <version> is the installed appliance version. In most cases, when upgrading within single major version, an upgrade is possible by adjusting this value to required version. Any upgrades should be exercised with care, while cluster host is in idle state.

$ ntk sys repo https://index.notakey.com/notakey-support/appliance/raw/v4.1.0
==> Changing repository to "https://index.notakey.com/notakey-support/appliance/raw/v4.1.0"
    Testing service connectivity...  ok
    Checking index...  ok
    Clearing cache...  ok
    Updating configuration...  ok
Configuration complete, use "ntk sys update" to fetch new package versions.

ntk sys update

Usage:

ntk sys update [--force]

Description:

Retrieve list of latest packages, perform update if new versions are found. Use --force to reinstall all locally downloaded packages.

$ ntk sys update --force
==> The following package versions will be downloaded
    downloading all available packages
    dashboard: dashboard:2.7.1
    auth-proxy: authproxy:1.0.2
    CLI: cfg:4.1.0
    consul: consul:0.8.4
    traefik: traefik:1.3.1
    vrrp: keepalived:1.3.9
    htop: htop:latest
    Do you want to proceed? (y/n): y

==> Downloading from repo.notakey.com
    downloading dashboard:2.7.1
    downloading authproxy:1.0.2
    downloading cfg:4.1.0
    downloading consul:0.8.4
    downloading traefik:1.3.1
    downloading keepalived:1.3.9
    downloading htop:latest

==> Configuration update
    apply new versions after service restart? (y/n): y
    restart all running services? (y/n): y
=> Graceful shutdown of existing instances
...
    update complete

ntk sys cleanup

Usage:

ntk sys cleanup [--all-unused]

Description:

Remove unused packages from local repository. If --all-unused is specified, also images with stopped containers are deleted, otherwise only unused images are removed. Note that this is a disk IO intensive process and should be used on a lightly loaded servers, as service could be impacted.

ntk sys supreq

Usage:

ntk sys supreq

Description:

Create an archive with all logfiles and diagnostic information for support request submission. No user data is contained in exported archive, except authentication history and logs. Archive contains sensitive configuration details, sharing with third parties should be exercised with caution. Expect a significant IO load increase while report is running.

$ ntk sys supreq
=> Gathering system detail... ok
=> Processing config... ok
=> Gathering logs... ok
=> Gathering system service details... ok
=> Gathering application details... ok
=> Packing... ok

Support request archive created in /home/ntkadmin/support_request_20170628135340.tgz

ntk sys timezone

Usage:

ntk sys timezone

ntk sys timezone <timezone>

Description:

Set timezone for containers. Timezone is in zoneinfo format, e.g. UTC, Europe/Riga or America/New_York. All running services will need to be restarted to apply timezone change. This affects time display in applications and log display time values.

Log Management

VRRP Logs

$ docker logs keepalived

Authentication Proxy Logs

$ docker logs auth-proxy

Audit Logs

When authentication server is running, you can configure audit events to be logged to a remote syslog via the web interface.

Diagnostic Logs

Currently diagnostic information can be retrieved with the docker logs command.

# Diagnostics information for the Authentication Server
$ docker logs dashboard

Submitting support requests

Use ntk sys supreq to create a single archive containing all diagnostic information about specific cluster node. Use included scp utility to copy this archive to remote server or use scp client on your computer to retrieve archive from cluster node. Please attach this archive to support request ticket.

FAQ

How to update manually installed HTTP SSL certificate files

To update SSL certificates follow these steps: - Use scp or similar utility to transfer certificate and key files to appliance. - Use ntk cfg setc ssl.pem and ntk cfg setc ssl.key to load data from files into appliance configuration as shown below: shell ntk cfg setc ssl.pem /home/ntkadmin/ssl.pem --load-file ... certificate output follows ... ntk cfg setc ssl.key /home/ntkadmin/ssl.key --load-file ... key output follows ...

Appendix I - Configuration Keys

The following configuration keys store important values:

Key Description
cluster.bootstrap_expect The number of expected servers in a cluster. This value is only relevant during cluster bootstrapping (i.e. the first time it is started). You should not set this value directly.
cluster.is_root 1 or 0. Specifies whether this server is the bootstrap leader (1) or not (0). This value is only relevant, when initializing a cluster for the first time.
node.name Name of the node. This is a descriptive value only, and can be set directly.
node.datacenter Node datacenter. This is a descriptive value only, and can be set directly.
host DNS name by which the Authentication Server will be accessible (e.g. ntk.example.com). If ssl.acme.status is on, then this should be a publicly accessible address.
ssl.acme.status On/off flag. When on - TLS certificates will be created and auto-renewed, using Let’s Encrypt. When off, TLS certificates must be set via the ssl.pem and ssl.key configuration values.
ssl.acme.email When using Let’s Encrypt TLS certificates, this will be sent as the contact address.
ssl.pem TLS certificate (in PEM format). This is used only when ssl.acme.status is not on. You can set this value directly. It should begin with -----BEGIN CERTIFICATE----- and have newlines escaped as \n.
ssl.key TLS certificate key (in PEM format). This is used only when ssl.acme.status is not on. You can set this value directly. It should begin with -----BEGIN PRIVATE KEY----- and have newlines escaped as \n.
secret_key_base This is a secret value used to verify the integrity of the Authentication Server’s HTTP cookies.
cli This key stores the ntk utility metadata - the current version, version integrity checksums etc. None of these values should be set manually.
vrrp This key stores VRRP configuration. Do not set these values directly, instead - use the ntk vrrp subcommand. Configuration structure is not guaranteed to remain the same across versions.
loglevel Controls global log level. Possible values: error, warning, info, debug. Services need to be restarted for changes to be applied.