Introduction

Notakey Authentication Proxy (NtkP) is a proxy server that allows transparently adding Notakey-based 2-factor authentication in existing systems, which are using standard authentication protocols.

Currently, NtkP supports RADIUS with PAP and CHAP authentication types.

Technical Summary

NtkP manages a list of known IP addresses, which can send it requests. Each IP address has a corresponding secret. Each of these IP addresses correspond to one upstream client.

NtkP also has one backing RADIUS server address and secret defined. This is the downstream RADIUS server.

When a RADIUS message is received, it will be transparently proxied to the downstream server. Each incoming message will be decoded with the matching upstream secret, and re-encoded with the downstream server’s secret.

Each message returned by the downstream server will be similarly decoded and re-encoded, to match the secret expected by the upstream client.

In addition, if the RADIUS message is an Access-Request message, then the username contained in the message will be passed to Notakey API, and await verification. If the end-user denies this request on their smartphone, the response will be changed, before being returned to the upstream client.

While waiting for the user to respond on their smartphone, upstream clients may time out, and re-send the Access-Request message. In this case, the proxy will attempt to handle duplicate requests, based on packet ID values and corresponding usernames.

Flowchart

System Requirements

Docker

The recommended environment for NtkP is Docker, so any Docker-enabled host should be fine.

Windows

NtkP can alternatively be installed as a Windows system service. It has a dependency on .NET Framework v4.5.

See: Microsoft .NET Framework v4.5 system requirements.

Installation instructions (Docker)

The recommended way to obtain NtkP is by using Docker. It is published as the notakey/authproxy image. Use the tag latest to always use the latest version, or specify a specific version, using the tag.

# Download the latest version
$ docker pull notakey/authproxy:latest

# Download a specific version
$ docker pull notakey/authproxy:1.0.0

The link to the Docker Hub page: Notakey Authentication Proxy on Docker Hub.

Installation instructions (MSI)

The MSI package is typically named with the pattern Notakey.AuthProxy.X.Y.Z.msi or Notakey.AuthProxy.X.Y.Z-W.msi.

X.Y.Z is the version number (e.g. 1.0.0), and -W is an optional qualifier (typically used for backwards-compatible bugfix releases).

You will need to agree to the EULA.

After the installer finishes, a new background service should be registered. The service should be named “Notakey Authentication Proxy (Heimdall)” and show the correct version in the description pane.

Configuration

Configuring the MSI

Example configuration file (only <argument> tags should be modified normally).

<service>
  <id>notakey_heimdall_service</id>
  <name>Notakey Authentication Proxy (Heimdall)</name>
  <description>This service runs the Notakey Authentication proxy.</description>
  <executable>Notakey.Application.Cli.AuthProxy.exe</executable>
  <logmode>rotate</logmode>

  <argument>--notakey-access-id</argument>
  <argument>a1234567-b1234-c123-d123-e1234567890</argument>

  <argument>--notakey-host</argument>
  <argument>http://demo.notakey.com/api/</argument>

  <argument>--message-ttl-seconds</argument>
  <argument>30</argument>

  <argument>--message-title</argument>
  <argument>VPN authentication</argument>

  <argument>--message-description</argument>
  <argument>Do you want to allow VPN access for user {0}?</argument>

  <argument>--proxy-send-timeout</argument>
  <argument>5</argument>

  <argument>--proxy-receive-timeout</argument>
  <argument>5</argument>

  <argument>--listen-address</argument>
  <argument>127.0.0.1</argument>

  <argument>--downstream-address</argument>
  <argument>127.0.0.1</argument>

  <argument>--address-secret-in</argument>
  <argument>0.0.0.0:pass@word1</argument>

  <argument>--secret-out</argument>
  <argument>pass@word1</argument>

  <argument>--port-in</argument>
  <argument>1818</argument>

  <argument>--port-out</argument>
  <argument>1812</argument>
</service>

The configuration file for the service can be found in the installation directory. The default location is C:\Program Files (x86)\Authentication Proxy\winsw.xml.

This file passes arguments to the service in key-value pairs. Odd <argument> tags contain parameter names, and even <argument> tags contain the corresponding values.

The full list of accepted arguments:

Argument Name	Default Value
‑‑notakey‑access‑id
Notakey API access id. This value identifies the Notakey service, to which the authentication requests will be sent. For example: a1234567-b1234-c123-d123-e1234567890.
‑‑notakey‑host
Notakey API endpoint. This value should be a fully qualified URL, including both the URL scheme and path, but excluding API version. For example: https://demo.notakey.com/api/
‑‑notakey‑timeout	5
Notakey API invocation timeout (in seconds). If a Notakey HTTP API call takes longer than the specified value, an authentication error will be returned to the proxy client.
‑‑message‑ttl‑seconds	60
Timeout interval for Notakey notification message in seconds.
‑‑message‑title	VPN authentication
Title for Notakey notification sent to user device.
‑‑message‑description	Do you want to allow VPN access for user {0}?
Description for Notakey notification sent to user device. Message can contain placeholder for username it is sent to in form {0}
‑‑proxy‑receive‑timeout	5
Timespan (in seconds) in which data must be received from the downstream server.
‑‑proxy‑send‑timeout	5
Timespan (in seconds) in which data must be sent to the downstream server.
‑‑listen‑address	127.0.0.1
IP address on which the proxy will serve client requests.
‑‑downstream‑address
Downstream server IP address or hostname.
‑‑address‑secret‑in
A key-value pair of allowed client addresses and their corresponding secrets. Multiple arguments of this type can be specified (to allow multiple clients). For example: 0.0.0.0:imb3bac will allow clients from any IP address, and set the secret to imb3bac.
‑‑secret‑out
The downstream server secret value.
‑‑port‑in	1812
The port on which the proxy will serve client requests.
‑‑port‑out	1812
The port on which the downstream server will serve requests.

Configuring the Docker image

Parameters to the Docker image are set via commandline arguments or environment variables.

Parameters passed as commandline arguments takes priority over environment variables.

Each argument that the service accepts (see MSI configuration) has a corresponding environment variable, which can be used to set the same argument.

Argument Name	Environment Variable
–notakey-host	NOTAKEY_HOST
–notakey-access-id	NOTAKEY_ACCESS_ID
–notakey-timeout	NOTAKEY_TIMEOUT
–listen-address	LISTEN_ADDRESS
–message-ttl-seconds	NOTAKEY_TTL_SECONDS
–message-title	MESSAGE_TITLE
–message-description	MESSAGE_DESCRIPTION
–port-in	PORT_IN
–port-out	PORT_OUT
–address-secret-in	ADDRESS_SECRET_IN
–downstream-address	DOWNSTREAM_ADDRESS
–secret-out	SECRET_OUT
–proxy-send-timeout	PROXY_SEND_TIMEOUT
–proxy-receive-timeout	PROXY_RECEIVE_TIMEOUT

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.

Log files

The Docker container logs output as any other container.

The Windows service will log output to log files in the service’s installation directory.

winsw.err.log

This file will contain information about errors.

winsw.out.log

This file will contain informational output without errors.

More advanced logging configuration (Windows)

The Windows service is a standalone executable, wrapped as a Windows service with the WinSW utility.

For more information on how to handle the Windows service’s log management, please see WinSW Logging and Error Reporting.

FAQ

MSI installation fails with the error message “Service could not be installed. Verify that you have sufficient privileges to install system services.” Why does this happen?

If your user has sufficient privileges to install system services, then this error may sometimes occur because the Windows Services snap-in is open. In this case the installer can not update the service list.

Try closing the Windows Services snap-in and click Retry.

Does NtkP listen on only one port? Are accounting messages supported?

NtkP only listens to one port, and it expects authentication messages to be sent on this port.

Listening to accounting messages is not currently supported.

What are the implications for only supporting PAP and CHAP authentication modes?

PAP and CHAP do not sufficiently protect user credentials from man-in-the-middle attacks.

These authentication types may be deemed secure-enough for use on an internal network, where the risk for a MitM attack can be mitigated with other means.

Why does NtkP support only PAP and CHAP?

PAP and CHAP are good enough for many use cases, so we have prioritized other tasks over implementing more authentication methods.

Implementing more authentication methods is on our roadmap, however.