Single Sign On for Aqualus Water - Azure AD / Entra ID Setup and Implementation
This documentation is to assist with the configuration and implementation of Single Sign On functionality of the Aqualus Water platform for Microsoft-enabled businesses.
Please note these important points:
SSO functionality currently only works for
the Aqualus Water Staff Portal, and
the Android version of the Field Operations Application (AFOA) from Version 4.1.3.
for businesses with these single sign on providers:
Microsoft Azure AD / Entra ID.
Also, please be aware that for SSO to function for the FOA it must be enabled in the Staff Portal as it cannot function independently.
Taggle is in the process of providing access via other SSO providers - please contact the Customer Service team if you have specific requirements.
Please note that the Windows version of the Field Operations Application does not currently support this version of the implementation of SSO. Please see https://taggle.jira.com/wiki/spaces/TKB/pages/7086669825 for the process based on the legacy Application Password method and contact Taggle Customer Support to ensure you will not be negatively affected.
Contents
- 1 How to Enable Single Sign On in Aqualus Water
- 1.1 Azure AD / Entra ID setup
- 1.1.1 Overview
- 1.1.2 Authentication Setup
- 1.1.3 API Permissions Setup
- 1.2 Aqualus Water Authentication Configuration
- 1.3 Android Field Operations Application Specific Information
- 1.1 Azure AD / Entra ID setup
- 2 FAQ’s
How to Enable Single Sign On in Aqualus Water
Enabling Sign Sign On for the Aqualus Water platform, it is required to
Setup Azure AD / Entra ID Authentication,
Setup Aqualus Water Authentication for the Staff Portal, and
(Optionally) Setup Aqualus Water Authentication for the Android Field Operations Application (AFOA).
Azure AD / Entra ID setup
Overview
To enable SSO for the AFOA, you will need both
an Application Client Id, and
the Directory tenant ID keys.
These will need to be copied into the System Configuration area of your Aqualus Water instance, as detailed below.
The SSO configuration area in the System Configuration section of Aqualus Water only supports ONE Azure AD / Entra ID setup for the client.
If you already have Azure AD / Entra ID setup or configured, then ensure that your existing configuration includes the below steps and details for compatibility.
Authentication Setup
To begin, navigate to Authentication section.
The image below outlines the areas for each of the Steps listed.
Web Section (Step 1)
Set the Redirect URL to the full URL of your Aqualus Water instance (for example YOURBUSINESSSTAFF.aqualus.com).
Mobile and Desktop Applications Section (Step 2)
Ensure that only the ’MSAL only' redirect URI is selected.
Implicit grant and hybrid flows Section (Step 3)
Enable ID Tokens and the Multitenant options in this section. These are required for Aqualus Water to support both SSO in the Staff Portal and the AFOA).
API Permissions Setup
Next, navigate to API Permissions section.
The image below outlines the areas for each of the Steps listed.
Configure Permissions Section (Step 1)
Ensure that the User.Read is added.
Other Permissions granted for Section (Step 2)
Ensure the openid and profile permissions are added.
Aqualus Water Authentication Configuration
Once the Azure AD / Entra ID SSO Provider has been correctly set up, the Client ID and Tenant ID provided will need to be entered and applied in your Aqualus Water instance.
Staff Portal SSO Configuration Setup
Navigate to System Configuration Area (Step 1)
Navigate to Main Menu → System Configuration → System Configuration
Search for azureAD… variables (Step 2)
Search for the azureAD… section of the System Configuration options.
Update the azureAD… variables (Step 3)
Add or update the values below:
azureADAuthorityURL → https://login.microsoftonline.com/{0}/v2.0
azureADAuthTypeEnabled → 1
azureADAuthTypeName → As per the variable description.
azureADClientID → AzureAD/Entra ID Client ID.
azureADOrderNum → As per the variable description.
azureADSS0AuthTypeID → Do not edit this value.
azureADTenantID → AzureAD/Entra ID TenantID.
Contact Taggle Support to verify and finalise SSO setup (Step 4)
After the steps above have been completed, you will receive a message to contact Taggle Support to finalise the setup. Please let us know you are ready and we will complete the final step.
Enable SSO for the Staff Portal (Step 5)
Enable SSO for the Staff Portal using the Aqualus Water System Configuration area. Search for the ‘enableSingleSignOn’ variable.
Modify the variable:
enableSingleSignOn → 1
You should now be able to login to the Staff Portal by following the instructions below.
If not, please contact Taggle Support.
(Optional) Android Field Operations Application SSO Configuration Setup
Enable SSO for the AFOA (Step 6)
Please ensure you have set up mobile device access as per https://taggle.jira.com/wiki/spaces/TKB/pages/7778041857/Single+Sign+On+for+Aqualus+Water+-+Azure+AD+Entra+ID+Setup+and+Implementation#Mobile-and-Desktop-Applications-Section-(Step-2) above before proceeding with this change. If the configuration is not correct in this step, you will not be able to log into the AFOA - even if you are able to use SSO for the web interface.
Enable SSO for the AFOA using the Aqualus Water System Configuration area. Search for the ‘enableFOASingleSignOn’ variable.
Modify the variable:
enableFOASingleSignOn → 1
If you have not enabled SSO for the Staff Portal, enabling the SSO for the FOA will not be able to be applied. To have SSO working in the FOA, the variables from both Step 5 and Step 6 must be enabled.
You should now be able to login to the AFOA app by following the instructions below.
If not, please contact Taggle Support.
Android Field Operations Application Specific Information
Android Field Operation Application Usage Changes
Once the enableFOASingleSignOn has been enabled, the Login using Username and Password will be disabled (greyed out). Users will only be able to use the Single Sign On option from the Login Page.
Using AFOA Single Sign On
From the Login Page, tapping the ‘Single Sign On’ button displays the SSO Provider page.
The user can now enter their username and password using the SSO process.
Once the user is authenticated and the SSO Login process completes, the user will be redirected to the Dashboard Page and may commence work.
Details on the use and operation of the AFOA can be found in the https://taggle.jira.com/wiki/x/7oQLDQE .
Unauthorised Request message - Expired Token for SSO Provider
The expiry time for the SSO requests and authentication is set by you in your SSO provider settings. By default these should be sufficient, however please consult your SSO Provider’s settings if this timeout needs to be changed.
In the event that a user receives a message regarding an ‘Unauthorised Request’ as per the image below, the user has two options.
If Cancel is selected, the user will be able to keep using FOA Droid as offline mode. This means the user won’t be able to sync data, however data can still be added to the device. This is useful in a situation where the user’s authentication has expired but they are not in an area with internet access, as work can still be performed and saved locally. Once the user has access to the internet again they can authenticate and then process to sync the data back to the system.
If Login is selected, the user will be redirected to the Login Page to execute the SSO Login again. Once completed, the user will be redirected to the Dashboard Page and is able to continue work and sync data.
FAQ’s
Will enabling SSO affect existing users?
Staff Portal : No.
To allow backwards compatibility and that ability to roll-back changes if required, existing users with a matching email address will be able to login to the Staff Portal with SSO and their existing login details. This may be subject to change in future updates to enhance security processes.
AFOA : Yes.
Once the SSO is enabled as per the above, the ability to login using the existing username and password is disabled (the button cannot be actioned). In this instance, users will be required to login via the SSO functionality.
What roles or permissions are assigned to users that log in using SSO?
When user accounts are created in Aqualus Water via SSO, the user will have Public Only access. This means they will be able to log in, but have no access to the system from a functional standpoint.
New users will require a user with System Administrator Level 2 to set up their access in Aqualus Water.