There are 3-phases in the life cycle of usage: Authentication, Authorisation, Access. People commonly refer to ‘multi-factor authentication’, which enriches the information a user must know/have/be in order to properly authenticate themselves.
However, some security policies cannot be modelled simple as “do I know who this person is” in the authentication phase. These must be evaluated continually, rather than once when the user provides credentials. Below are a few example security policies that cannot be modelled solely with authentication.
Multi-Factor Required on Time-Interval or Based on Location
Imagine a user signs in on a device, and gets an ID Token, an Access Token, and, a Refresh Token. They can now present the access token until it expires, and, refresh it with the refresh token. This could be good for 1 week as an example, and be appropriate for usage of the corporate wiki or email.
Now imagine there is an application of significant importance to the company. A breach of it would be have a larger downside than a breach of the wiki. The company has decided on a security policy such that the user must prove they are still in possession of the multi-factor device each 8-hour shift. This cannot be expressed with Authentication Rules.
GeoIP Restricted Access By Resource
Using Authentication Policies, we can control where a user is at sign-in time, but not where they are at time of use. Imagine a singular resource which requires a tighter knowledge of the user’s location proxied by IP. It might require allowing only from a specific IP range, or, only from certain countries, or, from everywhere except certain countries.
Configuration
Policies are created in isolation, and then attached to resources via labels. A policy can apply to multiple resources.
Step 1: Create Label To Attach Policy
Navigate to Resources/Overview. On the first resource you intend the policy to affect, type a name for it on the right (e.g. ‘canada-only’).
Now, select all resources to which it should apply, and then select ‘BULK REPLACE LABELS’, enter the name of your new label.
Step 2: Create Policy (Geo-IP / IP Restriction)
From Access/Policies, select NEW. Select ‘Device Information’, indicating that we will be using information relating to the user’s device for the policy.
Give the policy a name. Here we have used the same name as the label, but you can use any.
Configure the policy. Here as an example we will select the ‘country codes’, and, select CA for Canada.
Enter some information describing this policy (e.g. why you created it), and, the label from above. This policy will now apply to all resources with that label (you can later navigate to Resources/Overview to apply it to more new resources).
We can now see the policy in the table, and it should be active within a few seconds.
A QNAP NAS runs a custom Linux operating system, providing storage and other services in a consumer and small to medium business environment.
Installing the Agilicus Connector on the NAS can facilitate accessing the shares remotely, as well as providing a means of remote management.
Install
The Agilicus Connector will run as a container on the QNAP. In order to do this, you must have the Container Station feature enabled.
Enable QNAP Container Station
Create Agilicus Connector as Container
There are two methods to this: via the QNAP Web management interface, and, via the QNAP shell. Both achieve the same objective. If you use the QNAP Web management interface, be aware there is an expiry time on the challenge-id when you are copying from the Agilicus admin interface.
Option 1: QNAP Web interface
You will copy 3 fields from the Agilicus connector install screen (Resources/Connectors/New): two environment variables, and one image. The image should be cr.agilicus.com/pub/images/agilicus-agent/client:stable and the environment variables will be AGILICUS_CHALLENGE_ID=XXX and AGILICUS_CHALLENGE_CODE=XXX. These latter two are only good for a few minutes, regenerate if it takes you longer.
You will likely want to mount your QNAP Volume(s) into the same location (via bind host mount path), allowing re-exporting shares via Agilicus Share. (e.g. select ‘bind mount’ on the Storage screen, select the yellow file folder, pick a shared directory, then copy the name to the next field).
Note: there is an error in the first mount image, it should not be /opt, it should be /etc/agilicus/agent.
Option 2: Paste via Shell
The command line given from the Agilicus Admin interface on the install new connector, docker tab, will work as-is, you can just paste it. However, you will likelywant to mount /share into /share (via bind host mount path), allowing re-exporting shares via Agilicus Share. You can achieve this by adding -v /share:/share into the command line before the image. This will look like:
The WAGO Edge Controller is a flexible and open control platform for many embedded and industrial applications. It provides an excellent vantage point to run the Agilicus Connector.
WAGO Edge Controller
The WAGO Edge Controller is a flexible and open control platform for many embedded and industrial applications. It provides an excellent vantage point to run the Agilicus Connector.
The below instructions were tested on firmware 04.04.03(26) on the following devices:
WAGO Compact Controller CC100 751-9301
WAGO Controller PFC200 750-8212
There are two deployment methods available on the platform:
Native Install. The Agilicus Connector runs as part of the baremetal Host Linux distribution
Docker Install. The WAGO Edge Controller runs a container runtime
Since the Agilicus Connector has no local state other than the encryption keys, there is no specific preference as to which method to choose. If you are using Service Forwarders inbound to the device, you will likely want the native install to enable Machine to Machine communication from a local network.
Preparation
NOTE
❗
Agilicus AnyX uses modern cryptography which requires proper time. Please ensure NTP is configured.
Requirements
In order to deploy the Agilicus Connector successfully the following steps should be undertaken
Verify that sufficient (~200MB) disk space or expanded storage is available (Typical 1.1GB onboard eMMC available)
Enable SSH terminal access via Web UI
Configure and Sync NTP based time
Have WAN access with DNS resolution and network segmentation permitting the Controller to reach the Agilicus AnyX cloud IP address over TLS
Confirm SSH is Enabled:
Confirm that your Controller has access to a local or remote NTP Server in order to maintain accurate time
Option 1. Native Install
The WAGO Edge Controller natively supports the Agilicus Connector. Install the connector as usual, selecting ‘Linux’, and paste the given command into an administrative (root) shell via SSH.
The results will look as below:
INFO[2024-07-25T00:52:33+02:00] Starting connector - version v0.264.16
INFO[2024-07-25T00:52:36+02:00] Check if the agilicus connector is already running as a service. If so stop it
INFO[2024-07-25T00:52:37+02:00] Create file /usr/bin/agilicus-agent-wrapper.sh
INFO[2024-07-25T00:52:37+02:00] Create file /etc/init.d/agilicus-agent
INFO[2024-07-25T00:52:37+02:00] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x <nil>}
INFO[2024-07-25T00:52:37+02:00] Will install to /agilicus-agent-bb.sh -> {/etc/init.d/agilicus-agent -r-xr-xr-x <nil>}
INFO[2024-07-25T00:52:37+02:00] Will install to /agilicus-agent-wrapper-bb.sh -> {/usr/bin/agilicus-wrap -r-xr-xr-x <nil>}
INFO[2024-07-25T00:52:37+02:00] Create a directory at /opt/agilicus/agent/tufmetadata/latest
INFO[2024-07-25T00:53:29+02:00] Create a user and group named Agilicus to run the agilicus-agent service
INFO[2024-07-25T00:53:29+02:00] Copy executable to /opt/agilicus/agent
INFO[2024-07-25T00:53:29+02:00] Set permissions to Agilicus on /opt/agilicus/agent
INFO[2024-07-25T00:53:29+02:00] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent-arm
INFO[2024-07-25T00:53:30+02:00] creating connector instance
INFO[2024-07-25T00:53:31+02:00] Join a connector cluster
INFO[2024-07-25T00:53:31+02:00] Start agilicus-agent service
INFO[2024-07-25T00:53:31+02:00]
INFO[2024-07-25T00:53:31+02:00] Installation Complete
INFO[2024-07-25T00:53:31+02:00]
You can verify the Agilicus Connector instance status in the Connector Overview interface.
Option 2. Docker Install
NOTE
❗
Currently the docker installation support is restricted to 64bit ARMv8 architecture. Support for the 32bit ARMv7 is pending, we recommend Option 1 for these models. Contact us if you are unsure which architecture your controller uses.
Additional Requirements
As a primer, make sure to consult the WAGO documentation for the latest supported hardware and configurations of Docker.
If using Docker, make sure you understand the requirements of installing and running Docker service on the controllers with the WAGO Quickstart Guide on Docker available here:
Verify that the WAGO Controller model supports Docker
Deploy and Enable Docker via Web UI
Confirm Docker is enabled on the device by logging into the Web Interface:
SSH to the Controller with the admin credentials and elevate your session to root privileges:
Verify that docker is installed:
Create and Deploy AnyX Connector
Navigate to your Agilicus AnyX Admin page for your organisation and create a new connector instance under Resources -> Connectors -> New
Once created, proceed with Installation and select the Docker tab in the installation menu:
Copy the text block by clicking on the blue “Copy” icon.
Paste the text block in your Controller SSH Session:
Verify that docker is now running an ‘agilicus-connector’ container
Verify in the Agilicus AnyX admin interface that the connector instance is up and communicating with the cloud platform. The Instance dialog should display the WAGO controller hostname and a status of GOOD:
Troubleshooting
If the docker installation fails or the container fails to start, running docker logs will provide a lengthy and verbose output of the installation and initialisation process of the container.
The NanoPI R5S has 2 x Gigabit Ethernet, 1GiB of RAM, and 32GB of eMMC storage. With its large passive heatsink it is an ideal platform to use as a small router. It also makes an ideal platform to run the Agilicus Connector.
The NanoPi R2S will run several operating systems (Ubuntu, Armbian, OpenWRT). In this document we discuss using it with OpenWRT.
Installing OpenWRT
As received, the NanoPi R2S will (usually) be running FriendlyWRT. You may feel free to use this, however it has some security flaws. Agilicus recommends using the native OpenWRT build. You may build it yourself, or obtain from the OpenWRT Project.
Connect your laptop to the LAN ports (furthest to the USB-C power connector).
Select ”Choose File’ and the file you just downloaded
Select ‘Upload and Write’
Wait approximately 90 to 120 seconds
At this stage you are running the Agilicus-supplied OpenWRT image.
Agilicus Connector Install
Using the Agilicus administrative portal, create a new connector. Use the ‘Linux’ instructions, copy.
In the OpenWRT admin interface (http://192.168.2.1/), select ‘Services/Terminal’. Sign in as root and the password you selected. Paste (shift-insert).
At this time the connector should be installed and you may close the terminal.
You may wish to enable access to this router via the Agilicus AnyX platform (notably SSH and Admin web interface).
NOTE: DHCP Server Enable
Depending on your use, you may wish to have a DHCP server on the LAN ports, you can enable this under ‘Network/Interfaces/LAN’. You may also configure your desired IP range here.
❗
It is appropriate to have a DHCP server on these LAN ports if this is an isolated network. If you are connecting to a larger network with an existing DHCP server, you probably wish to instead change the protocol on the LAN ports to DHCP Client.
NOTE: Time Sync (NTP)
Modern cryptography requires clock sync and accuracy on all devices. Typically this is performed via Network Time Protocol, however, in some environments this is blocked (e.g. HTTPS-only outbound).
If your clock is not sync’d (see System/Time Synchronisation menu), you might be able to use a local NTP server. If not, you can enable an HTTPS-based sync as below:
service htpdate enable
service htpdate start
This is going to use the Agilicus API to provide an HTTP-based (over HTTPS port 443) time service. Configuration can be observed in /etc/config/htpdate:
Once you have installed the Agilicus Connector, we recommend disabling the web terminal. On ‘Services/Termina’, select the config tab and remove the check-box beside ‘Enable’.
You may re-enable the web terminal later if you need it. However, we recommend using SSH instead for future command-line access.
The web terminal operates on a secondary TCP port (7681) and is not needed for normal operation.
SSH Setup
Agilicus recommends disabling password access to SSH in favour of SSH Keys.
On System/Administration, the SSH Access tab, uncheck ‘Password authentication’ and uncheck ‘Allow root logins with password’.
The rationale here is that password stuffing and guessing is a thing. Eventually someone will guess your l33t-hax0r password. Removing any ability to use passwords reduces the risk. In some controls environments any passwords can be disallowed.
Once you have disabled password access, we recommend adding a SSH Key. Agilicus recommends using ed25519 SSH keys since they are smaller and more secure. Add your public key to the router here and place the private key (with passphrase!) in your SSH Agent on your desktop.
SSH keys are not only more secure, but also more convenient.
One downside to note: the Agilicus web interface for SSH is not currently compatible with SSH keys. If you wish to have SSH access to this device via the Agilicus Profile web interface, keep password on.
Firewall
At this stage, configure the firewall and NAT settings to suit on each of the interfaces. If the Agilicus Connector is providing Service Forwarder services, remember to open this ports on the router too.
We can check which ports are listening by running netstat -nlpt as below. Things with 0.0.0.0:PORT are available from outside the device. Things listening on 127.0.0.1, fe80::, ::1, etc, are locally bound only. In the example below, ‘uhttpd’ (the admin web interface), ‘dropbear’ (SSH) and ‘ttyd’ (the web terminal) are the only things listening.
This walk through shows an example of how, once the connector is installed (as per above), configuration of an HTTP and SSH interface to this local device. Once these are configured you could use the firewall to disable all external access. The high level steps are:
Create Connector (Agilicus Admin)
Install Connector (NanoPi Web Terminal)
Create SSH Resource (Agilicus Admin)
Create Web Resource (Agilicus Admin)
Assign Web Resource Permission (Agilicus Admin)
SSH to NanoPi from Agilicus Profile (Agilicus Profile)
Open Web Interface to NanoPi (Agilicus Profile or direct)
OK, let’s get started. This will take approximately 5 minutes.
Install the Agilicus connector directly on the PLC for highest security and simplest deployment.
Phoenix Contact PLCnext AXC F x152
The Phoenix Contact PLCnext AXC F 2152 (and 1152 and 3152) provide an ideal platform to run the Agilicus Connector. It has enough storage, CPU, its in the right vantage point in the network. Once installed, you can use it for programming, or for operations.
The installation is the same as all other Linux platforms.
First, we SSH into the PLC. This is typically ssh admin@plc with username ‘admin’ and password ‘plcnext’.
Next we must enable the root password if we have not already:
sudo passwd root
(admin password)
(new root password)
(new root password)
At this stage we can become root:
su - root
(new root password)
#
At this stage, go to the Agilicus admin interface and create a new connector. Select the ‘Linux’ install and paste into the ssh window above:
As a reminder, this command line times out in 10 minutes, if you have note done those steps above first, just regenerate the command-line
The correct output will look something like below. You may need to have DNS enabled and NTP (for time).
NOTE: Enable NTP via you may wish to set the timezone to UTC first:
ln -sf /usr/share/zoneinfo/UTC /etc/localtime
root@sim-axcf2152:~# which curl && (curl -sSL agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh) || (wget -O - agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh); sh /tmp/i.sh -c XXXX -s -d /usr/bin/curl OS: , Machine: , END: Fetching https://www.agilicus.com/www/releases/secure-agent/stable/agilicus-agent-arm into /tmp/agilicus-agent-arm -rwxr-xr-x 1 root root 49872896 May 28 19:04 /tmp/agilicus-agent-arm
'[' challenge = explicit ']'
/tmp/agilicus-agent-arm client --install --challenge-id XXX --challenge-code XXX --debug INFO[2024-05-28T19:04:28Z] Starting connector - version v0.261.1
INFO[2024-05-28T19:04:31Z] Create file /etc/init.d/agilicus-agent
nEBU[2024-05-28T19:04:32Z] isSystemd: false
INFO[2024-05-28T19:04:32Z] Will install to /agilicus-agent-sysvinit.sh -> {/etc/init.d/agilicus-agent -r-xr-xr-x }
INFO[2024-05-28T19:04:32Z] Will install to /agilicus-agent-wrapper-sysv.sh -> {/usr/bin/agilicus-wrap -r-xr-xr-x }
INFO[2024-05-28T19:04:32Z] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x }
INFO[2024-05-28T19:04:33Z] Create a directory at /opt/agilicus/agent/tufmetadata/latest
INFO[2024-05-28T19:04:33Z] Create a directory at /opt/agilicus/agent/tufmetadata/stable
INFO[2024-05-28T19:04:51Z] Create a user and group named Agilicus to run the agilicus-agent service
INFO[2024-05-28T19:04:51Z] Copy executable to /opt/agilicus/agent
INFO[2024-05-28T19:04:51Z] Set permissions to Agilicus on /opt/agilicus/agent
INFO[2024-05-28T19:04:51Z] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent-arm
INFO[2024-05-28T19:04:53Z] creating connector instance
INFO[2024-05-28T19:04:53Z] Join a connector cluster
INFO[2024-05-28T19:04:53Z] Start agilicus-agent service
INFO[2024-05-28T19:04:54Z] INFO[2024-05-28T19:04:54Z] Installation Complete INFO[2024-05-28T19:04:54Z]
Please check the online status in the web interface under Resources/Connectors/Overview' Please check the online status in the web interface under Resources/Connectors/Overview
If you have questions, or errors were shown above, please email support@agilicus.com.' If you have questions, or errors were shown above, please email support@agilicus.com.
At this stage we can check its running. In the Agilicus admin interface, the connector line will go ‘GREEN’ (Good) within a minute or so. We can also test on the PLC:
# ps -ef|grep agilicus
that line should show the service running.
The Agilicus Connector also works on the PLCnext simulator.
Many desktop, server, embedded systems support container runtimes. The most widely used syntax and name recognition, Docker, gives a convenient simple command-line interface.
The Agilicus connector can natively run inside a connector. This provides a convenient method of experimenting (or deploying) with low cost, high simplicity.
For people wishing to run the connector on an Apple MAC, this is the best approach.
Create the connector as normal, select ‘Docker’ from the install type tab at the top and paste into the machine running the container runtime.
By default this command creates a volume ‘agilicus_cfg’ and uses ‘host’ networking.
Two ephemeral security identifiers (CHALLENGE_ID, CHALLENGE_CODE) are provided, these are claimed once and then discarded. You must paste the command line within 10-minutes of generating it.
Once complete, you will see the connector come online as normal.
Note: for a ‘share’, you may need to mount a volume into the container (e.g. -v /Documents:/Documents), otherwise only the internal filesystem of the container is available.
Installing an Agilicus Connector creates a new type of user, a service account.
Connector Install: Sign-In
Installing an Agilicus Connector creates a new type of user, a service account. This service account is created automatically for you, using your (the administrators) privilege as a bootstrap. This service account has a restricted set of abilities. You may see (and delete after deleting a connector) in the admin front end under ‘Access/Service Accounts’.
Once this service account is created, the Connector will use this identity without further user intervention.
In order to create the service account, and get its credentials, the install process needs you to authorise it. To do this, 2 methods exist (both yield identical results):
Open a new browser, request you to sign in. This in turn uses a ‘callback’ URI that points to the host you are trying to install the connector on. Your browser, upon finishing the sign-in flow, will do a redirect to http://localhost:<someport>, passing the access token forward.
Copy a URL you are given, paste it into your browser, this will give you a code, paste that back into the location you started the install from.
Typically if you are using a graphical desktop operating system, and signed into it as yourself, you would use method #1. If you are remotely accessing a system, or it is a headless embedded device, you would use method #2.
In some cases both methods are available, in which case the first one to answer will be used.
Note: The Connector installation process should be run with Administrative (e.g. Root, LocalAdmin privilege). If you do not, it will attempt to elevate for you (as you can see in the below example).
A console log of the initial install process is shown below. In this example, you would have seen your browser open automatically with a sign-in screen as above right. If you sign in this way, the installation will complete. Instead, you may copy the URL given (https://auth.__MYDOMAIN__/auth?client_id=agilicus-builtin-agent-connector…) into the browser on your desktop. You will then see a screen as shown. Copy the token (osfygqo2j…) and paste it in where it says “Enter verification code:“, and the installation will complete.
Whichever method you use, you will achieve the same result, and the Agilicus Connector will need no further intervention.
INFO[2022-05-29T11:45:38-04:00] Starting client - version v0.119.0-5
INFO[2022-05-29T11:45:38-04:00] User is not admin, attempting to elevate. If this fails, re-run as admin/root with same arguments.
re-run [/usr/bin/sudo /bin/sh -c "/home/don/src-ag/platform/secure-exposed-agent/bin/agilicus-agent" "client" "--install" "--agent-id" "GLrmn8mKJ6W45c8Bo3ABCK" "--oidc-issuer" "https://auth.dbt.agilicus.cloud"]
INFO[2022-05-29T11:45:38-04:00] Starting client - version v0.119.0-5
You have **2** methods to provide your authentication. Use the most convenient.
1. You may see a browser open. If you sign in to it, this flow will complete
automatically, and ignore the url below/paste.
2. You will see a URL appear here. Cut and paste that into a browser you are
signed-into. It will then give you a code to paste here.
Typically #1 is used if you are signed into this machine directly, and #2 for
ssh or remote desktop or embedded devices.
If a browser did not open automatically, please open this link in
your desktop browser to retrieve the authentication code, and paste below:
https://auth.__MYDOMAIN__/auth?client_id=agilicus-builtin-agent-connector&...
Enter verification code:
You can add one (or more) Azure Active Directory systems as Upstream Identity Providers. Doing this will allow your team to sign in with their Active Directory username/password. If you work with more than one corporation, you may add multiple Upstream Identity Providers.
Agilicus Front-End Create Upstream Issuer
The setup is very simple and takes less than 2 minutes to acomplish. There is a ‘stepper’ that walks you through the tasks.
First, open the admin user interface (https://admin.__MYDOMAIN__). Login as your (initial) administrative user. Nagivate to ‘Organisation’/’Authentication Issuer’. From here you may select ‘Add Provider’, adding a new identity provider.
At this stage, you will enter a Stepper which will walk you through the steps graphically. First select Azure Active Directory as the type:
Azure Application Registration
The Stepper will show screen shots of how to configure Azure, they are also here. First, select ‘Azure Active Directory’ in your Azure console:
Now create a new Application. This will be for all logins to the Agilicus platform.
Select a name. This will be shown to the user on the Login select page, we recommend making it related to your organisation. E.g. “My Company Active Directory”. In the Application stepper you are given a “Redirect URI”, paste it here.
You will now be given 3 pieces of information. A ‘Display Name’, an ‘Application (Client) ID’, and a ‘Directory (Tenant) ID’. Enter these in the appropriate spots in the Stepper.
Here you can see where this information is placed in the Agilicus Admin Stepper, from the Azure screen we have:
On the Agilicus Stepper we have:
Now we create a ‘Client Secret’. This is a shared secret between the two systems. Create this in the Azure Portal:
As a description we recommend using the same name as for the Application. If you select an Expiry (e.g. something other than Never) you must remember to update the Admin user interface at a later date.
In the Admin stepper paste the secret you received. You are now done!
NOTE: Multiple Azure tenant with same email address
If your Active Directory login name is the same as the email address you provided through your Apple ID / Google ID / LinkedIn ID, you may have an issue. Please contact Agilicus (info @ agilicus.com) and we can join these accounts for you. E.g. if your Apple ID email is foo@mycompany, and your Active DIrectory is foo@mycompany, let us know and we can join these two together.
Azure Claims
This section is optional. If you wish to synchronise groups, or use UPN as welll as email, you should configure a set of additional claims. Agilicus recommends:
email — this gives access to the user ’email’ which may differ from the UPN
onprem_sid — this is used if you will do passthrough authentication (e.g. using SAML with Citrix)
upn — this gives access to the user principal name
sid — this can be used to allow per session sign-out
preferred_username — this controls how the user might interact with the system as a name
(Optional) Azure Groups
You may wish to directly import your Azure groups into Agilicus for role-based access control. To do so, enable the groups claim in Azure.
On your Azure Upstream Identity Issuer, enable the group mapping as below. You may need to use the GUUID and map to names.
Testing and Application Consent
At this stage you may try a login. You can keep the Admin portal logged in and use https://profile.MYDOMAIN to try. You should see a new Sign-In option, which is named as you have above.
The first (and only) time you select this new Sign in option, you will be presented with a question as to whether you consent to the information shared. The Information shared is your Name, and your Email. No permission is being granted to access any Azure or Office 365 information.
You are now complete. All users can now Sign in with their corporate login, no additional passwords to remember.
Advanced Grant Workflow
NOTE: If you use advanced grant workflow If you use a per-application or per-user grant workflow, we recommend granting access to this new ‘App Registration’ under the ‘Enterprise Applications’ section of Azure Active Directory. You may navigate to the specific application (as below), and then ‘Permissions’, and then ‘Grant admin consent’. If you do not do this, you may find that users who use the ‘offline_access’ workflow (also known as the refresh token) may be confused by constantly being requested to grant access
amr (if present, used if Active Directory Multi-Factor-Authentication is used)
To add this identity provider, select Authentication Issuer, select “ADD PROVIDER” under OpenID Connect Upstream Providers. From here we have a set of fields:
Name: This will be a phrase your staff will see when logging in.
Issuer: This is the URI of your Active Directory or ADFS endpoint, often https://my-org.ca/adfs. To find your issuer under Azure Active Directory, see appendix.
Icon: This will be referenced in your CSS if you choose to theme, named dex-btn-icon–NAME.
Client id: This will be generated by your ‘Create OpenID Application” interface in Active Directory.
Secret: This will be generated when you create the application in Active Directory.
Issuer External Host: leave this blank
Username Key: typically UPN
Email Key: typically UPN.
User ID Key: typically sid
Verifies Email: typically checked (this removes the request scoped `email_verified`)
In order to establish a relying party trust between Agilicus and your Active Directory, identifying information and a shared secret must be established between them. This is done by creating an OpenID Connect configuration in ADFS known as an Application Group, which consists of a Server application and a Web API. Both of these components together specify the Agilicus redirect URIs that need to be invoked during authorization code flows as well as permissions, scopes, claims, and a client identifier and shared secret that Agilicus uses to communicate with your ADFS server.
Details
The steps to create an Application Group in ADFS are described below. These instructions are for Active Directory Federation Services for Windows Server 2016.
Open the AD FS Management console (Server Manager → Tools → AD FS Management)
Right-click Application Groups and select Add Application Group; alternatively, select Application Groups and select Add Application Group from the list of available actions under the Action menu bar or the Actions pane
Enter a Name and optionally a Description for the new application group
In the Template list, under Client-Server applications, select the Server application accessing a web API type. Click Next
Make note of the Client Identifier. This ID will become the “Client ID” in the Agilicus Administrative Portal.
Enter the Redirect URI that was given in the Agilicus Administrative Portal.
Check the option to Generate a shared secret. This will be used in the Agilicus Administrative Portal.
Add an Identifier value that is equal to the Client Identifier generated above. Click Next
Under Choose an access control policy, select Permit everyone. Click Next
On the Configure Application Permissions page, under Permitted scopes, make sure OpenID, email, profile, amr (if present), and allatclaims are checked. Click Next
Review the summary and click Next to create the Application Group
Click Close to complete the wizard
The Application Group is now created and should be listed in the Application Groups pane. In order to populate the user tokens with the appropriate information during OAuth2 exchanges, some additional configuration steps are needed to transform Active Directory data into token claims.
Right-click the newly created Application Group and select Properties; alternatively, select the newly created Application Group and select Properties from the list of available actions under the Action menu bar or the Actions pane
Select the Web API entry under Applications and click Edit
Go to the Issuance Transform Rules tab and add each of the following three rules
Group Rule
Click Add Rule
Under Claim rule template, select the option Send LDAP Attributes as Claims and click Next
Enter a name for the claim rule such as AD Group With Qualified Long Name
Under Attribute store, select Active Directory
In the mapping table on the first row, under the LDAP Attribute column, select the Token-Groups – Qualified by Long Domain Name option
In the mapping table on the same row, under the Outgoing Claim Type column, select the Group option and click Finish
Subject Rule
Click Add Rule
Under Claim rule template, select the option Send LDAP Attributes as Claims and click Next
Enter a name for the claim rule such as Subject Claim
Under Attribute store, select Active Directory
In the mapping table on the first row, under the LDAP Attribute column, select the User-Principal-Name option
In the mapping table on the same row, under the Outgoing Claim Type column, select the Name ID option and click Finish
UPN Rule
Click Add Rule
Under Claim rule template, select the option Send LDAP Attributes as Claims and click Next
Enter a name for the claim rule such as User Principal Name
Under Attribute store, select Active Directory
In the mapping table on the first row, under the LDAP Attribute column, select the User-Principal-Name option
In the mapping table on the same row, under the Outgoing Claim Type column, select the UPN option and click Finish
Click OK to save and close the updated Web API properties
Click OK again to close the Application Group properties
Appendix: Azure Active Directory
Creating your Client ID and Secret
Adding the Optional Claims for sid
Finding your Issuer
Your Issuer is found by looking at the WS-Federation sign-on endpoint, changing ‘login.microsoftonline.com’ to ‘sts.windows.net’, and removing the wsfed from the end. It will look like ‘https://sts.windows.net/XXXXX-XXXX-XXXX/’.
Install the Agilicus Connector on Microsoft Windows.
Versions Supported
The Agilicus Connector will run on any version of Windows XP or later. However, prior to Windows 10, the ‘curl’ command, used as part of the install, was not present, and you may need to manually install it.
If your Windows version is old or unpatched, it may be missing the Let’s Encrypt Intermediate certificate, see https://letsencrypt.org/certificates/
Installation
Windows 10 and later come with a command pre-installed called ‘curl‘ that allows for 1-click automatic install.
To create and install a connector, first, on your desktop PC (where you have the ADMIN url open), go to ‘resources/connectors/new’. Give your connector a name that means something to you (often the name of the machine you will install it on, or the site that it connects).
Click ‘create’. You will now be given the option to ‘Install Connector’. This brings up a dialog box as below. Select ‘WIndows – CMD’.
There is only 1 question on this dialog “This is a subsequent connector (create a cluster)”. Select this if you have more than one computer running the same connector instance in a high-availability cluster.
Select the ‘COPY’ button. This will place the command line into your clipboard.
At this stage we must switch to the computer where you will run the connector. It might be this same machine, it might be another accessible via Remote Desktop or VNC.
On the target computer, open a ‘Command Prompt’ as administrator:
Go to ‘Start’
Type ‘cmd’
Right click ‘Command Prompt’
Select ‘Run as administrator’
This will open a ‘cmd’ shell.
We can quickly test that ‘curl’ is installed by running ‘curl ifconfig.me’. This will print our current public IP address. Curl is pre-installed as part of Windows as for Windows 10 and Windows 2016. If you do not have curl installed, you may try the PowerShell instructions from the dialog, or, install curl manually.
We can now paste the command we obtained from the ADMIN UI.
Paste the command as below. The correct output will be similar to what is shown, ending in ‘Installation Complete’
It is possible you will run into some errors, the most common relate to:
Time setup. Your computer should be time-synced (using NTP). This is important for proper cryptography.
Firewall. Your computer may block outbound access to https://www.agilicus.com
Intermediate Certificate. If your computer has not run Windows update since 2021, it may be missing the Let’s Encrypt intermediate certificate.
At this stage you are complete and may close the command window.
In the ADMIN UI you can check the status of your connector, it should move to ‘GREEN/GOOD’ (you may need to refresh this screen).
General Notes
NOTE: Timeout
For security reasons, the command you will paste has a time limit before it expires of 10 minutes. If it expires, simply generate a new one in the ADMIN interface and paste it. In this case, you will see an error like: “Installation failed due to the following error: could not claim challenge code: 400 Bad Request. Do not run the command again; generate a new one. See https://www.agilicus.com/anyx-guide/agilicus-connector/#h-installation“
NOTE: WebClient Service
You may need to manually enable the Windows WebClient service if you will use the connector to mount a remote WebDav Share to this machine. Normally this is set to run on demand, but in some environments it may be disabled.
NOTE: Windows Failover Clustering High Availability
Some installations have observed, using the PowerShell installation instructions, a false-positive detection for Trojan:Script/Sabsik.TE.B!ml. This has been submitted to Microsoft for re-evaluation, but they have been unable to reproduce. If this occurs, you can override this detection for this specific binary.
NOTE: 2012 PowerShell: Could not create SSL/TLS secure channel
Older versions of Windows may be missing the R3 root certificates (see Microsoft note). This can prevent usage of modern cryptographic https sites. Let’s Encrypt has more information, including a diagram of the full chain of trust.
You may find you need to run Windows Update, or, manually remove the old R3 intermediate and add the new one from Let’s Encrypt.
NOTE: CHANGE RUNNING USER/PERMISSIONS
In some circumstances you may change the user the connectr runs as (the windows service user) after initial installation. If you do this, it is important to change ownership of all of the files in C:\Program Files\Agilicus to make the user.
Diagnostic Logs – Windows Eventvwr
The Agilicus Connector sends diagnostic and access logs to Windows Eventvwr by default. To view these logs on a standalone-basis, you might consider creating a custom view.
Open Microsoft Windows eventwr (from Start menu, type ‘eventvwr’)
Right click in custom views
Create Custom View
Select ‘By Source’, and ‘agilicus-connector‘. Enable each Event Level of interest (e.g. Critical, Warning)
Save as ‘Agilicus Connector Logs’
Once this is complete, you will see a new custom view as below. You may then browse the logs or e.g. right-click and save a text file for forwarding.
File Permissions Correction
If your connector shows a warn status, it could mean that the file does not have sufficient permission for Agilicus’ connector. To give access files/folders the correct permissions,
Automatic Permission Fix Instructions
Download and run this script (in Powershell) as access.ps1, or, follow the manual instructions below.
The Agilicus Connector can install on an embedded router product such as OpenWRT. The devices (usually) have either an MIPS or an Arm processor. The instructions are the same for each, but the link is different. The instructions below are for a OpenWRT Router but will be similar on other devices. Select the proper processor (ARM/MIPSBE/MIPSLE) according to your hardware.
See NanoPi R5S for a specific device and instructions.
RESOURCE REQUIREMENTS
Your OpenWRT device will need at least 128MiB of flash memory, and at least 256MiB of DRAM. Not all devices do, we recommend checking first.
No changes are needed to your firewall. No VPN is needed. You can administer users via their Active Directory or Apple, Google, Linkedin accounts.
The high level steps are:
Enable SSH on your Router (or, use the web-based terminal from LUCI)
Create a Connector (Agilicus admin interface)
SSH to the Router
Paste the given command line
after this, the Agilicus Connector will be entirely automatic, and controlled via the Agilicus admin interface. You may uninstall it at any time with
agilicus-agent client --uninstall
Create Connector
First we will create a Connector. This logical endpoint allows reverse inbound connectors to safely occur.
We give the connector a name. This is used for statistics and diagnostics purposes. Select the Linux instructions, and select Copy.
Now, SSH to your Router and paste the given command line:
# which curl && (curl -sSL agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh) || (wget -O - agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh); sh /tmp/i.sh -c JhtPxw9GVXXXXXX -s yw6XXXX
/bin/curl
OS: <Linux>, Machine: <aarch64>, END: <le>
Fetching https://www.agilicus.com/www/releases/secure-agent/stable/agilicus-agent-arm64 into /tmp/agilicus-agent-arm64
-rwxr-xr-x 1 root root 46268416 Jul 8 11:37 /tmp/agilicus-agent-arm64
+ /tmp/agilicus-agent-arm64 client --install --challenge-id JhtPxw9GXXXXX --challenge-code ywXXXX
INFO[2023-07-08T11:37:53-05:00] Starting connector - version v0.211.3
INFO[2023-07-08T11:38:08-05:00] Check if the agilicus connector is already running as a service. If so stop it
INFO[2023-07-08T11:38:08-05:00] Create file /usr/bin/agilicus-agent-wrapper.sh
INFO[2023-07-08T11:38:08-05:00] Create file /etc/systemd/system/agilicus-agent.service
INFO[2023-07-08T11:38:08-05:00] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x <nil>}
INFO[2023-07-08T11:38:08-05:00] Will install to /agilicus-agent.service -> {/etc/systemd/system/agilicus-agent.service -r--r--r-- 0xd97540}
INFO[2023-07-08T11:38:08-05:00] Create a directory at /opt/agilicus/agent/tufmetadata/latest
INFO[2023-07-08T11:38:08-05:00] Create a directory at /opt/agilicus/agent/tufmetadata/stable
INFO[2023-07-08T11:38:18-05:00] Create a user and group named Agilicus to run the agilicus-agent service
INFO[2023-07-08T11:38:18-05:00] Copy executable to /opt/agilicus/agent
INFO[2023-07-08T11:38:18-05:00] Set permissions to Agilicus on /opt/agilicus/agent
INFO[2023-07-08T11:38:18-05:00] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent-arm64
INFO[2023-07-08T11:38:18-05:00] creating connector instance
INFO[2023-07-08T11:38:19-05:00] Join a connector cluster
INFO[2023-07-08T11:38:19-05:00] Start agilicus-agent service
INFO[2023-07-08T11:38:21-05:00]
INFO[2023-07-08T11:38:21-05:00] Installation Complete
INFO[2023-07-08T11:38:21-05:00]
At this stage you are complete, you will see the Connector go online in the web interface in a minute or so.
The MikroTik RB5009UG+S+IN is a small-form factor router. it is a good vantage point to run the Agilicus Connector. NOTE: this is an ARM-based device, not X86.
Other MikroTik devices may work as well, MikroTik has a broad family of devices. In order to be appropriate for the Agilicus Connector, they need to support:
container package
ARM or x86 processor
100MiB or more of storage space
256MiB or more of memory
The below instructions were tested on the RB5009UG+S+IN with v7.8 and v7.9RC, specifically:
The below instructions were performed using the MikroTik CLI. They may also be performed via the Web GUI or the WinBox.
Detailed Installation Steps
Note: the first steps assume you have not enabled container-package and networking on the RouterOS device. If you have, skip ahead to the Setup config-volume step.
If you are using the Web or WinBox configuration, you will see a package installed as below:
Confirm the container command exists:
/container/print count-only
0
Step 2: Setup container networking
Now we will enable a virtual Ethernet bridge (veth1) and assign it to the container use. If you wish, you may use direct interfaces without NAT by assigning a second IP, or, by assigning physical ports. Later when the Agilicus connector is installed, it will need to be able to resolve DNS and perform outbound connectivity to api.agilicus.com
Note: the Mikrotik is very fussy about mounts. It must create them itself (rather than being created by e.g. sftp). It will create a magic file called ‘.type’ in the mount dir, do not delete or modify this file.
Note: the cr.agilicus.com/pub/images/agilicus-agent/client:stable image is multi-arch (AMD64, ARM64). If your MikroTik is not one of these, it will not function. If your MikroTik does not support multi-arch containers (e.g. prior to v7.9), you may substitute one of these two tag names:
Modify it to be something like below and then run it. There is no need to be admin/root, this will not install any software, merely create the configuration files. We are just changing the beginning of the command line to be “agilicus-agent client –remote-install”, leave the –oidc-issuer onwards unchanged.
Note: you will need a local copy of the software on your desktop to create the config file. It does not need to be installed. If you do not have this, you can download the Linux Binary, or the Windows Binary.
A browser will open to create the Service Account and credentials. The output will look like:
INFO[2023-03-17T20:14:28-04:00] Starting client - version v0.172.3
You have **2** methods to provide your authentication. Use the most convenient.
1. You may see a browser open. If you sign in to it, this flow will complete
automatically, and ignore the url below/paste.
2. You will see a URL appear here. Cut and paste that into a browser you are
signed-into. It will then give you a code to paste here.
Typically #1 is used if you are signed into this machine directly, and #2 for
ssh or remote desktop or embedded devices.
If a browser did not open automatically, please open this link in
your desktop browser to retrieve the authentication code, and paste below:
https://auth.MYDOMAIN/auth?client_id=XXXXX
Enter verification code:
INFO[2023-03-17T20:14:35-04:00] Will install into Will install into directory /tmp/remote-4139368021
INFO[2023-04-23T12:30:33-04:00] Download root key file
INFO[2023-04-23T12:30:33-04:00] Fetch agent configuration
INFO[2023-04-23T12:30:33-04:00] Write agent configuration file in temp directory
INFO[2023-04-23T12:30:36-04:00] Create connector instance
INFO[2023-04-23T12:30:36-04:00] creating connector instance
INFO[2023-04-23T12:30:37-04:00] Join a connector cluster
INFO[2023-04-23T12:30:37-04:00] Remote installation config created successfully
INFO[2023-04-23T12:30:37-04:00] Copy <<agent.conf.enc.yaml public_key.json pubring.gpg root.json secring.gpg>> to remote
At this stage, there should be 4 files in a directory like /tmp/remote-4139368021:
Note: its important to let the Mikrotik router create the config directory by itself. It creates a ‘magic’ file called .type inside the dir. Without this step, the config directory will be read-only within the container.
/container/start 0
After this, check that it is running (and repeat until it is running)
Accurate globally synced time is critical to the proper operation of many modern cryptographic tools. It affects certificte allocation/revocation, sign-in audit logs, etc.
The Agilicus system requires that your individual endpoints (browsers, Agent Connectors) have proper network time at all times. Typically this means enabling NTP.
During sign-in or installation you may see a warning indicating that your time is not accurate. Enable your time-sync service for your operating system to continue.
Linux
On systemd-derived Linux distributions, NTP is provided y the time-sync target. This in turn might use ntpd or chrony:
systemctl status time-sync.target
● time-sync.target - System Time Synchronized
Loaded: loaded (/lib/systemd/system/time-sync.target; static)
Active: active since Tue 2022-04-12 16:01:41 EDT; 1 month 19 days ago
Docs: man:systemd.special(7)
You can check that your NTP is synced using one of these commands:
chronyc tracking
Reference ID : CF22301F (backoffice-1.incentre.net)
Stratum : 4
Ref time (UTC) : Wed Jun 01 14:11:18 2022
System time : 0.000066093 seconds fast of NTP time
Last offset : -0.000524711 seconds
RMS offset : 0.000274038 seconds
Frequency : 18.516 ppm slow
Residual freq : -0.004 ppm
Skew : 0.036 ppm
Root delay : 0.066371940 seconds
Root dispersion : 0.002734751 seconds
Update interval : 1035.0 seconds
Leap status : Normal
$ ntpq -p
remote refid st t when poll reach delay offset jitter
==============================================================================
+muug.ca 132.163.97.1 2 u 377 1024 377 40.083 -2.270 3.861
-nowhere.zeromea 10.0.11.202 2 u 1066 1024 377 20.776 -13.097 11.333
*zero.gotroot.ca 30.114.5.31 2 u 979 1024 377 68.439 -3.066 2.814
+time.cloudflare 10.106.8.139 3 u 555 1024 377 36.048 -2.940 2.268
Windows
Microsoft Windows uses the Windows Time Service, which in turn uses the Network Time Protocol (NTP) on UDP port 123.
Embedded devices running e.g. Ubiquity EdgeMax, pfSense, OpenWRT, etc, all have their own NTP-enable. See their documentation or web/cli interface for more information.
Various errors can occur during the user sign-in process. These range from a lack of authorisation, improper identity, missing or incorrect multi-factor authentication, etc. The user will receive a notification in the browser for each, and those message in turn will point to the various specific messages here.
User user@example.com is unauthorized
Message: User user@example.com is unauthorized. You do not have all the required roles to use this application. Action: – Check with your administrator to request access. – Please do not bookmark or reload. Correlation Id: horhpxP4Wpx8ZmhMwFppRm Request Id: dWxUpfg9pHwacBUrpBvwbd Message Id: id-insufficient-roles Timestamp: 2022-12-09 20:51:04.562761388 +0000 UTC
A problem occurred during sign in.
Note this can occur if the user declines the Authentication Consent flow from Microsoft Entra (see https://www.agilicus.com/white-papers/azure-application-consent/)
Login session expired.
Message: Login session expired. Action: – Please retry sign in – If this issue persists please contact your administrator. – Please do not bookmark or reload. Correlation Id: gW2xgGTkDXBgGxkeSfE6iP Request Id: qEr4F4KoS2ja5d6wZWQSo8 Message Id: id-signin-session-expired Timestamp: 2022-12-09 20:51:04.562804481 +0000 UTC
Unable to enroll user in multi-factor authentication
Message: Unable to enroll user in multi-factor authentication. You don’t currently have any of your organisation’s supported multi-factor authentication methods enrolled and your enrollment attempt is outside the enrollment period set by your organisation. Action: – Please contact your system administrator. Correlation Id: ms2ZbTULdw9tLqS8QLTjED Request Id: jEd82e4F3sQEwZErmEFWeH Message Id: id-mfa-enrollment-error Timestamp: 2022-12-09 20:51:04.5628225 +0000 UTC
User does not exist.
Message: User does not exist. Action: – Please do not bookmark or reload. – Please contact your system administrator. Correlation Id: ARGphvHQKqK6nthAcxH56E Request Id: mGYaNtspx9G6pbRTmPf4Ko Message Id: id-no-user-found Timestamp: 2022-12-09 20:51:04.562887174 +0000 UTC
User failed multi-factor authentication challenge
– Please retry sign in. Correlation Id: Zq4t9tQuKqR39ZwQQUaMuE Request Id: Mo7F8HJvPd82HDmfbBKCVh Message Id: id-failed-mfa-challenge Timestamp: 2022-12-09 20:51:04.562908755 +0000 UTC
Logout complete
Message: Logout complete. Your application did not redirect you back to its homepage, or it failed to do so. Action: – Please navigate to it in order to sign in again. Correlation Id: BGbadbNDAEnavjeEEMceqL Request Id: c9GwZgfZWXttpzweVdxvq6 Message Id: id-logout-redirect Timestamp: 2022-12-09 20:51:04.562926844 +0000 UTC
An invalid redirect URI was encountered during sign in.
Message: An invalid redirect URI was encountered during sign in. Action: – Please retry sign in. Correlation Id: Vu2KHEkmreAaDmXS86tz4m Request Id: 4MdWDJfeAuavPTFs5LFpLK Message Id: id-invalid-redirect-uri Timestamp: 2022-12-09 20:51:04.562944933 +0000 UTC
A problem occurred during sign in. Your sign in credentials match multiple identity providers.
Action: – You may have signed into the wrong provider. – If this issue persists please contact your administrator. – Please do not bookmark or reload. Correlation Id: LoNQiSfSkUP5yVaT59qpAY Request Id: rs5giDgcZVjsfmC3DezXxP Message Id: id-multiple-upstream-identities Timestamp: 2022-12-09 20:51:04.562869154 +0000 UTC
Sign in denied.
Action: – Please do not bookmark or reload. – Please contact your system administrator. Correlation Id: Gsy6HMDsQGNUXY9Zzp6yHB Request Id: 9NuHcNsD663wDCsE2QGFrF Message Id: id-signin-denied Timestamp: 2022-12-09 20:51:04.562847224 +0000 UTC
Upstream connection failed
Message: Upstream connection failed
Action: – The upstream host could be down – Please retry; if the error persists contact your IT Administrator Correlation Id: Gsy6HMDsQGNUXY9Zzp6yHB Request Id: 9NuHcNsD663wDCsE2QGFrF Message Id: id-upstream-host-down Timestamp: 2022-12-09 20:51:04.562847224 +0000 UTC
Failed to Authenticate
Message: Failed to initialize authentication
Action: – Please retry. If the error persists contact your IT Administrator Correlation Id: Gsy6HMDsQGNUXY9Zzp6yHB Request Id: 9NuHcNsD663wDCsE2QGFrF Message Id: id-authentication-failure Timestamp: 2024-10-09 11:23:04.782847224 +0000 UTC
The Kubernetes install is intended for advanced usage only. It is for users who are integrating with a larger system. As a pre-requisite, you will need kubectl installed on the machine you will do the installation from.
The steps initially are similar:
Create a new Connector in admin
Select “Install’
Download the binary (using the alternative manual install, see link for all binaries etc)
Select ‘Manual’. Change –install/–kubernetes-install to –kubernetes-install. Adjust other parameters as needed
The Ubiquiti EdgeRouter X (ER-X/ER-X SFP) is a small-form factor router. In addition to performing routing services, it is a good vantage point to run the Agilicus Connector if you already have it.
This is a low-performance device, we do not recommend purchasing new ones.
The Ubiquiti EdgeRouter X (ER-X/ER-X SFP) is a small-form factor router. In addition to performing routing services, it is a good vantage point to run the Agilicus Connector.
(Once you have completed these, you may wish to try accessing the EdgeRouter X web interface via the Agilicus Any-X platform, see example).
DEVICE WARNING
❗
Note: this device is a low-performance device with an older processor and low ram. If you have a need for more than a few services, or ones which need more than ~10Mbps of throughput, we recommend a newer device such as NanoPi, a Raspberry Pi, or a pfSense.
The below instructions were tested on an EdgeRouter X SFP with v2.0.9, specifically:
In the Agilicus Administrative Web interface, you will:
Create Connector
Copy the install command line
Paste this into the ssh interface of the Ubiquiti EdgeRouter X
Step 1: Create Connector
Navigate (in the Agilicus admin web interface) to ‘Resources/Connectors/New’.
Step 2: Copy the install command line
Select “Linux”. Copy the command line to your clipboard. Run on the ssh interface to the ERX.
This command will fetch a script, and then run it with a time-limited challenge.
Note: the command line looks complex since it must run on multiple platforms, some of which have curl, some of which have wget, but it effictively fetchs a single install script and runs it with 2 arguments. You may feel free to fetch the script and inspect it, run it manually.
You should now be complete.
A complete log of a successful install is shown below for reference.
don@machine$ ssh ubnt@172.16.0.13
_____ _
| ____|__| | __ _ ___ (c) 2010-2020
| _| / _ |/ _ |/ _ \ Ubiquiti Networks, Inc.
| |__| (_| | (_| | __/
|_____\__._|\__. |\___| https://www.ubnt.com
|___/
Welcome to EdgeOS
By logging in, accessing, or using the Ubiquiti product, you
acknowledge that you have read and understood the Ubiquiti
License Agreement (available in the Web UI at, by default,
http://192.168.1.1) and agree to be bound by its terms.
ubnt@172.16.0.13's password:
Linux erx 4.14.54-UBNT #1 SMP Tue May 11 13:23:28 UTC 2021 mips
Welcome to EdgeOS
Last login: Sat May 28 18:11:43 2022 from 172.16.0.8
ubnt@erx:~$ sudo su -
root@erx:~# which curl && (curl -sL agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh) || (wget -O - agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh); sh /tmp/i.sh JX2EXXXXXXXXXXXXEU https://auth.MYDOMAIN
/usr/bin/curl
Starting install... <JX2EXXXXXXXXXXXXEU> <https://auth.MYDOMAIN>
OS: <Linux>, Machine: <mips>, END: <le>
INFO[2022-05-28T18:32:33.787560338Z] Starting client - version v0.119.0
INFO[2022-05-28T18:32:34.923316902Z] Logging in...
You may see a browser open, in which case you may sign in automatically.
Failing that, if this machine is headless, or remote, you will see a URL below.
Copy and paste that into a browser you are logged into. You will then see a code,
paste it in below.
Please go to the following link in your browser to retrieve the authentication
code:
https://auth.MYDOMAIN/auth?client_id=agilicus-builtin-agent-connector&code_challenge=XXXXX&code_challenge_method=S256&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&scope=openid+profile+email+offline_access+urn%3Aagilicus%3Aapi%3Aapplications%3Areader%3F+urn%3Aagilicus%3Aapi%3Aapplications%3Aowner%3F+urn%3Aagilicus%3Aapi%3Atraffic-tokens%3Aowner+urn%3Aagilicus%3Aapplication_service%3A%2A%3Aowner%3F&state=XXXXX
Enter verification code: scpfcXXXXXpim4qq5pl
checking code
INFO[2022-05-28T18:33:23.875526942Z] Check if the agilicus-agent is already running as a service. If so stop it
INFO[2022-05-28T18:33:23.932589295Z] Create a directory at /etc/agilicus/agent
INFO[2022-05-28T18:33:23.934868328Z] Download public key file to /etc/agilicus/agent/public_key.json
INFO[2022-05-28T18:33:24.265979606Z] Create file /usr/bin/agilicus-agent-wrapper.sh
INFO[2022-05-28T18:33:24.266562921Z] Create file /etc/systemd/system/agilicus-agent.service
INFO[2022-05-28T18:33:24.273604799Z] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x}
INFO[2022-05-28T18:33:24.278649712Z] Will install to /agilicus-agent.service -> {/etc/systemd/system/agilicus-agent.service -r--r--r--}
INFO[2022-05-28T18:33:24.282177117Z] Create a directory at /opt/agilicus/agent/tufmetadata/latest
INFO[2022-05-28T18:33:24.282578531Z] Create a directory at /opt/agilicus/agent/tufmetadata/stable
INFO[2022-05-28T18:33:24.285506591Z] Setup Agilicus secure store
INFO[2022-05-28T18:33:24.285945878Z] Create secure keyring for storing communication credentials in /etc/agilicus/agent
INFO[2022-05-28T18:34:25.392134745Z] Fetch agent configuration
INFO[2022-05-28T18:34:25.392429467Z] Write agent configuration file in /etc/agilicus/agent/agent.conf.enc.yaml
INFO[2022-05-28T18:34:26.432424427Z] Create a user and group named Agilicus to run the agilicus-agent service
INFO[2022-05-28T18:34:26.432722016Z] Copy executable to /opt/agilicus/agent
INFO[2022-05-28T18:34:26.432866291Z] Set permissions to Agilicus on /opt/agilicus/agent
INFO[2022-05-28T18:34:26.433163321Z] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent-mipsle
INFO[2022-05-28T18:34:26.914492417Z] Start agilicus-agent service
INFO[2022-05-28T18:34:27.898994929Z] Installation Complete
root@erx:~# systemctl status agilicus-agent.service
* agilicus-agent.service - Agilicus Agent
Loaded: loaded (/etc/systemd/system/agilicus-agent.service; enabled; vendor preset: enabled)
Active: active (running) since Sat 2022-05-28 18:34:27 UTC; 9s ago
Main PID: 23147 (agilicus-agent)
CGroup: /system.slice/agilicus-agent.service
`-23147 /usr/bin/agilicus-agent client --cfg-file /etc/agilicus/agent/agent.conf.enc.yaml
Note: Missing Let’s Encrypt Intermediary
curl -k https://letsencrypt.org/certs/lets-encrypt-r3.pem -o /etc/ssl/certs/lets-encrypt-r3.pem sed -i ‘/^mozilla\/DST_Root_CA_X3/s/^/!/’ /etc/ca-certificates.conf update-ca-certificates
Note: Time Synchronisation (NTP)
Before running the install steps, ensure NTP (time synchronisation) is running. If you do not have your own NTP server, use pool.ntp.org (specifically, use 0.pool.ntp.org as a server name). NTP can be enabled in the ‘system’ menu.
$ show ntp
remote refid st t when poll reach delay offset jitter
==============================================================================
-216.197.156.83 .PPS. 1 u 51 64 1 44.325 -2.774 3.691
+198.245.55.137 15.254.136.119 2 u 48 64 3 31.049 3.062 2.792
*2001:1600:4:1:: .GPS. 1 u 48 64 3 117.633 0.569 1.495
+207.34.48.31 205.206.70.42 3 u 48 64 3 61.305 3.715 3.977
You have a Virtual Private Cloud (VPC) in AWS EC2. It has private-only IP addressing. You need to ssh to some hosts within it, or remote desktop, or share some folders, etc. In this example we will show how to install the Agilicus Connector onto a t2.micro instance, with no public IP (and no NAT Gateway), and, use that to reach other instances within the VPC directly. There is no routing, no inbound or outbound connectivity otherwise.
You have a Virtual Private Cloud (VPC) in AWS EC2. It has private-only IP addressing. You need to ssh to some hosts within it, or remote desktop, or share some folders, etc. In this example we will show how to install the Agilicus Connector onto a t2.micro instance, with no public IP (and no NAT Gateway), and, use that to reach other instances within the VPC directly. There is no routing, no inbound or outbound connectivity otherwise.
Note: you can also follow these instructions AWS Doc to install a NAT gateway into your VPC, and then install the Agilicus Connector on a single machine within the VPC. This would allow your other VPC components to reach outbound.
In this example we will show a setup where a dual-homed t2.micro
Step 1: Create Private VPC
For this demonstration the private VPC has no NAT gateway, no Internet access. This is an internal only network. You can decide whether it has onwards access to other Amazon services if needed.
Step 3: Create private EC2 Server
For demonstration purposes we create an EC2 server to ssh to.
Step 4: Create dual-homed EC2 instance for Agilicus Connector
This machine will act to straddle the private VPC and the public Internet. It does not route, it does not NAT. No traffic will flow from/to it without going through the Agilicus Identity-Aware Firewall.
OK at this stage we have a VPC with no public IP. We have a private server on it with no public IP. We have a 2nd server, with a public IP, that can reach the devices in the VPC. We will now install the Agilicus Connector to facility onwards ssh.
Now, if we look at the config of the private server, we can see its hostname and IP:
Step 5: Install Agilicus Connector
These instructions are as normal for a Linux host. We create the connector in the web front end, it gives us a command line to run.
We are now given a command line to run. We paste it into the ssh on the Agilicus Gateway server (the one with the public IP):
# which curl && (curl -sSL agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh) || (wget -O - agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh); sh /tmp/i.sh -c JhtPxw9GVXXXXXX -s yw6XXXX
/bin/curl
OS: <Linux>, Machine: <aarch64>, END: <le>
Fetching https://www.agilicus.com/www/releases/secure-agent/stable/agilicus-agent-arm64 into /tmp/agilicus-agent-arm64
-rwxr-xr-x 1 root root 46268416 Jul 8 11:37 /tmp/agilicus-agent-arm64
+ /tmp/agilicus-agent-arm64 client --install --challenge-id JhtPxw9GXXXXX --challenge-code ywXXXX
INFO[2023-07-08T11:37:53-05:00] Starting connector - version v0.211.3
INFO[2023-07-08T11:38:08-05:00] Check if the agilicus connector is already running as a service. If so stop it
INFO[2023-07-08T11:38:08-05:00] Create file /usr/bin/agilicus-agent-wrapper.sh
INFO[2023-07-08T11:38:08-05:00] Create file /etc/systemd/system/agilicus-agent.service
INFO[2023-07-08T11:38:08-05:00] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x <nil>}
INFO[2023-07-08T11:38:08-05:00] Will install to /agilicus-agent.service -> {/etc/systemd/system/agilicus-agent.service -r--r--r-- 0xd97540}
INFO[2023-07-08T11:38:08-05:00] Create a directory at /opt/agilicus/agent/tufmetadata/latest
INFO[2023-07-08T11:38:08-05:00] Create a directory at /opt/agilicus/agent/tufmetadata/stable
INFO[2023-07-08T11:38:18-05:00] Create a user and group named Agilicus to run the agilicus-agent service
INFO[2023-07-08T11:38:18-05:00] Copy executable to /opt/agilicus/agent
INFO[2023-07-08T11:38:18-05:00] Set permissions to Agilicus on /opt/agilicus/agent
INFO[2023-07-08T11:38:18-05:00] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent-arm64
INFO[2023-07-08T11:38:18-05:00] creating connector instance
INFO[2023-07-08T11:38:19-05:00] Join a connector cluster
INFO[2023-07-08T11:38:19-05:00] Start agilicus-agent service
INFO[2023-07-08T11:38:21-05:00]
INFO[2023-07-08T11:38:21-05:00] Installation Complete
INFO[2023-07-08T11:38:21-05:00]
At this stage we are done, and ready to create an SSH resource in the Agilicus Admin GUI. We do this as normal.
Now open Agilicus Launcher and observe we can ssh to the ec2-private server, both from the Web interface, and, from our desktop.
If desired, enter a manual ~/.ssh/config entry to override the private key
Host ec2-private-server
Port 22
User ec2-user
ProxyCommand agilicus-agent wscat --oidc-issuer https://auth.dbt.agilicus.cloud --hostname %h --port %p
IdentityFile /home/don/.ssh/don-ec2.pem
At this stage we are done. We can ssh directly there:
$ ssh ec2-user
ast login: Tue Jul 5 01:36:47 2022 from ip-172-31-13-67.ca-central-1.compute.internal
__| __|_ )
_| ( / Amazon Linux 2 AMI
___|\___|___|
https://aws.amazon.com/amazon-linux-2/
[ec2-user@ip-172-31-6-69 ~]$
The Agilicus Connector can install on an embedded NAS product such as Synology. The devices (usually) have either an Intel or an Arm processor. The instructions are the same for each, but the link is different. The instructions below are for a Synology NAS but will be similar on other devices.
NOTE: Upgrades
Note: it is possible that when you upgrade the OS to your Synology you may need to re-install your Agilicus Connector.
No changes are needed to your firewall. No VPN is needed. You can administer users via their Active Directory or Apple, Google, Linkedin accounts.
The high level steps are:
Enable SSH on your NAS
Create a Connector (Agilicus admin interface)
SSH to the NAS
Run the given command
after this, the Agilicus Connector will be entirely automatic, and controlled via the Agilicus admin interface.
1. Enable SSH
In order to install the Agilicus Connector on your Synology NAS, you will first need to enable SSH. We can do this from the Synology Web Interface Control Panel, select “Terminal & SNMP” under Applications.
If you are not familiar with SSH, it is a Secure Shell remote command line interface. We will only use it for the installation step here, after which we don’t need it. You may use ssh from the command line on your Windows, Mac, Linux machine (it is typically installed on all of these). You may also use Putty, or, you may install SSH into Chrome and use from your browser.
2. Create Agilicus Connector
First we will create a Connector. This logical endpoint allows reverse inbound connectors to safely occur.
We give the connector a name. This is used for statistics and diagnostics purposes.
You will now be presented with some download instructions. Copy the command line given for Linux.
3. SSH to the NAS
SSH to your NAS. Run ‘sudo -i’. Now paste the command line
...
INFO[2024-01-07T17:14:35-05:00] Starting connector - version v0.237.1
INFO[2024-01-07T17:15:00-05:00] Check if the agilicus connector is already running as a service. If so stop it
...
INFO[2024-01-07T17:15:09-05:00] creating connector instance
INFO[2024-01-07T17:15:10-05:00] Join a connector cluster
INFO[2024-01-07T17:15:10-05:00] Start agilicus-agent service
INFO[2024-01-07T17:15:18-05:00]
INFO[2024-01-07T17:15:18-05:00] Installation Complete
At this stage we are complete. Let us look at some sample first resources.
Sample: Synology Web Interface
As a first example, let us make the Synology Web interface available via Agilicus. The detailed screen shots are below, but the steps are:
Resources/Application New. Select a name (this will become an internet host name, so it cannot have spaces or special characters)
Select which connector (the one we just installed) is on the same site as the Synology
Select the network coordinates of the Synology web interface. Since we are running inside the NAS, we can use ‘localhost’ and 5000 for a port (these are the internal coordinates of the web interface)
Select authenticated by Proxy. This means a user will be forced to provide credentials in order to see the web interface
Select ‘named users, single role’, we will assign permissions in the next step. Hit apply, this will create the application.
Assign permissions. Access/Application Permissions. We can assign permissions to groups or individual users. Select the row for the user/group, and the column for the application.
We are done. Let’s test. We can use ‘profile’ (https://profile.__MYDOMAIN__), or, directly, https://APPNAME.__MYDOMAIN__. let’s use the link to profile in the lower left, note (and bookmark) the URL it goes to.
You should see an icon for your new Synology NAS web interface. If not, refresh the page. If you select it, it will navigate to a new web page, note the URL.
Sample: Synology Share
Let’s assume we have a Share existing on our Synology called ‘tmp’. On the filesystem this is in /volume1/tmp. Once we have completed the above steps, we can create a new Share in the Agilicus admin interface (https://admin.__MYDOMAIN__).
Next we will be asked for two parameters (web uri path prefix, name). The first will appear in an http path, e.g. if you say “bobcat”, the URI your users will see is https://files.__MYDOMAIN__/bobcat. The second is a name which will show up in the audit log. Normally these are the same (unless you have the same share name on multiple hosts).
Now we will indicate the path on the Synology. In our example (The synology has a share called tmp, this will be in /volume1/tmp)
At this stage you will be given the option to test this in the administrative interface, and, your users may navigate to https://profile.MYDOMAIN to get their own mount instructions for their desktops.
Sample: Synology Surveillance Station Remote Cameras
See Synology Surveillance Station for detailed setup, the above web interface setup will give you access to your cameras, the remainder of the setup is on the NAS interface.
It i possible to allow/deny access to individual resources based on the country their inbound IP is coming from.
Note:As with all IP-based lookup schemes, a user coming via VPN can appear in an alternate location.
Geo-location is done at the granularity of country. Countries are identified by their ISO-code (a 2-letter code unique per country).
Rules have priorities. Lower numbers evaluate first. Rules with the same priority evaluate in parallel, taking the most restrictive answer.
Actions include:
Allow
Deny
Log
An example configuration allowing (priority-0 evaluates first) traffic from Canada, US, and denies (priority-1, NOT Canada, US) the remainder is shown below.
The Agilicus Connector supports native high-availability. In some environments (notably Windows High Availbility File Servers), it may be desirable to instead use Microsoft’s Windows Clustering technology.
To enable High Availability in the Agilicus Connector in a Windows environment (e.g. for resilient access to a Share, to remote desktops), configure it within a Windows Failover cluster.
The high level instructions are:
configure a windows failover cluster with a shared disk of at least 200MiB.
Install the Agilicus Connector into the shared disk on one of the servers. See below for specific instruction.
Stop the service on the node and set it to Disabled
Open the failover cluster manager
In your cluster, select Roles-> add new roles
Click next, select the “Generic Application” role
For the command line, enter F:\agilicus-agent.exe (the working directory from the install instructions, the shared disk)
name the service something unique (e.g. “agilicus-connector”)
Add the storage (e.g. F: in our example)
Don’t register settings
Click confirm, finish
Verify the Agilicus connector is running
Connector Install
On one of the servers in the cluster, we will perform the install as normal, with one modification.
Open a browser (on any machine, does not need to be the windows cluster), sign in to the Agilicus Admin web interface, create a new connector, select the appropriate OS tab, and copy.
On the machine in the server cluster, open an administrative shell, paste the command line. DO NOT PRESS ENTER. Add a command line parameter of ‘–working-directory <PATH>’ where <PATH> is the shared folder (e.g. F:\Agilicus).
For cmd, the sample command would then look something like below:
The instructions to install the Agilicus Connector are nearly identical on various Unix operating systems. This includes desktops, servers, and embedded devices.
See a specific example, the NanoPI R5S or a Synology NAS. Most platforms are installed as follows:
Create Agilicus Connector
First we will create a Connector. This logical endpoint allows reverse inbound connectors to safely occur.
We give the connector a name. This is used for statistics and diagnostics purposes.
You will now be presented with some download instructions. Copy the command line given for Linux.
SSH to the device
SSH to your device. Run ‘sudo -i’ if you are not root (your prompt is not ‘#’). Now paste the command line
...
INFO[2024-01-07T17:14:35-05:00] Starting connector - version v0.237.1
INFO[2024-01-07T17:15:00-05:00] Check if the agilicus connector is already running as a service. If so stop it
...
INFO[2024-01-07T17:15:09-05:00] creating connector instance
INFO[2024-01-07T17:15:10-05:00] Join a connector cluster
INFO[2024-01-07T17:15:10-05:00] Start agilicus-agent service
INFO[2024-01-07T17:15:18-05:00]
INFO[2024-01-07T17:15:18-05:00] Installation Complete
At this stage we are complete.
General Devices
Generically supported are any devices running Linux with at least 256MiB of RAM, at least 512MiB of flash storage, ARM or x86 processor. These include below (and more).
systemd-based Linux installations (e.g. Ubuntu etc)
upstart-based Linux installations
Raspberry PI
OpenWRT
pfSense (FreeBSD Firewall)
Ubiquity Edge Router X
Synology NAS
Specific walk-throughs are provided for some of these on the Agilicus Connector page.
The Ubiquiti EdgeRouter-X has a built in web interface. In this example, we use a connector installed on it to make this web interface available to arbitrary users over the public Internet
The Ubiquiti EdgeRouter-X has a built in web interface. In this example, we use a connector installed on it to make this web interface available to arbitrary users over the public Internet… without opening the firewall. Each user must use Single-Sign-On via Agilicus plus their existing identity provider, and then can access from any device without a VPN.
Step 1. Create application
Step 2. Enter name (hostname we will use externally), description
Step 3. Indicate we use standard pattern hostname.
Step 4. Indicate its via an Agilicus Connector (in this case, installed on the Ubiquiti EdgeRouter-X directly).
Step 5. Select the connector (previously configured as per instructions)
Step 6. Indicate we will use TLS from user to device.
Step 6. Configure upstream as localhost:443, on TLS (this is the local web server of the EdgeRouter)
Step 7. Indicate that Agilicus will do an OpenID Connect Authentication Proxy, use /logout as the revoke token URI.
Step 8. Indicate that we will have individual users.
Step 9. Apply. After this is complete we will then add a user to permissions and test.
At this stage we can assign permissions:
Now we can either use profile (https://profile.MYDOMAIN) which has all applications in it as a launcher, or navigate directly (https://erx.MYDOMAIN).
If desired, publish so that it is selectable in profile, and give it an icon:
During the installation, a Service Account will be created (permissions for the Connector to run as).
The Raspberry Pi installation uses the same instructions as the Linux ones (image at right) A sample command line is offered in the Agilicus admin porttal, which may be pasted into the ssh shell.
You are now complete.
Logs (if any) are generated to /var/log/agilicus-agent.log (e.g. run ‘tail -F /var/log/agilicus-agent.log’)
We may check the status once installed as below.
Sample Install Output
RPI $ which curl && (curl -sSL agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh) || (wget -O - agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh); sh /tmp/i.sh -c hAS43XdGbJwpnmSo2AjrKH -s ua6keppv
/usr/bin/curl
Must run as root to do install, attempting to use sudo.
OS: <Linux>, Machine: <x86_64>, END: <le>
Fetching https://www.agilicus.com/www/releases/secure-agent/stable/agilicus-agent into /tmp/agilicus-agent
-rwxr-xr-x 1 root root 50616688 Jul 1 18:12 /tmp/agilicus-agent
+ /tmp/agilicus-agent client --install --challenge-id hAS43XdGbJwpnmSo2AjrKH --challenge-code ua6keppv
INFO[2023-07-01T18:12:16-04:00] Starting connector - version v0.208.3
INFO[2023-07-01T18:12:30-04:00] Check if the agilicus connector is already running as a service. If so stop it
INFO[2023-07-01T18:12:30-04:00] Create file /usr/bin/agilicus-agent-wrapper.sh
INFO[2023-07-01T18:12:30-04:00] Create file /etc/systemd/system/agilicus-agent.service
INFO[2023-07-01T18:12:30-04:00] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x <nil>}
INFO[2023-07-01T18:12:30-04:00] Will install to /agilicus-agent.service -> {/etc/systemd/system/agilicus-agent.service -r--r--r-- 0x135ad20}
INFO[2023-07-01T18:12:30-04:00] Create a directory at /opt/agilicus/agent/tufmetadata/latest
INFO[2023-07-01T18:12:30-04:00] Create a directory at /opt/agilicus/agent/tufmetadata/stable
INFO[2023-07-01T18:12:30-04:00] Create a user and group named Agilicus to run the agilicus-agent service
INFO[2023-07-01T18:12:30-04:00] Copy executable to /opt/agilicus/agent
INFO[2023-07-01T18:12:30-04:00] Set permissions to Agilicus on /opt/agilicus/agent
INFO[2023-07-01T18:12:30-04:00] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent
INFO[2023-07-01T18:12:31-04:00] creating connector instance
INFO[2023-07-01T18:12:31-04:00] Join a connector cluster
INFO[2023-07-01T18:12:31-04:00] Start agilicus-agent service
INFO[2023-07-01T18:12:32-04:00]
INFO[2023-07-01T18:12:32-04:00] Installation Complete
INFO[2023-07-01T18:12:32-04:00]
RPI $
The Netgate SG-1100 pfSense is a small-form factor router. it is a good vantage point to run the Agilicus Connector.
Other pfSense appliances may work, they will need to be arm or x86 based, and have at least 120MiB of storage available. The Agilicus connector will consume approximately 50MiB of RAM.
The below instructions were tested on a Netgate SG-1100 with v22.01, specifically:
# cat /etc/version
22.01-RELEASE
The pfSense installation uses the same instructions as the Linux ones (image at right) A sample command line is offered in the Agilicus admin porttal, which may be pasted into the ssh shell.
Once you run this command, you will see output as below. You are now complete.
The Agilicus Agent Connector will self-update over time, no intervention is required.
We may check the status once installed as below.
Logs (if any) are generated to /var/log/agilicus-agent.log (e.g. run ‘tail -F /var/log/agilicus-agent.log’)
[22.01-RELEASE][root@pfSense.home.arpa]/root: which curl && (curl -sSL agilicus.com/www/releases/secure-agent/stable/install.sh > /tmp/i.sh) || (wget -O - agilicus.comw
/usr/local/bin/curl
Check time synchronisation/NTP is active
OS: <FreeBSD>, Machine: <arm64>, END: <le>
Fetching https://www.agilicus.com/www/releases/secure-agent/stable/agilicus-agent-freebsd-arm64 into /tmp/agilicus-agent-freebsd-arm64
-rwxr-xr-x 1 root wheel 45613056 Jun 3 18:52 /tmp/agilicus-agent-freebsd-arm64
+ /tmp/agilicus-agent-freebsd-arm64 client --install --challenge-id XXXX --challenge-code XXXX
INFO[2023-06-03T18:52:48Z] Starting connector - version v0.201.0
INFO[2023-06-03T18:53:01Z] Check if the agilicus connector is already running as a service. If so stop it
INFO[2023-06-03T18:53:01Z] Create file /usr/bin/agilicus-agent-wrapper.sh
INFO[2023-06-03T18:53:01Z] Create file /usr/local/etc/rc.d/agilicus-agent
INFO[2023-06-03T18:53:01Z] Will install to /agilicus-agent-freebsd.rc -> {/usr/local/etc/rc.d/agilicus-agent -r-xr-xr-x <nil>}
INFO[2023-06-03T18:53:01Z] Will install to /agilicus-agent-freebsd.sh -> {/usr/local/etc/rc.d/agilicus-agent.sh -r-xr-xr-x <nil>}
INFO[2023-06-03T18:53:01Z] Will install to /agilicus-agent-wrapper.sh -> {/usr/bin/agilicus-agent-wrapper.sh -rwxr-xr-x <nil>}
INFO[2023-06-03T18:53:01Z] Create a directory at /opt/agilicus/agent/tufmetadata/latest
INFO[2023-06-03T18:53:01Z] Create a directory at /opt/agilicus/agent/tufmetadata/stable
INFO[2023-06-03T18:53:02Z] Create a user and group named Agilicus to run the agilicus-agent service
INFO[2023-06-03T18:53:02Z] Copy executable to /opt/agilicus/agent
INFO[2023-06-03T18:53:02Z] Set permissions to Agilicus on /opt/agilicus/agent
INFO[2023-06-03T18:53:02Z] Create symlink from /usr/bin/agilicus-agent to /opt/agilicus/agent/agilicus-agent-freebsd-arm64
INFO[2023-06-03T18:53:03Z] creating connector instance
INFO[2023-06-03T18:53:03Z] Join a connector cluster
INFO[2023-06-03T18:53:03Z] Start agilicus-agent service
INFO[2023-06-03T18:53:04Z]
INFO[2023-06-03T18:53:04Z] Installation Complete
INFO[2023-06-03T18:53:04Z]
[22.01-RELEASE][root@pfSense.home.arpa]/root:
The Agilicus AnyX Platform supports self-sign-up and evaluation. If you wish to create an environment to evaluate, please run through the ‘Sign-Up‘ flow (see product-guide for more information on the sign-up flow). Once you have an organisation setup and can sign-in, you may wish to try and entirely encapsulated, built-in demo. This has no software to install on your machine. The video walk through below shows the steps and usage.
Demo Coordinates and Internals and Notes
When you select the “CREATE INITIAL DEMO SETUP”, a container is creating running a desktop operating system. Several objects are now created: – Agilicus Connector – Share (the temp directory of the container, /tmp) – VNC remote desktop
There is one additional resource, a local web server is running in this environment, listening on localhost:8000. You may create a web application, using the demo-connector, to reach this web application.
The domain you have chosen during setup, you will have 2 web url: – https://admin.__MYDOMAIN__ –> the administrative interface – https://profile.__MYDOMAIN__ –> the end-user interface, launch pad
opening the Profile, you will see each of these resources.
Cleanup
Once you are complete, there is a ‘DELETE DEMO SETUP’ button which will delete each of these resources.
The NanoPI R5S has 1 x Gigabit Ethernet, 2 x 2.5 Gigabit Ethernet, 4GiB of RAM, and 32GB of eMMC storage. With its large passive heatsink it is an ideal platform to use as a small router. It also makes an ideal platform to run the Agilicus Connector.
The NanoPi R5S will run several operating systems (Ubuntu, Armbian, OpenWRT). In this document we discuss using it with OpenWRT. Specifically, Agilicus makes available a hardened-version of OpenWRT for this platform.
Installing Agilicus OpenWRT
As received, the NanoPi R5S will (usually) be running FriendlyWRT. You may feel free to use this, however it has some security flaws. Agilicus recommends using our build. You may build it yourself, or for convenience we supply an image here.
Connect your laptop to one of the two LAN ports (closest to the USB-C power connector).
Select ‘Choose File’. Select the file you downloaded
Select ‘Upload and Write’
Wait approximately 90s (until the lights stop flashing and it indicates its complete)
Power off, power on
At this stage you are running the Agilicus-supplied OpenWRT image.
Router Setup
We have chosen to disable DHCP server by default (to avoid the risk of plugging this device into an existing network and causing confusion). To initially connect, plug your laptop into one of the LAN ports (closest to the USB-C connector) and set the IP on your laptop to ‘192.168.2.2’ and connect to http://192.168.2.1/ via your browser.
On first sign-in, you will be prompted to set a password. Choose something strong (later we will suggest a way that the router is blocked for password access entirely).
This is a standard OpenWRT (23.04) image, and the normal User Guides show different configuration options.
The default configuration is:
WAN (DHCP client, all inbound blocked, outbound NAT)
LAN (static 192.168.2.0/24, all inbound allowed, default route through WAN).
SSH enabled (with passwod)
Web enabled (with password)
No UPnP services nor mDNS/Avahi are enabled by default.
Agilicus Connector Install
Using the Agilicus administrative portal, create a new connector. Use the ‘Linux’ instructions, copy.
In the OpenWRT admin interface (http://192.168.2.1/), select ‘Services/Terminal’. Sign in as root and the password you selected. Paste (shift-insert).
At this time the connector should be installed and you may close the terminal.
You may wish to enable access to this router via the Agilicus AnyX platform (notably SSH and Admin web interface).
NOTE: DHCP Server Enable
Depending on your use, you may wish to have a DHCP server on the LAN ports, you can enable this under ‘Network/Interfaces/LAN’. You may also configure your desired IP range here.
❗
It is appropriate to have a DHCP server on these LAN ports if this is an isolated network. If you are connecting to a larger network with an existing DHCP server, you probably wish to instead change the protocol on the LAN ports to DHCP Client.
NOTE: Time Sync (NTP)
Modern cryptography requires clock sync and accuracy on all devices. Typically this is performed via Network Time Protocol, however, in some environments this is blocked (e.g. HTTPS-only outbound).
If your clock is not sync’d (see System/Time Synchronisation menu), you might be able to use a local NTP server. If not, you can enable an HTTPS-based sync as below:
service htpdate enable
service htpdate start
This is going to use the Agilicus API to provide an HTTP-based (over HTTPS port 443) time service. Configuration can be observed in /etc/config/htpdate:
Once you have installed the Agilicus Connector, we recommend disabling the web terminal. On ‘Services/Termina’, select the config tab and remove the check-box beside ‘Enable’.
You may re-enable the web terminal later if you need it. However, we recommend using SSH instead for future command-line access.
The web terminal operates on a secondary TCP port (7681) and is not needed for normal operation.
SSH Setup
Agilicus recommends disabling password access to SSH in favour of SSH Keys.
On System/Administration, the SSH Access tab, uncheck ‘Password authentication’ and uncheck ‘Allow root logins with password’.
The rationale here is that password stuffing and guessing is a thing. Eventually someone will guess your l33t-hax0r password. Removing any ability to use passwords reduces the risk. In some controls environments any passwords can be disallowed.
Once you have disabled password access, we recommend adding a SSH Key. Agilicus recommends using ed25519 SSH keys since they are smaller and more secure. Add your public key to the router here and place the private key (with passphrase!) in your SSH Agent on your desktop.
SSH keys are not only more secure, but also more convenient.
One downside to note: the Agilicus web interface for SSH is not currently compatible with SSH keys. If you wish to have SSH access to this device via the Agilicus Profile web interface, keep password on.
Firewall
At this stage, configure the firewall and NAT settings to suit on each of the interfaces. If the Agilicus Connector is providing Service Forwarder services, remember to open this ports on the router too.
We can check which ports are listening by running netstat -nlpt as below. Things with 0.0.0.0:PORT are available from outside the device. Things listening on 127.0.0.1, fe80::, ::1, etc, are locally bound only. In the example below, ‘uhttpd’ (the admin web interface), ‘dropbear’ (SSH) and ‘ttyd’ (the web terminal) are the only things listening.
This walk through shows an example of how, once the connector is installed (as per above), configuration of an HTTP and SSH interface to this local device. Once these are configured you could use the firewall to disable all external access. The high level steps are:
Create Connector (Agilicus Admin)
Install Connector (NanoPi Web Terminal)
Create SSH Resource (Agilicus Admin)
Create Web Resource (Agilicus Admin)
Assign Web Resource Permission (Agilicus Admin)
SSH to NanoPi from Agilicus Profile (Agilicus Profile)
Open Web Interface to NanoPi (Agilicus Profile or direct)
OK, let’s get started. This will take approximately 5 minutes.
First, create the connector on the NanoPi. Skip this is you have already done so above.
Select install. On the dialog, select ‘Linux’. Select ‘Copy’
On the NanoPi web interface, open the terminal, sign in. Press ‘Shift-Insert’ to paste the line you copied above.
You should see output as to the left, taking about 30 seconds.
Errors you might see include:
Time issues. The NanoPi does not have a battery-backed real-time clock. It is setup to use Network Time Protocol (NTP). If your firewall blocks this, or the WAN port is not connected, you must solve this first. Cryptography and certificates require good time sync. See below for an https-only solution that is simple to firewall.
Outbound firewall blocking www.agilicus.com or api.agilicus.com (both on port 443)
At this stage the connector is installed on this device. We will move on and configure SSH access next.
Create a new SSH resource. Select the connector we created above.
Create a new SSH resource. Select the connector we created above.
Give the SSH resource a name. We will see this later in the Web Interface and from the command line. The name must be valid as a hostname (e.g. no spaces).
Assign permissions. For this sample, we are assigning permissions to a single user. More commonly one would create a group (e.g. SSH Admins) to simplify.
At this stage, we have finished the SSH setup. We can use it from the Agilicus Profile (web-based, any device), from the Start menu on a desktop operating system, or via the command-line on our desktop. It will work with Putty and OpenSSH.
Now let us configure a Web Application to see the web console of the NanoPi R5S.
Create a new application. Give it a name (which must be valid as a hostname in format). You will later be accessing this as https://NAME.DOMAIN/
You may, if you wish, have a well-known alias to this new web interface. This is more commonly done with very public ones (e.g. a Wiki or Timesheet system). Leave it as default and the Agilicus AnyX will create the hostname for you.
Select the connector from the previous step.
The connector has to know where to send the request (it is a proxy). The ‘upstream’ in this case is the NanoPi R5S itself, e.g. localhost port 80.
For a bit of additional security we can tie the ‘logout’ URL of the NanoPi R5S web interface to the Agilicus AnyX logout by copying in the URL of the logout. This is optional.
We also suggest that named users with a single role, configured later, for this sample. Normally you would create a group, e.g. ‘Web Admins’ and assign users to it.
At this stage we are done, select ‘Apply’.
Now we will assign ourselves permission to use this new web resource.
To make the profile a bit more ‘fun’ we can now assign a logo (an icon) to the launch of this web interface. In this ‘define’ section we could also refine the Web Application Firewall rules etc.
Any image file (we suggest about 512×512) is suitable for a logo.
At this stage we are done. We have:
created and installed a connector on this NanoPi R5S.
created an SSH service (to the NanoPi itself)
created a Web resource (to the NanoPi itself)
We can now test our work. Open https://profile.__MYDOMAIN__/
Once you have signed in, you will see an icon for the new web resource, if you click it, a new browser tab will open. Observe the URL (https://NAME.DOMAIN). You can use this directly without profile if you wish. If you sign in, you will see the NanoPi R5S web interface directly. Now try it from a different network (e.g. your mobile phone, disable WiFi). Observe you can still connect. Now try with an unprivileged user (e.g. a different Gmail account), observe you cannot sign in.
The ‘profile’ interface acts as a launch pad for the end-user. It will act as a Progressive Web Application (e.g. ‘add to homescreen’ on your mobile), giving you a single launch icon.
You may also use the resources it points to directly: it is your choice.
We can test the SSH access. From profile, select the resource we created earlier.
We will see a ‘login’ dialog appear, enter the username (root) and password to the NanoPi R5S.
At this stage, we should see an SSH terminal.
From here, consider using the ‘Launcher’ install feature of profile, add the Browser Extension. You will now see an entry on your start menu for this SSH, opening the native client (e.g. if you have Putty or OpenSSH installed).
Similarly to the Web Resource, only users with permission are able to sign in. You may also choose to enable multi-factor authentication on your user and observe how this functions with both Web and SSH resources.
We don’t use passwords. Instead, you’ll link to your Google or Microsoft account. Select either ‘Microsoft’ or ‘Google’. You will then see a familiar sign-in screen.
Step 1A: Select Identity Provider
Select either ‘Microsoft’ or ‘Google’. You will then see a familiar sign-in screen.
If you use Google Workplace, or Gmail, use ‘Google’.
If you use Microsoft Office 365, Azure, Entra, Hotmail, Outlook, use ‘Microsoft’.
You will then be redirected to the normal sign-in experience for your Identity Provider.
Step 2: Set Up Your Organisation Name
Here you are being asked to name your setup. This is typically your company name. This name will be seen on invoices and other administrative sections.
Regular users won’t see it.
Step 3: Choose a Domain Name
Every resource you create will have a web address format like this: https://<RESOURCENAME>.<DOMAINNAME.>
You have two choices: 1. Simply use a domain we provide (like “myorg.agilicus.cloud”). 2. Use your own sub-domain (like ‘cloud.mydomain.com’). This is recommended for better security training.
Choose a sub-domain and an Agilicus domain, then click “Create”.
Option 2: Use Your Own Domain
Pick “I have set up my own cname alias”. In your DNS tool (like GoDaddy), create a new sub-domain. Point a wildcard CNAME record (like *.cloud.__MYDOMAIN__) to ca-1.agilicus.ca. If you use internal and external DNS, set up both. Click “Create”.
Step 4: Sign In to Your New Account
You’re nearly done! The system is now creating 3 new web areas:
admin.__MYDOMAIN__: The admin webpage
auth.__MYDOMAIN__: For authentication (you won’t go here directly).
profile.__MYDOMAIN__: A launch pad for end users.
After these are set up, you’ll be prompted to sign in again. Sign in using the same account from Step 1. You’ll see a guide to help you further, and you’re all set!
Securely sharing directories from individual servers or desktops has never been simpler. No VPN, no ransomware. No client to install.
Theory of Operation
General Steps
The Secure File Sharing is facilitated by an Agilicus Connector on the host(s) you have files you wish to access. Creating this is very simple, the only configuration option is a name.
Once the Connector is installed, you can later add new directories to share, modify who has access, and remove the share entirely, all from the admin user interface. The Connector will automatically keep itself up to date and pick up new configuration. Set it and forget it.
To create a new Share, you will walked through the steps in the Admin web interface. First, select the Connector you have previously installed. You may have multiple shares on the same Connector.
Now we give the Share a web URI name. This is something that will show up for the end-user, they will be given instructions to mount something like https://file…/NAME.
You must also configure a globally-unique name for this Share. You will see this in the Administrative interface, in the audit interface, etc. These may be the same if you wish.
We will now supply a “Local directory”. This is the directory on the machine the Connector is installed on. See the note below on permission, it is important that the Connector have access to it.
At this stage we are complete. As an administrator you will be given instructions on how to mount the Share, which you may use to test it is working correctly. Generally, each user in your organisation will use Profile in order to request and use a Share.
To manually mount the Share, there are 3 parameters:
URL. This will look like https://files.__MYDOMAIN__/URI-NAME
Username: this will be the email-address you use with the Agilicus system (e.g. your Active Directory login, your Google Login, etc)
Password: this will be an access token. This is generated for each user independently. End users may request access, or request an Access Token via Profile.
The Profile interface will give these parameters to each user.
Permissions, Access Control
Permissions work similarly to Applications. Each Share has 3 main permissions (Owner, Editor, Viewer). Users may be individually granted permissions per share, or, Groups may be used. We recommend Group-based access.
File Level Permission
By default, all files on a share are treated alike for permission (share-level permissions). However, you may enable per-file permissions. If this is enabled, the user’s SID or email are compared against the machine the connector is running on for permission on each file. This allows e.g. NTFS-level per file permissions. The user must have the permission to login locally to the machine for this to work.
NOTE ON PERMISSIONS
❗
Many Microsoft products (e.g. Microsoft Office) will create a Lock-file or a Temporary file in the same directory. This can be confusing when using a permission other than Owner. For example, if the permissions are ‘Editor’, a user can update an existing file, but not delete it nor create new files. If they open a Microsoft Word file, they may see an error indicating that the temporary file cannot be created. Unless you are using a small set of well-known applications, we recommend using Owner permissions.
NOTE ON MAXIMUM FILE SIZE
❗
The default limit for maximum size on some Windows clients is 50MiB. We recommend setting FileSizeLimitInBytes to a larger value, e.g. 500MiB. This is located in HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters See https://learn.microsoft.com/en-us/iis/publish/using-webdav/using-the-webdav-redirector for more information. This setting is on the client (where you will mount the share).
Access Request
Variable Expansion
In some cases you may wish the path to be templated, for example, mount /PATH/USERNAME. You may do that with string substitution. Variables may be expanded in the format of ${VARIABLE}.
The following variables are supported:
AGILICUS_USER_FULL_NAME
AGILICUS_USER_FIRST_NAME
AGILICUS_USER_LAST_NAME
AGILICUS_USER_EXTERNAL_ID
AGILICUS_USER_EMAIL
AGILICUS_USER_EMAIL_NAME
AGILICUS_USER_EMAIL_DOMAIN
Linux Specific
Permissions
The Agilicus Connector runs as an unprivileged system user. This means that, by default, it will not have permission to read files in a shared directory created by you. To give it access, create a group whose purpose is to group users who have permission to read and write shared files on the machine. Add the agilicus user to the group, then give that group permission to access the shared folder.
# Set up the shares group and add the agilicus user to it
sudo addgroup shares
sudo usermod -a -G shares agilicus
# Configure the share and all files within it to allow access to the shares group
sudo chgrp -R shares my-shared-directory
sudo chmod -R g+srw my-shared-directory
# Ensure files created by the connector and other users have the proper permissions
sudo setfacl -d -m g::rwx my-shared-directory
Windows Specific
Permissions
When installing the connector, by default it is installed as the ‘SYSTEM’ user. This user is typically appropriate for running a service, but there are times it may not have adequate permissions to access a specific folder for a share. When this happens you will see a ‘List Error’ trying to access the share from profile, and it won’t mount properly for end users. This can happen in particular when sharing from a network drive, where local permissions don’t grant access.
When this happens, it may be appropriate to assign it to a different user. This user might be a domain admin, a local admin or a separate user which you giver permission to access the folder being shared. This can be done by opening the Microsoft services applet, finding the ‘Agilicus Connector’ service, and changing the Log On option to run as a user with access to the share.
When you change the user which is running the connector, you must also ensure that the user running the connector has full read+write permissions to the “C:\Program Files\agilicus\agent” folder.
Manual Mount with Map Network Drive
A Share may be mounted using the Windows Explorer, just like any other Share. No special software needs to be installed. You will need the 3 parameters
Automatic Mounting
For end users with the Agilicus Launcher installed on the desktop, a Share can be automatically mounted/refreshed. This is particularly useful in conjunction with Multi-Factor authentication. In those mode, a ‘drive-letter’ or ‘mount path’ is configured as per below image, and the Share will automount for each user.
Linux Specific
For mounting a share automatically on Linux, fill in the ‘Linux path’ field on the client configuration shown above.
On Linux some extra setup is necessary in order to make automatic mounting work. The davfs package needs to be installed with the non-root mount option enabled On debian-based systems like ubuntu, you would run the following: sudo apt install davfs2 In the package configuration screen, choose the left option.
Next add you user to the davfs2 group: usermod -a -G group $USER You will have to reboot for this to take affect.
Lastly, for each share add an entry into your /etc/fstab file matching the following https://<YOUR SHARE URI> <LINUX PATH> davfs rw,user,noauto 0 0 This must match the uri for the share and the path configured to mount it.
From now on, whenever you run refresh on your desktop, the share will automatically mount!
Advanced Setup: Local Routing Performance
This is an optional section. It shows how to route traffic locally, from a machine with direct access to the connector facilitating the share. In order to achieve this, we rely on a local DNS (and split horizon DNS). The Connector will expose a local port (443) with the same hostname and certificate as externally.
In order to improve performance and decrease bandwidth usage, it can be useful to have your local users access a share directly, rather than over the internet. While this still requires the users to initially login to the Agilicus platform, it enables the network traffic for accessing the share itself to never leave the premises.
The end goal would look something like this at right.
To follow this guide, you have to already have a share created. Ensure that the share is working.
New shares will have the feature enabled to automatically support this task.
After you have your share working, you will need to ensure your site’s network is setup to access the share. By default, it will be exposed on port 443 (https) on the computer the connector is running on. If there is already a web server on that site, the connector could conflict and be unable to serve the traffic. In those cases, you will need to resolve the conflict and move either the agent or the website.
For each connector with assigned File Share resource, exposing its local server TCP port 443 simply requires enabling via the “Manage Routes” dialog:
By default we can bind to all the local server interfaces. If there is a segmentation requirement, we can specify the IP address the connector should only bind to.
The next step is setting up DNS to resolve share addresses to the connector onsite. You will need to configure the local dns server to route the domains for Agilicus shares to the local connector. Agilicus shares follow the pattern: <share-name>.share.<your agilicus domain>. For example, if your share is named ‘accounting’, and your domain is ‘cloud.acme.org`, then the share would be `accounting.share.cloud.acme.org`. You can also see what domain your share is on in profile by clicking ‘Manual Mount’ and checking the URL.
There are two choices available for how you configure your local dns entries.
Create a wildcard record *.share.<your agilicus domain> to direct all shares to the local connector. This will work correctly provided that all shares for your organization are available from this connector
Create a record for each specific share.
Whether you choose 1) or 2) depends on your specific network layout and your dns server’s capability for wildcard entries.
For example with a share named ‘test’, and the local connector on ‘192.168.122.1` a config in OPNSense would look like this.
Would you like to try an example with a predefined web application? See Example for a worked out example that gives you a simple executable web server and runs through setting up an Agilicus Web Application to reach it from the external world.
The ‘application’ concept includes several key concepts:
Authentication Clients. These are called ‘client id’ or ‘applications’ in other Single-Sign On and Identity platforms
Roles. A Role is an intrinsic set of permissions a user might have (e.g. Administrator, Editor, etc)
Rules. A Rule is an authorisation firewall configuration. E.g. /admin/.* can be accessed via GET/POST/PUT for Administrators
Image Runtime. If the application is hosted on the Agilicus platform this will be a container (or a runtime for a bundle)
Bundle. A zip file which will be mounted into a Runtime. This might be the output of a npm build for example, or a set of PHP files
Proxy. This is a feature which remaps, provides security, upgrades security headers.
Instance. Applications can have multiple concurrent running configurations. An ‘Instance’ is a specific subset (e.g. production versus staging)
Status. For hosted applications this will show their running state.
In the lifecycle of an Application, you may create it with ‘New’ following a guided setup process. You may then refine or edit the configuration with ‘Define’. You may also define an application from empty using ‘Define’.
The Overview screen shows the current applications and allows editing them.
New
This will create a New application using a guided process. Typically use the ‘a new application’ option unless there is a pre-configured template for your well-known application.
Prior to starting here you should have created a Network Connector to the site hosting the web application / API.
After the first question, you will be asked to provide 3 facts in ‘Define Application’:
Enter the application name. This will become a HOSTNAME in DNS, so it must be valid (no spaces)
Describe the application. This is for you, it will show later in some reports.
Enter the application category. This is for you, it will allow aggregating some reports. E.g. ‘HR’
Next, you will be asked if you wish a hostname alias. This allows you to override the well-known pattern of the Agilicus platform (APPNAME.DOMAINNAME) with a special one. This might be e.g. ‘wiki.mycompany’ instead of ‘wiki.cloud.mycompany’.
I access via <appname>.<domainname>
I access via an alternate hostname that I have setup manually
Notice: Hostname Alias and DNS setup
It is important that if you choose the first option that the hostname you give is assigned via a CNAME to the Agilicus platform, similar to how you did this during initial organisation setup. e.g. if you use ‘wiki.example.com’, you would have in your DNS a CNAME record ‘wiki.example.com CNAME ca-1.agilicus.ca’.
Next, you will setup how the users Access this application. You have 4 choices:
Over the public Internet. The application is hosted by a SaaS provider or is otherwise publicly available without a firewall. The Agilicus platform can be used to provide authentication services via the Authentication Clients. No firewall rules are applid.
From my site via an onsite connector. The application runs inside a private datacentre or a virtual private cloud and an Agilicus Connector is used to reach and expose it.
From my site via a point-to-point VPN. Similar to the onsite connector but an ipsec site-to-site VPN has been pre-configured
From the Agilicus Cloud. The application is hosted within the Agilicus platform
Typically Option #2 will be used (From my site via an onsite connector). Once you select this, a new set of options to configure the web application firewall will appear:
My application expects to receive requests using its internal hostname. — Some web applications require a remap from e.g. https://EXTERNALNAME to http://INTERNALNAME, the firewall will make these changes.
Select Connector. Here you will select he previously configured network connection.
Data Path Processing. Here you will configure the encryption and logging method. If you select ‘Fine Graind Access Logs”, there will be two TLS segments, with the Agilicus web application firewall in the middle. If you select ‘End to End Transparent TLS” the encryption will be done within your site, and there will be no access logs generated.
Enter upstream Service. Here you will put the hostname and port as if you were accessing from onsite. This should be resolvable by the onsite connector. It might be e.g. “web.internal” and port “8888”. If you select “my service is accessed via TLS” this means that the *internal* site currently is encrypted (the external one will always be). You may also indicate if the TLS certificate of the internal site is publicly valid.
Next you will configure the Authentication. You may:
Does not require authentication. The site is a read-only website that anyone can use
Participates in Authentication. The application implements OpenID Connect or SAML
Is authenticated by proxy. The Agilicus platform will take care of single sign on authentication
You may also see “My application is also launched from a Desktop.”. This applies, for example, to Microsoft ClickOnce where a start-menu icon might be used.
At this stage you may Apply, and then move to the ‘Overview’ screen to observe and refresh status.
Overview
The Applications Overview lets you see at a glance each running application, and select one to edit (define) it.
The ‘Status’ is mostly applicable to hosted applications.
name: the name you gave the application. This will also be the hostname (e.g. what you type into a browser in https://name)
Description: as you provided in ‘New’
Image: this is only pertinent if you are running a hosted application inside the Agilicus platform
Image Tag: this is only pertinent if you are running a hosted application inside the Agilicus platform
Admin State: the application can be temporarily rendered inactive for diagnostics
Status: the running state when hosted inside the Agilicus platform. Multiple concurrent copies are run for redundancy.
The actions that are present here:
Delete application: remove the definition, remove from service
Enable application: set the admin state to ‘active’
Disable application: set the admin state to ‘disabled’
Define new: create a new application without the guided setup
Additionally, if you click on any row it will navigate directly to the Define screen for updates.
Define
The ‘Define’ screen may be used to create a net new application, or to update the definition of an existing one.
This screen has 4 main tabs (Common/Hosting/Security/Proxy), each configuring a subset.
Common
The ‘Common’ tab setups up configuration which is present on all instances, all configurations. This includes:
Name: the hostname this application will be addressed (do not include domain name)
Category: this is for your use, e.g. “HR”
Description: a textual string shown on the overview screen
Contact Email: if filled in and there is a problem the Agilicus team may contact this
Port: This is only used if the application is hosted inside the Agilicus platform on a container you provide.
Image Runtime: This is either
identity-aware WAF proxy — your application is exposed by an identity-providing proxy
one of the ‘core’ predfined — your application is a bundle run within this environment
unused — your application runs on your site or elsewhere
Publish Application — the application will appear in https://profile.__MYDOMAIN__ for your end users to discover
External — the application exists solely to create an authentication client, there is no data flow
Logo — this will be shown in https://profile.__MYDOMAIN__. The logo should be square (e.g. 256×256) and in png format
Hosting
Only use this tab if you are running an application inside the Agilicus platform. This means you are providing a container image. This is not a common use case, and most users will not use this tab.
There are two areas: “Instances” and “Bundles”
Instances
An ‘instance’ is a separate running copy of the application, which in turn has some specific configuration overrides. For customers who have multiple organisations (e.g. Production, Staging), this allows them to run multiple copies with different versions.
The columns:
Tag: only set this if you have provided your own container, it will be the image-tag (e.g. group/image:tag). If using one of the built-in runners please leave it set as ‘latest’
Owner: this column sets which organisation ‘owns’ or can change the application. This is used to share an application into other organisations
Organisations: which orgs this will show up in
Bundle Names: Use this to mount a file into a runner (e.g. a zip file of php files)
Status: this will show the current running status
Actions: this will go to a details screen (below) to set instance-specific parameters
Instance Details
In the ‘configure instance’ details screen, entered from the action button on the instance, we can configure:
image(version) tag: Tag: only set this if you have provided your own container, it will be the image-tag (e.g. group/image:tag). If using one of the built-in runners please leave it set as ‘latest’
Owner: this column sets which organisation ‘owns’ or can change the application. This is used to share an application into other organisations
Organisations: which orgs this will show up in
Bundle Names: Use this to mount a file into a runner (e.g. a zip file of php files)
Fully-qualified domain names: This allows setting an ‘alias’, and is the same affect as setting the ‘I access via’ hostname in the ‘New’. The same caution applies: ensure that your DNS has an alias (CNAME) for the name you enter here. Enter a fully-qualified name (e.g. HOSTNAME.DOMAINNAME).
In addition there are some status fields:
Status: stale/good
Running replicas: the number of currently running copies, this will scale up and down
Error message: any error detail
Restarts: the number of times the application has unexpectedly restarted
Last Apply Time: the last time changes were applied to the running system
Running image: the version currently executing
Running hash: the container hash currently executing
There is also some configuration related to files/environment/mounts/temp. These are:
File: this allows you to upload a single file and have it placed in the running image at a given location
Environment: set environment variables to configure your application
External Mounts: mount an external filesystem (e.g. SMB) into your running container
Temporary Directories: Create a directory which will be used for read-write scratch files
Bundles
A bundle is a zip-file containing support files of your application. These will be interpreted by the runtime container, mounted within it.
The proxy configuration allows setting up HTTP header and body rewriting, overrides, and upstream configuration. This is discussed separately on the Proxy page.
Diagnose
Hosted applications may produce diagnostic logs. These are available by date range and application, and may be downloaded as CSV for offline analysis.
You can add one (or more) Azure Active Directory systems as Upstream Identity Providers. Doing this will allow your team to sign in with their Active Directory username/password. If you work with more than one corporation, you may add multiple Upstream Identity Providers.
You can add one (or more) Azure Active Directory systems as Upstream Identity Providers. Doing this will allow your team to sign in with their Active Directory username/password. If you work with more than one corporation, you may add multiple Upstream Identity Providers.
Note: you can consider using the shared ‘Sign in with Microsoft’ Identity provider, which has zero-config. See considerations.
Agilicus Front-End Create Upstream Issuer
The setup is very simple and takes less than 2 minutes to acomplish. There is a ‘stepper’ that walks you through the tasks.
First, open the admin user interface (https://admin.__MYDOMAIN__). Login as your (initial) administrative user. Nagivate to ‘Organisation’/’Authentication Issuer’. From here you may select ‘Add Provider’, adding a new identity provider.
At this stage, you will enter a Stepper which will walk you through the steps graphically. First select Azure Active Directory as the type:
Azure Application Registration
The Stepper will show screen shots of how to configure Azure, they are also here. First, select ‘Azure Active Directory’ in your Azure console:
Now create a new Application. This will be for all logins to the Agilicus platform.
Select a name. This will be shown to the user on the Login select page, we recommend making it related to your organisation. E.g. “My Company Active Directory”. In the Application stepper you are given a “Redirect URI”, paste it here.
You will now be given 3 pieces of information. A ‘Display Name’, an ‘Application (Client) ID’, and a ‘Directory (Tenant) ID’. Enter these in the appropriate spots in the Stepper.
Here you can see where this information is placed in the Agilicus Admin Stepper, from the Azure screen we have:
On the Agilicus Stepper we have:
Now we create a ‘Client Secret’. This is a shared secret between the two systems. Create this in the Azure Portal:
As a description we recommend using the same name as for the Application. If you select an Expiry (e.g. something other than Never) you must remember to update the Admin user interface at a later date.
In the Admin stepper paste the secret you received. You are now done!
NOTE: Multiple Azure tenant with same email address
❗
If your Active Directory login name is the same as the email address you provided through your Apple ID / Google ID / LinkedIn ID, you may have an issue. Please contact Agilicus (info @ agilicus.com) and we can join these accounts for you. E.g. if your Apple ID email is foo@mycompany, and your Active DIrectory is foo@mycompany, let us know and we can join these two together.
Azure Claims
This section is optional. If you wish to synchronise groups, or use UPN as welll as email, you should configure a set of additional claims. Agilicus recommends:
email — this gives access to the user ’email’ which may differ from the UPN
onprem_sid — this is used if you will do passthrough authentication (e.g. using SAML with Citrix), or fine-grained access control on a Share
upn — this gives access to the user principal name
sid — this can be used to allow per session sign-out
preferred_username — this controls how the user might interact with the system as a name
(Optional) Azure Groups
You may wish to directly import your Azure groups into Agilicus for role-based access control. To do so, enable the groups claim in Azure.
On your Azure Upstream Identity Issuer, enable the group mapping as below. You may need to use the GUUID and map to names.
Testing and Application Consent
At this stage you may try a login. You can keep the Admin portal logged in and use https://profile.MYDOMAIN to try. You should see a new Sign-In option, which is named as you have above.
The first (and only) time you select this new Sign in option, you will be presented with a question as to whether you consent to the information shared. The Information shared is your Name, and your Email. No permission is being granted to access any Azure or Office 365 information.
You are now complete. All users can now Sign in with their corporate login, no additional passwords to remember.
Advanced Grant Workflow
NOTE: If you use advanced grant workflow
❗
If you do not do this, you may find that users who use the ‘offline_access’ workflow (also known as the refresh token) may be confused by constantly being requested to grant access.
