PreAuth Option

Overview

PreAuth is an implementation of FAS without the resource utilisation of a separate web server, particularly useful for legacy devices with limited flash and RAM capacity.

PreAuth is a pre-authentication process that enables NDS to directly serve dynamic web content generated by a script or executable program.

Note

From version 3.3.1 onwards, a PreAuth login script is pre-installed. This generates a page asking for username and email address. Logins are recorded in a log file. It is enabled by un-commenting just 3 lines in the config file. From version 4.0.2 onwards it is enabled by a single line in the config file that overrides any other FAS configuration. From version 4.3.0 onwards it is enabled by setting config option login_option_enabled to “1”

PreAuth is enabled by configuring NDS FAS to point to a virtual URL in the NDS web root instead of an independent FAS server. The location of the PreAuth script or program is provided in the config file.

The PreAuth script can be a shell script or any other script type that an interpreter is available for (for example, PHP-cli, Python etc.).

A PreAuth program could be, for example, a compiled program written in C or any other language that has a compiler available for the platform.

The PreAuth script or program will parse the url encoded command line (query string) passed to it and output html depending on the contents of the query string it receives from NDS. In turn, NDS will serve this html to the client device that is attempting to access the Internet.

Selecting Pre-Installed Username / Email Login Script (v4.3.0 onwards)

The default preauth login script is installed as part of the NoDogSplash package providing username/emailaddress login as an alternative to the basic splash page.

It is enabled by setting in config:

option login_option_enabled = ‘1’

No additional FAS or PreAuth config settings are required.

Using PreAuth version 4.0.2 onwards

From version 4.0.2 onwards, PreAuth is enabled with a single configuration option:
  • preauth. This the path to the PreAuth script or executable.

This option overrides any other FAS configuration and takes the form of the path to the PreAuth script. The path to the preinstalled login script is included in option preauth in the default config files, for example in OpenWrt:

#option preauth ‘/usr/lib/nodogsplash/login.sh’

The “#” symbol means the line is commented. To activate, remove the “#”. save and restart Nodogsplash.

Using PreAuth version 3.3.1 to version 4.0.1

From version 3.3.1 to version 4.0.1, PreAuth is set up using the standard NDS configuration for FAS (See the Forwarding Authentication Service (FAS) section of this documentation).

In addition a single PreAuth configuration option is required to inform NDS of the location of the PreAuth script or program.

In summary, the following configuration options should be set:
  1. fasport. This enables FAS and must be set to the same value as the gateway port.
  2. faspath. This must be set to the PreAuth virtual url, “/nodogsplash_preauth/” by default.
  3. preauth. This the path to the PreAuth script.

The remaining FAS configuration options must be left unset at the default values.

ie:
  1. fasremoteip. Not set (defaults to the gateway ip address).
  2. fas_secure_enable. Not set (defaults to enabled).

Note

From version 3.3.1 onwards, the example PreAuth script is preinstalled.

Enabling the Preinstalled Login Script (v3.3.1 to 4.0.1)

On Openwrt, edit (to uncomment) following lines in the /etc/config/nodogsplash file:

#option fasport ‘2050’

#option faspath ‘/nodogsplash_preauth/’

#option preauth ‘/usr/lib/nodogsplash/login.sh’

To read:

option fasport ‘2050’

option faspath ‘/nodogsplash_preauth/’

option preauth ‘/usr/lib/nodogsplash/login.sh’

Enabling the Preinstalled Login Script (v4.0.2 onwards)

On Openwrt, edit (to uncomment) following line in the /etc/config/nodogsplash file:

#option preauth ‘/usr/lib/nodogsplash/login.sh’

To read:

option preauth ‘/usr/lib/nodogsplash/login.sh’

For other operating systems edit the equivalent lines in the /etc/nodogsplash/nodogsplash.conf file

After making the change, save the file and restart the router.

What Does the Example Login Script Do?

This example shell script generates html output for NDS to serve as a dynamic splash page.

The example asks the client user to enter their name and email address. On entering this information the client user then clicks or taps “Continue”.

The script then generates html code to send to NDS to serve a second “Thankyou” page and creates a log entry ( /tmp/ndslog.log ), recording the client authentication details.

On tapping “Continue” for the second time, the client user is given access to the Internet.

This is a simple example of a script to demonstrate how to use PreAuth as a built in FAS. The script could of course ask for any response from the client and conduct its own authentication procedures - entirely at the discretion of the person setting up their own captive portal functionality.

PreAuth with Remote Images

An additional example PreAuth script, demo-preauth-remote-image.sh, is available in the source code:

https://github.com/nodogsplash/nodogsplash/archive/master.zip

and extracting from the folder:

“forward_authentication_service/PreAuth/”

This is an enhancement of the preinstalled login.sh, giving an example of how to display images pulled in from remote web servers, both http and https.

The example displays the NodogSplash avatar image dynamically retreived from Github.

Writing A Preauth Script

A Preauth script can be written as a shell script or any other language that the system has an interpreter for. It could also be a complied program.

NDS calls the preauth script with a command line equivalent to an html query string but with “, ” (comma space) in place of “&” (ampersand).

Full details are included in the example script demo-preauth.sh available by downloading the Nodogsplash zip file from

https://github.com/nodogsplash/nodogsplash/

and extracting from the folder

“forward_authentication_service/PreAuth/”

Defining and Using Variables

The query string is sent to us from NDS in a urlencoded form, so we must decode it here so we can parse it. In a shell script we would use the code:

query=$(printf "${query_enc//%/\\x}")

In the example script we want to ask the client user for their username and email address.

We could ask for anything we like and add our own variables to the html forms we generate.

If we want to show a sequence of forms or information pages we can do this easily.

To return to the script and show additional pages, the form action must be set to:

<form action=\"/nodogsplash_preauth/\" method=\"get\">

Note: In a shell script, quotes ( ” ) must be escaped with the

"\"

character.

Any variables we need to preserve and pass back to ourselves or NDS must be added to the form as hidden:

<input type=\"hidden\" name=......

Such variables will appear in the query string when NDS re-calls this script.

We can then parse for them again.

When the logic of this script decides we should allow the client to access the Internet we inform NDS with a final page displaying a continue button with the form action set to:

"<form action=\"/nodogsplash_auth/\" method=\"get\">"

We must also send NDS the client token as a hidden variable, but first we must obtain the token from ndsctl using a suitable command such as:

tok="$(ndsctl json $clientip | grep token | cut -c 10- | cut -c -8)"

In a similar manner we can obtain any client or NDS information that ndsctl provides.

The query string NDS sends to us will always be of the following form (with a “comma space” separator):

?clientip=[clientipaddress], gatewayname=[gatewayname],  redir=[originalurl], var4=[data], var5=[data], var6......

The first three variables will be clientip, gatewayname and redir

We have chosen to name redir as $requested here as it is actually the originally requested url.

There is one exception to this. If the client presses “back” on their browser NDS detects this and tells us by returning status=authenticated instead of redir=[originalurl]

If we detect this we show a page telling the client they are already logged in.

Additional variables returned by NDS will be those we define here and send to NDS via an html form method=get

See the example script which uses $username and $emailaddr

There is no limit to the number of variables we can define dynamically as long as the query string does not exceed 2048 bytes.

The query string will be truncated if it does exceed this length.

Displaying Remote Banner Images

A modified version of the Username/Email-address login script is available that demonstrates how to display remotely hosted images on its login pages.

This additional example PreAuth script, demo-preauth-remote-image.sh, is available in the source code:

https://github.com/nodogsplash/nodogsplash/archive/master.zip

and extracting from the folder:

“forward_authentication_service/PreAuth/”

This is an enhancement of the preinstalled login.sh, giving an example of how to display images pulled in from remote web servers, both http and https.

The example displays the NodogSplash avatar image dynamically retrieved from Github.