Overview

“NetBox is the leading solution for modeling and documenting modern networks.”. It can be simply run via e.g. a container or other methods.

In this example we show how to setup NetBox to be access by, and signed into by, Agilicus AnyX, providing secure remote access with single sign on.

Netbox setup

For this example, we are using the docker-compose environment https://github.com/netbox-community/netbox-docker of the community netbox-docker.

We modify the env/netbox.env file to add these lines:

CSRF_TRUSTED_ORIGINS="https://netbox.__MYDOMAIN__ http://localhost"

REMOTE_AUTH_ENABLED=True
REMOTE_AUTH_BACKEND='netbox.authentication.RemoteUserBackend'
REMOTE_AUTH_AUTO_CREATE_USER=True
REMOTE_AUTH_AUTO_CREATE_GROUPS=True
REMOTE_AUTH_GROUP_SYNC_ENABLED=True
REMOTE_AUTH_HEADER=HTTP_X_GATEWAY_USER_EMAIL
REMOTE_AUTH_GROUP_HEADER=HTTP_X_GATEWAY_PRIMARY_ROLE
REMOTE_AUTH_DEFAULT_GROUPS=admin

These headers for REMOTE_AUTH_* are documented here: https://netboxlabs.com/docs/netbox/en/stable/configuration/remote-authentication.

The CSRF_TRUSTED_ORIGINS allows the Agilicus external name to be allowed to sign in.

Once we have done this, we run docker compose up, and, NetBox is now running.

From here, assuming we already have a connector installed, we can create an application following the below steps. All except the last step are done through the ‘Resources/Applications/New’ stepper. The last step (enabling User Context headers), navigate to Resources/Applications/Overview, and select your new application, then select the Proxy header.

At this stage, you should be able to navigate to https://netbox.__MYDOMAIN__ (or, https://profile.__MYDOMAIN__ and see the icon). You should be auto-logged in as a user in the admin group. You can later add users to Agilicus AnyX permissions with ‘self’ or ‘admin’ to give control of what they can do in netbox. Add additional groups if desired.

NOTE: since we chose the ‘multiple roles’ option in the stepper, we must manually configure the firewall rule, allowing each of the roles full HTTP access, and then allowing NetBox to decide what sub-permissions to do based on group.

Overview

LibreNMS is “a fully featured network monitoring system“. In order to make it externally accessible, we will treat it as a Web Application.

Application Setup

The LibreNMS application is setup using defaults with 1 exception: we must HTTP Rewrite the Media Type text/html.

In this sample, we show setting it up so that all users in the organisation have equivalent access.

First, create a new web application. Select a ‘name’ (which will become part of the URL, e.g. https://NAME.DOMAIN), a description and a category. The latter two are for information purposes only.

Now we can select a hostname. By default it will be NAME.DOMAIN, but, if you have an alternate hostname setup as a CNAME, you may use it here.

You may use an onsite connector you have previously setup, or a VPN you have previously setup.

This choice controls the fidelity of the access & audit logs, as well as the depth of the WAF. The first choice gives full audit records on each access transation, and protects against SQL injection, CSRF and XSS attacks. The second option keeps the custodial control of the TLS private key entirely within your site and private. Both will work for this example.

Now we select the coordinates of the LibreNMS server *as it is on your current site*. This might be a hostname or IP, it is how you currently use LibreNMS.

We now select authenticate by the reverse proxy.

Here we can control the initial default access. You can change this later in the ‘Access’ tab.

We are now complete on the initial setup, and then have 1 more non-default step to perform, to do the Media rewrite.

Now that this is done, we have one last step. The LibreNMS web application writes the local IP:PORT into the HTML and we must rewrite it. To do so, on the ‘define’ screen, select ‘librenms’ from the top, and, under the HTTP Rewrites section, add ‘text/html’ to the media to be re-written. At this stage, we should be able to login and use normally.

In addition, you should set ‘application/json’ to the rewrite, in order to be corrected on return to API-driven components.

You may consider setting the ‘Include user context headers’ which will cause the authenticated user information to be available as a trusted header.

Overview

In this demonstration we will use the Agilicus Connector to securely expose an internal web server, using a clientless zero-trust secure connector.

Install Sample Web Server

Download the sample web server (the source code and compiling instructions are on github). Unzip the package and run the appropriate one for your platform, open a browser to http://localhost:8080/. This does not modify any files on your computer: it is a single executable with a few HTML files inside it.

don@office[gke-corp]:static-web-site$ ./static-web-site
 ::1 - - [28/Jan/2021:20:50:04 -0500] "GET / HTTP/1.1" 200 0
 ::1 - - [28/Jan/2021:20:50:04 -0500] "GET /assets/vendor/bootstrap/css/bootstrap.min.css HTTP/1.1" 200 0
 ::1 - - [28/Jan/2021:20:50:04 -0500] "GET /assets/vendor/boxicons/css/boxicons.min.css HTTP/1.1" 200 0
 ::1 - - [28/Jan/2021:20:50:04 -0500] "GET /assets/vendor/icofont/icofont.min.css HTTP/1.1" 200 0

OK, now we have a sample web server running locally. The web browser should show something like below.

Setup Agilicus Connector

Refer to the Agilicus Connector configuration instructions for more details.

Setup Sample Application

Refer to the Applications configuration instructions for more details.

Create a new Application. Select a template (static website). You can walk through the remainder of the options, but they will be filled in correctly already (except for the Connector to use).

For the demonstration we will use the existing domain name choice. However, you may wish to create a CNAME and have this application available as e.g. ‘wiki.example.com‘.

Now we will select how the application upstream connection works. We will access the simple static web site from onsite (emulating e.g. your corporate wiki or vacation planner)

Now we will select the internal coordinates. The sample static web site runs on our localhost, and on port 8080. You might have instead used an internal hostname here (e.g. wiki.example.com) and a port like 80.

Now we will choose how users are authenticated. In some cases you may just want a completely unauthenticated site. In some cases your application has native support for OpenID Connect (in which case see Authentication Clients).

Here we will choose “Is authenticated by a proxy”. This means the Agilicus Platform will automatically handle authentication and authorisation. Your application will receive pre-defined headers with the username and user roles. No unauthenticated user traffic will arrive at your application.

We may also choose a Logout URL, in case your web site has a spot users can end their session explicitly. This is optional.

We will also choose how the users are Authenticated. This controls how groups will be pre-setup for you, and how users are assigned. If we select “Is used by all users in my organisation”, this means that any user will have a default role, automatically: no need to grant permission.

If we say “has named users with a single role”, we will have to select the users manually, and all will have the same web application firewall permission (e.g. allow/deny).

We are now complete. We are given an overview of what we have setup, and an option to download a JSON file we might later use as a template. This is optional. When we hit Apply, a set of steps are performed:

1. Create new Web Application Firewall
2. Create DNS name
3. Create TLS certificate
4. Apply Web Application Firewall Rules
5. Create default group
6. Assign users to group
7. Create Authentication Client
8. Configure Identity Aware Web Application Firewall to use Authentication Client

These steps will take approximately 3-4 minutes.

You will be given a URL to navigate to with your browser. Its pattern will be https://static-website.MYDOMAIN. If all has gone well, when you navigate to that you will be required to sign-in, and then it will work the same as when you use http://localhost:8080.

Note: there is a default Content-Security-Policy in the Web Application Firewall, and a default set of Web Application Firewall rules for this application. Yours may vary and may require allowing e.g. different Javascript script-src or style-src.

Congratulations! You are now complete.

Things you may wish to observe:

• the sample website outputs a line of text for each HTTP request. Note that an unauthenticated browser does not generate any traffic
• the user audit screen will show your accesses: each session, each HTTP transaction. This is cryptographically secure, based on a JWT on each transaction: no IP/port matching.

Overview

See the companion code in Github. This can be run with docker-compose up to demonstrate.

In this example, we have an HTML web dashboard (running on localhost:5000), and an API (running pn localhost:5001). We use the Web Application Firewall rewrite to remap the API to a prefix (so it will become conceptually localhost:5000/api). This allows it to be represented as a single-sign-on session, on a single external URL.

In this example, we first create an application. On the 3rd step, “My Application Is An API”… if your API correctly uses CORS, you can leave this as-is. Else consider setting it, or example the ‘Define’ step later for more configuration.

When you get to step 7 (Configure Upstream Services), enter 1 for each endpoint. The main (HTML) one is ‘application’, the others are path_prefix. Substitute the real hostname if you need (you may need additional remapping later if your application is hard-coded).

Once you have completed the New Application Stepper, navigate to the ‘Define’ screen to refine the setup. On the ‘Proxy’ Tab, enable ‘Rewrite Common Media Types’.

Add permission to your user, and the page should work at https://<name><domain>/

Overview

In this example, we will show setting up an “Icecast” audio streaming system, and force users to be authenticated via OpenID Connect. We will also show Authorisation: a set of “viewers” who can stream the music, and an Administrator.

For this example we will use an onsite connector as a means of reaching the Icecast server. Go through the steps to install this now (or use one already installed).

First, let us open the “New Application” menu. We will do this manually (without a template) to demonstrate.

Give the application a name. This must be a valid hostname (it will be part of the URL a user will use, e.g. https://<NAME>.<DOMAIN>. You may describe the application and give it a category, these are just used for reporting purposes.

You have a choice: you can supply your own domain name (in which case you must put a CNAME in your DNS pointing to our domain ca-1.agilicus.ca), or you may use a name from the CNAME you set up when you created the organisation initially.

Now we indicate how the upstream Icecast application is accessed. We will do this via the onsite connector.

Select the specific connector (which we previously created and installed).

You now have 2 choices. You may have a full web application firewall with fine-grained (e.g. per transaction) audit logs, or you may have a perfect TLS session end to end transparent (in which case the private key will be solely on your site: we will have no access). For this demonstration, we will use the Enhanced Web Application Firewall.

We now enter the coordinates (in the private network, e.g. as would be reachable by that onsite connector) for the Icecast server.

We wish to have the OpenID Connect Proxy handle authentication and authorisation. We can also enter a URL that, when fetched, will force a logout.

We are later going to have 2 types of users (viewers, admins). You might choose an “auto-create” user type for the viewer, allowing anonymous but attributable access.

At this stage we are done creating the application, we will now set up the identity aware web application firewall authorisation.

Create Authorisation Roles, Firewall Rules

On the “Define” screen we can fine tune. First add a “viewer” role, then an “admin” role which includes viewer. Make the default role “viewer”.

Now let us set up the firewall. We will allow ‘viewer’ to GET anything except /admin. We will allow administrators to do any (GET/PUT/POST/…) on /admin/ tree.

At this stage we can open up our Icecast server (https://APPLICATION.DOMAIN), we will be challenged to provide credentials, after that, single sign-on, we are streaming our sweet music.

Overview

In this demonstration we will show compiling and hosting a simple web application. No container is needed, we can entirely host it by just dropping a ‘zip’ file of the build into a browser. In addition, we will entirely handle the authentication for the application (no changes, single-sign-on). We will protect a manifest file of secrets to prevent access by unauthenticated users.

The specific application I will demonstrate is gitlab-monitor, a tool which monitors your Gitlab pipelines. It has an unfortunate security model: it requires you to place a config file on the server, accessible by the client, which has a Gitlab Personal Access Token. This is not safe. So, lets host it safely.

Building The Application

Every application has its own build strategy. Make, npm, nuget, etc. This one uses the npm (or yarn) ecosystem.

git clone https://github.com/timoschwarzer/gitlab-monitor
cd gitlab-monitor
npm i
npm audit fix
npm run build
tar -C dist -cvf /tmp/gitlab-monitor.tar .

OK, now we have built the application. We have a file, /tmp/gitlab-monitor.tar, which is the binary ready to run. Let’s get it on the web with a domain name, a certificate, etc.

Create Application, Setup Hosting, Authentication, Permissions

Step 1. Create Application

An application is a type of template, we will later make instances of it (e.g. staging, production). The application configuration will ask for a name (this will become the hostname, e.g. https://<appname>.<yourdomain>. We will add an image (which will show up in https://profile.<yourdomain> for launching).

We select the Identity Aware WAF Proxy (v1) runtime.This will, by default, force authentication of the user.

Now we will upload the application bundle we compiled above. You can just drag and drop the tar file onto the button, or, press “upload bundle” and select it. You can pick a name (e.g. gitlab-monitor-v2) or use the default one of the file name.

OK now we must configure the firewall rules. There are 2 firewalls in series here, the first acts on fine-grained paths, and the second acts to force authentication before allowing access. We will rely on this feature to protect our config.json (which contains the secret). Thus we must allow access to all paths first, and then deny the config file except for known users.

OK, now we have the template defined, we will create an instance. Instances can be used for e.g. “staging vs production”. They typically run in child-organisations, which is out of scope here. We will use ‘latest’ as the tag (which controls the version of the runtime). We attach the bundle from above.

We will now mount our config file into the instance. First, configure instance:

Now we can upload our config file, specify the path as /app/config.json, and we are done.

Overview

An Application may be hosted in the Agilicus platform, or external. For this example we are going to show how to develop a new application, initially not hosted. For steps we will need:

1. Authentication Client (OpenID Connect client id)
2. Application (to attach permissions to, externally hosted)
3. Create group, assign users to it

Application Setup

We can do the first two steps aove in a single step with the “New Application” configuration. First, under the Application menu, select ‘New’. Select ‘manually’.

Now we give the application a name. The name will eventually be part of the URL (as a hostname) so keep it a single word. We add a description (which end users will see in the catalog), and a category (which will be used for grouping in reports).

We now indicate how we will ultimately access this application. Since it is (currently) external, this does not matter, leave the top item checked. Later when we move it to be hosted this will become a URL.

Now we indicate how the user accesses the application. Since we are just developing it, and it is on our desktop, leave this as “over the public Internet” (e.g. the application is not hosted in or through the Agilicus platform for the data path).

We now indicate that our application will participate in the authentication. This means that it has a built-in library handling OpenID Connect.

We must now configure the redirect URI (which is part of the OpenID Connect specification). Here we will use http://localhost:3000/ since we are hosting this on our desktop. Later we will add the production redirect URI in the Authentication Client.

We must now indicate how users are granted access. If we say “is used by all users in my organisation”, this means that the “All users” group will be granted access.

If we say “has named users with a single role”, this means authorisation is Boolean (allow/deny), but for a named set of users. We will use this option for the sample.

If our application has distinct roles for the users (e.g. Admin, Editor, Viewer), we can use the “has named users with distinct roles”.

Now we are complete, we will hit apply.

We can inspect the Authentication Client created. Later when we change the redirect URI we can change it here.

At this time we will change the application allowed from ‘All’ to ‘Sample-React-App’, forcing it to only allow our new application.

Group Create, Permissions Assign

Create a new group. Assign yourself (and any other users)

Now, create a new row in the “Application Permissions”, add the new group, and assign ‘Self’ as a permission to the application column.

Sample Code

See github repo for a sample using react-openidconnect library.

import React, {Component} from 'react';
import Authenticate from 'react-openidconnect';

import logo from './logo.svg';
import './App.css';

var OidcSettings = {
  authority: 'https://auth.cloud.egov.city/',
  client_id: 'sample-react-auth',
  redirect_uri: 'http://localhost:3000/',
  response_type: 'id_token token code',
  scope: 'openid profile email',
  post_logout_redirect_uri: 'https://localhost:3000/',
};

class App extends Component {
  constructor(props) {
    super(props);
    this.user = 'unknown';
    this.userLoaded = this.userLoaded.bind(this);
    this.userUnLoaded = this.userUnLoaded.bind(this);

    this.state = {user: undefined};
  }

  userLoaded(user) {
    if (user) {
      this.user = user;
      console.log(user);
      this.setState({user: user});
    }
  }

  userUnLoaded() {
    this.user = 'unknown';
    this.setState({user: undefined});
  }

  NotAuthenticated() {
    return (
      <div className="App">
        <header className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <p> Click to authenticate </p>
        </header>
      </div>
    );
  }

  render() {
    return (
      <Authenticate
        OidcSettings={OidcSettings}
        userLoaded={this.userLoaded}
        userunLoaded={this.userUnLoaded}
        renderNotAuthenticated={this.NotAuthenticated}
      >
      `<div className="App">
        <header className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <p> Welcome User! {this.user} </p>
        </header>
      </div>`
      </Authenticate>
    );
  }
}

export default App;

Overview

The following guide outlines the steps for creating a VTScada web application in the Agilicus platform. These instructions are intended for VTScada v12.1.30+ deployments on Windows, Linux, and Android devices.

If you require assistance for Safari and iOS device , contact us.

Step 1: Create the Application

From the left sidebar, expand Applications and select New:

1. Application name. The chosen name will also be required to configure the VTScada Server list later in the instructions.
2. a description of the application.

Click on Next to get to the “Hostname Aliases” section and accept the proposed Hostname, or specify a different one. (If different, will need to be applied to the VTScada Server address list)

Select the first option of “I access via NAME-OF-APP.subdomain.domain.name” and click on next.

First under “My application is accessed” select “from my site via an onsite connector”

• Within “Set up web application firewall” select “My application expects to receive requests using its internal hostname”

Under “My application hosts all or most of its pages under a common path prefix”, enter your VTScada Realm name (eg: /Default) that is the default Path we will allow authenticated users to navigate. Other path exceptions will be created later in the Firewall ruleset.

From the “Select a connector” drop down, pick the connector that you had previously created. 

Within the “Enter the hostname” field, type in the hostname of the server that is hosting your VTScada web portal. This should be the same as your VTScada thick client.

In this configuration, the VTScada Server Setup and “Default” Realm server / and URLs point to an IP address of 192.168.10.15, and a TCP port of 80, with no SSL (Secure).

Click on Next to be taken to the “Authentication section”:

Select “is authentication by a proxy” and type in “/logout” (without the double quotes) into the “Enter the logout url” field.

We will also use the Optional “Enter the redirect after signin path” URL to redirect to the VTScada Server Realm page once users perform Authentication. Therefore, fill the value of the field with the name of the Realm ( eg: /Default )

Select “has named users with a single role (I will assign users later)” and click on Next:

Select the APPLY button to finish off this section of the setup.

Step 2: Configure the Application

Click on “Overview” within the Applications section and select the Actions icon in the very far right hand side of the screen for the VTScada application that we just created:

After clicking on “Configure Application”, select the Proxy section

Within the Proxy section select the “Common Path Prefix” and input the Realm name. This will limit the Anywhere Client to the desired realm path unless allowed by the Firewall rules in the following steps. In this case, we use the path /Default which is our VTScada realm.

Click on “Rewrite Common Media Types” checkbox.

Next, select the “Security” section and scroll to the “Firewall Rules”

In the Firewall section, we will enter rules that will allow Authenticated Users with permissions to the “Self” role to access specific paths within the VTScada Anywhere Client. These specific path are explicit in order to match valid content within the VTScada Realm that may fall outside of the “Path Prefix” set in the previous step ( eg: /Default ). These paths contain various web objects such as Icons, CSS files, Images, Anywhere Client scripts, and specific paths to the Server realm GUUID.

If using Website uptime monitoring, we recommend making the standard website browser icon “favicon.ico” available without authentication so that Web monitoring software can easily test end to end website uptime and availability by fetching this object.

The following rules are recommended:

1. /[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}
2. ^/.*VIC01663918
3. ^/Default[/]?$ ( YOUR ACTUAL REALM NAME )
4. ^/VTScada(Light)?Branding.*
5. ^/favicon.ico
6. ^/vts.css
7. /logout

Explainer:

1. This rule matches the GUUID path pattern used in VTScada Anywhere Client. If you wish to be more precise and secure, you can change this rule to the actual GUUID seen in the browser URL path like this example, and make it “^/Default/48708544-07e3-4d1b-9b6e-ea8ace4b00fe”

2. This rule matches the Anywhere Client script path

3. This rule should bear the name of the Server realm. In this case “Default”. This should be made to match your Server realm. This should be created by default in the original application configuration, but we can change the syntax here to be more specific.

4. This rule matches the VTScada path for images and objects for both the Regular and Light version of the server

5. This rule matches the standard favicon.ico website icon

6. This rule matches the Style Sheets path

7. This rule matches a logout path that would be used to sign out of the VTScada application

We have now completed setting up your VTScada resource within the Agilicus platform.  At this point you would want to create the appropriate Role Based Access Control permissions per the steps below:

Step 3: Add Permissions

1. Select Access -> Application Permissions
2. Grant Firewall Role (self) Permission of the application name (VTS) to the required Identity

Step 4: Configure VTScada

From the VTScada Application Manager, select the Server Setup dialog:

Select the “Connection Addresses” tab, select the “+” icon to create a connection address entry.

Enter the matching Agilicus Application name FQDN exactly as created in the “Connection Address” dialog, select port 443 and check “Secure“

Click “Apply” to submit the new address. This will allow VTScada Anywhere Client to present a list of valid hostnames where the Anywhere Client is allowed to connect. Since the FQDN is the one we configured through the Agilicus platform, the VTScada Anywhere Client will be permitted to browse via the newly created service.