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

A PreAuth login script is pre-installed. From version 7.0.0 onwards, this generates by default a simple “Click to Continue” page, or by setting config option login_option_enabled to “1” it generates a username/email address dialogue. No other configuration is necessary.

A custom PreAuth can be 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.).

The default script is a shell script can be found at at /usr/lib/opennds/login.sh

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.

Configuring a Custom PreAuth

A custom 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, “/opennds_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).

What Does the Default PreAuth Login Script Do?

The Default PreAuth Login is a shell script

It is located at /usr/lib/opennds/login.sh.

It generates html output for openNDS to serve as a dynamic splash page.

Login Mode

The default script has two modes of operation set by the value of the login_option_enabled config option.

The default mode is “login_option_enabled” set to “0”. In this mode the initial page served to clients is a simple “Click to Continue” page.

If “login_option_enabled” is set to “1” asks the client user to enter their name and email address. On entering this information the client user then clicks or taps “Continue”.

In both cases, the script then generates a second page for openNDS to serve a “Thankyou” page. It then adds 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.

Customising the default login script

Static Mode Switching

The login mode provided by the “login_option_enabled” option can be any integer value and is passed to the login script. This is used in the default login.sh to determine which type of “splash page” to serve, in the standard case either “Continue” or “Username/Email”

Additional modes could be added to the login.sh script to determine custom modes of operation.

Dynamic Response

The script could modified to 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. Looking at the details of the default login.sh will show how this is done.

An example file “multifieldlogin.sh” is provided in the source code:

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

and extracting from the folder:

“forward_authentication_service/PreAuth/”

PreAuth with Remote Images

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

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

and extracting from the folder:

“forward_authentication_service/PreAuth/”

This is based on an earlier version 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 openNDS avatar image dynamically retrieved from Github.

Example of Multi Field Login

An additional example PreAuth script, multifieldlogin.sh, is available in the source code:

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

and extracting from the folder:

“forward_authentication_service/PreAuth/”

This is based on an earlier version of the preinstalled login.sh, giving an example of how to add multiple fields of information to be requested from the client.

The example displays a login form requesting the client to enter:
  • Username
  • Phone
  • Address
  • Access Code

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.

openNDS 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 default script login.sh.

Defining and Using Variables

A Dynamic set of variables can be defined in the PreAuth dialogue and used for authentication verification purposes and/or logging.

This is not the same as, and must not be confused with, Custom Parameters. Custom parameters are statically defined by the openNDS configuration and can be read directly by the PreAuth script if required.

In the login.sh 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=\"/opennds_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=\"/opennds_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

(Note: In login.sh, we have chosen to name redir as $requested as it is actually the originally requested url.)

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

If we detect “status” in the query string, 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

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.