Agilicus AnyX and VTScada are an ideal complementary match. Agilicus AnyX provides on-demand access, from anywhere, to any user, to the VTScada Anywhere client. This provides high-security and high simplicity usage for remote support and diagnostics.
A minor usability issue can arise, a ‘double login’ experience. The user signs in via Agilicus AnyX with their corporate single-sign-on credentials, but, then the VTScada system doesn’t trust them. This happens with external support and contractors as well as direct staff. Fortunately there is a simple solution: Configure VTScada to ‘participate’ in the sign-in and use Agilicus AnyX as the OpenID Connect Provider. Once this simple configuration is completed the user will sign-in once, using their native corporate account, without local configuration on VTScada.
First, we configure the Application in Agilicus AnyX. The only change from a typical application is to use the ‘My Application Participates in Authentication’. Otherwise configure as usual for VTScada.
Now that we have configured the Application, we can observe that a OpenID Connect ‘Client’ has been created (Resources/Applications/Authentication Clients). The name of it we will use in the VTScada configuration below. We will also configure a ‘remapping’ to cause the Agilicus User ‘External ID’ field to become available (see “VTScada – OpenID Connect Authentication“) for mapping to a different username if desired.
Add the ‘redirect uri’. The format will be “https://<vtscada-name.__MYDOMAIN__/vtscada/oidc/return”, matching vtscada-name and __MYDOMAIN__ to your environment.
At this stage we are complete in the Agilicus Admin and will switch to the VTScada configuration.
In the “OpenID Connect Provider” box, we will use the ‘discovery’ feature. The URL will be https://auth.__MYDOMAIN__/.well-known/openid-configuration. If you chose to use the remap feature above, enter that in the Account Name Field.
Enter the Client ID from above in the Client ID field of VTScada, as well as the Secret.
At this stage, test the login, it should function.
The key fields to use:
Enable OpenID Connect
OpenID Connect Discovery URL (https://auth.__MYDOMAIN__/.well-known/openid-configuration). Press the ‘Discover’ button, it will fill in the fields below
Permit remote sign-in using VTScada account credentials
Client ID (match to the field from Agilicus Authentication Client)
Shared Secret (match to the field from the Agilicus Authentication Client)
Account Name Field (match to the remapping above)
scopes (openid email groups profile offline_access)
NOTE: VTScada will require an outbound firewall connection to auth.__MYDOMAIN__. The user authenticates in their browser and passes a token to VTScada, which will in turn use that to lookup the user information remotely.
Mapping Multiple External Users To A Single VTScada User, With Multi-Factor
In some environments its desirable to have a single VTScada user (e.g. Operator) shared by multiple external users (e.g. joe@mycompany, jane@mycompany). Normally this would not be safe, but, with Agilicus AnyX the authentication is not shared and can include individual user multi-factor authentication.
Using the remapping above, use the ‘external-id’ field on a per-user in the Agilicus web admin, assign the VTScada user name per person.
For example, if you use these settings in the Agilicus admin users:
Agilicus (External) Username
External-ID
jane@mycompany
operator
joe@mycompany
operator
jerry@mypartner
admin
And remap the External-ID as:
Then Jane and Joe can sign in using their @mycompany single-sign-on (e.g. via O365, Google Workplace), be challenged for a second factor, but then end up signed into VTScada as ‘operator’.
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/’.
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
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.
Agilicus AnyX supports personalising the sign-in and usage environment to match your corporate brand. This is more than just asthethic: a consistent look and feel helps train users to reduce the likelihood of a successful spear-phishing attack.
Setting up your theme on Agilicus AnyX is quite simple. The basic steps are:
Download template
Modify template
Test locally in browser
Upload template
Test live
So lets get started. Before you start, you will want 3 files that can often be found on your company website:
favicon.png. This should be a square-aspect ratio, usually 256×256 or 512×512, of your company logo. It will show in a browser tab.
logo.png. This should be rectangular in size, approximately 1600×300 resolution. This will show in Profile in place of the Agilicus logo. We recommend a transparent background, and a foreground that will look proper with a blue background (#0057b8).
my-login.svg. This should be a square-aspect ratio svg, it will show in Profile in place of the Agilicus logo. The foreground should work with a blue background (#0057b8)
NOTE: Remote Links, Content-Security-Policy
❗
The Agilicus AnyX uses a strong, restrictive content-security-policy. This prevents linking to external 3rd-party css/js/images/fonts during the sign-in process. These must be mirrored into the theme file and served via the platform to be used.
First, we will download the ‘default’ theme.
This default theme can be unpacked somewhere on your computer.
The ONLY files you can modify are in the ‘theme’ subdirectory. The rest are read-only and just for the purpose of testing on your desktop.
When you re-pack this file, repack from the root directory, e.g. your new zip file should look the same as below, with an ‘index.html’ file in the top directory, and a theme-subdirectory.
You may add fonts/logos/etc to the theme directory and refer to them by relative path.
Once you have downloaded and unpacked this file, you will see the below contents. Do not change files other than in the theme directory (your changes will be ignored by the system). Overwrite the favicon.png and logo.png files in the theme directory. You may now proceed to testing.
On your desktop, in the directory you have unpacked the files, there is a file ‘index.html’. Double-click this, it should open in your browser. You can now see a list of links to the various pages, try each one to assess your changes. You may edit the styles.css and reload in the browser to iterate.
Once you are satisfied with your changes, proceed to the re-pack and re-upload.
Upload Template
Now that you are satisfied with your changes, make a zip-file of the entire directory structure you unpacked. E.g. ‘index.html’ will be in the root directory of the zip, and theme will be a sub-directory.
From your browser, use the UPLOAD THEME button in Authentication/Theming. Select the zip file you just made.
The theme will take affect after approximately 60-90 seconds. You may then test by signing-in again (e.g. in an incognito window).
NOTE: Browser Caching
❗
Your browser may cache the icons and fonts. Flush your cache if they do not seem to have changed.
Custom fonts
You may add your own fonts. To do so, we will do these steps:
Create a font-face entry in theme/styles.css
Add font-files to theme/my-font/
Adjust h1/body entries in theme/styles.css to reference your font
You might consider modifying the styles.css to set a background image, to change hover behaviour, etc.
To change the background image and colours, consider e.g. put an image called ‘background.jpg’ in the theme dir, then add a background-color/image/repeat to body or navbar as appropriate:
You may also have your own identity-provider and wish to change its icon (the Microsoft and Google ones are default). To do so, you will need an SVG file which is square in aspect ratio (see the my-login.svg as an example).
Add your ‘my-company.svg’ file, add a section in styles.csss to reference it:
In this implementaiton of Multi-Factor Authentication, the user is prompted to authenticate to their upstream identity provider, and, then, a multi-factor challenge is provided via web.
State can be kept in a secure cookie on the ‘auth.DOMAIN’ endpoint. This can allow single-sign-on with multi-factor as well as only requiring a 2nd factor over some time interval.
Supported Methods: WebAuthn (Passkey, USB Authenticator, FIDO U2F, …)
The Web Authentication (WebAuthn) standard is the current best practice. It allows seamless integration of platform-specific features (biometric, TPM) with external U2F and CTAP devices.
Browsers and versions supporting WebAuthn can be seen here.
WebAuthn is designed to be privacy preserving, no information on the user or device is shared with the network. This includes biometrics.
Supported Methods: TOTP (Time based challenge app)
A time-based one-time password (TOTP) is a universal standard, implemented by many applications (including Authy, Google Authenticator).
TOTP is private (there is no network communication flow) and works even without a graphical or browser flow.
Agilicus’ implementation works with all TOTP-supporting applications, however, we recommend Authy.
Our strategy is to not supply “yet another” TOTP application. Instead, we recommend users use a common one across all websites, including ours.
Web Push
Web Push uses a network authentication profile called VAPID. This is designed to be entirely private: there is no way to identify the user or device receiving the push. In the Web Push model, the user’s browser (whether open or not) will receive a ‘push’ “WAS THIS YOU” message when you try to login, even on another device.
Web Push is secure and convenient. However, the major downside is Apple, which does not support push methods. There is a petition requesting support.
Authentication Rules
Authentication Rules are a type of Conditional Access. They are logically part of the authentication flow, after he user has proven identity. These rules can augment the logic with things like:
has provided multi-factor authentication
is in / not in IP ranges
application properties
user properties
device properties
The system has a set of policy presets. These operate like macros, overriding the current rules and then leaving them free to configure.
You should choose this option for strong security and convenience for your users. Using a single identity source of truth among many applications enables maximal ease of use, while enabling multi-factor-authentication ensures that anyone without physical access to their device(s) cannot compromise the account. You will always be able to revoke a user’s access at any time and audit their usage of any applications or services. Details: Multi-factor authentication can be enabled per client, by default it will follow a user’s preference A user’s session is shared between apps unless that app’s client has Single Sign-On set to ‘never’ A user’s session lasts up to 7 days Multi factor authentication must be used to log in after every 30 days if a multi-factor authentication method has been configured
Permissive
You should choose this option if the data you need to get to your employees needs to be protected, but is not of a particularly sensitive nature. This option enables low barrier to entry to get as many users as possible onto the system with as little administrative overhead as possible. You will always be able to revoke a user’s access at any time and audit their usage of any applications or services. Details: Multi-factor authentication can be enabled per client, by default it will follow a user’s preference. A user’s session is shared between apps unless that app’s client has Single Sign-On set to ‘never’ A user’s session lasts up to 14 days Multi factor authentication must be used to log in after every 30 days if enabled
Strict
You should choose this option if you need the minimum ‘blast’ radius from a compromised device. By reducing the sharing of sessions between applications, minimizing multi-factor authentication duration and requiring frequent logins you can guarantee that in the event an employee’s device is compromised they cannot access anything other than what the employee is currently logged into. You will always be able to revoke a user’s access at any time and audit their usage of any applications or services. Details: Multi-factor authentication can be enabled per client, by default it will follow a user’s preference A user’s session is not shared between apps unless that app’s client has Single Sign-On set to ‘always’ A user’s session lasts at most 1 day Multi factor authentication must be used to log in every 7 days
Trust On First Use
Agilicus recommends a ‘Trust On First Use’ method of self-enrolment. In this model, a user is forced to setup their second-factor on the next sign-in, with a maximum deadline.
The deadline is set organisation wide, and is the delta from when the user is created until when they must have successfully demonstrated a 2nd-factor setup.
End-User Setup (Profile)
The end user may manually navigate to “Profile” (via https://profile.DOMAIN). They may also install it as a Progressive Web App (PWA), making it appear as a mobile-native application.
In the Profile, the user may setup whichever multi-factor methods their organisation has chosen to support.
if trust on first use is used. the user will be forced here on their first login within the enrolment period.
Diagnostics and User Audit
We can see which users have multi-factor setup in the ‘Users’ screen (via the shield). We can also filter to show only user with/without multi-factor authentication enabled.
The “RESET” users option will unset the multi-factor setup & preferences of a user.
We can see the multi-factor sessions and preferences (as well as all other audit information) of a given user on the audits screen. Here too we can reset the trust-on-first-use timeline.
Requiring multi-factor authentication
Normally, a user must periodically present their second factor when authenticating only if they have it enabled. That said, you can configure the policy to require a set of users to have a second factor method configured. If such a user tries to log in when they do have not have a second factor method configured, they will either be asked to enrol one, if they are within the enrolment deadline, or they will be denied access.
You can configure this setting in one of two ways. If you have not yet customised your authentication policy, you can apply one of the presets. Choose the preset to apply, then select the groups for which you want to force multi-factor authentication in the “Always require multi factor authentication for groups” section.
If the group you want does not exist, create it first. If you have customised the policy, you can either edit the existing rule which controls this behaviour, or create a new one. Under the “default multi-factor authentication rules” group, select the “Group Requires Multifactor” rule, then configure its condition (via the actions menu).
Choose “Configure condition details”, then select the desired groups in the “Values” chiplist. Do not change the operator. Once you have chosen the groups, navigate to “Apply” and click “Add”.
If this rule does not exist, you will need to create a new one in the “default multi-factor authentication rules” group. First, click “Add rule”, then select the newly created, blank rule. Change its name to “Group Requires Multi-factor”:
Set its Action to “Require Second Factor”.
Then add a new condition. Set its type to “Object attribute” with field “user member of id.
Move next to “Configure condition details”, where you will choose the “in” operator. Select the desired groups under “Values”.
Move next to Apply to add the condition. Once you done so, the policy will be updated, and users in the configured groups will be forced to provide a second factor.
Multi-Factor Authentication Frequency
Similar to an authentication session, a user’s proof of their second factor is only valid for a configurable amount of time. This configuration is part of the authentication policy. The duration for how long the second factor is valid is expressed in seconds. It can be configured either by applying a new preset, or by editing the appropriate authentication rule.
To apply a preset, choose the desired one from the “Authentication/Authentication Policy” page, then choose the time interval.
In this example, users will be asked to present their second factor every 2592000 seconds (30 days). Choose your desired value, then hit apply.
To configure the existing policy, open the “default multi-factor authentication rules” group, and choose the “User has succesfully provided a second factor within time window” rule.
Edit the value by selecting “Configure Condition” from the actions menu.
The Agilicus platform uses external Identity Providers (called Upstream Identity Providers). There are no passwords stored within the system. Supported standards include OpenID Connect (an extension of OAuth 2.0) and SAML 2.0. In turn, you will configure Authorisation in the Agilicus system. What this means is “who” is provided by a 3rd party, and “what they can do” is controlled by you, the Administrator.
Within the Authentication Issuer you have several configuration options:
You can configure the sign-in screen theming with your own logo and colours.
You can select from a set of Agilicus-Managed Upstream Identity Providers (Apple, Google, Linkedin)
The Authentication Clients implement OpenID Connect client id. This is an advanced setting, it is rarely required to configure. These are created automatically for each web application. You might create these if you have 3rd party applications using Agilicus AnyX as a Single-Sign-On provider (see VTScada Single-Sign-On as an example), you might edit them if you wish to alter the default parameters of a single application.
Background
An OpenID Connect (OIDC) client_id is a unique identifier assigned to an application that wants to use OIDC for authentication and authorisation. Think of it like a username for your application when it talks to an OIDC provider (in this case Agilicus AnyX)
Purpose: It tells the OIDC provider which application is requesting access. This allows the provider to apply the correct security policies, redirect users back to the right place after login, and more.
Uniqueness: Each client application registered with an OIDC provider gets a unique client_id. This is crucial for security and proper functioning.
Configuration: When you register your application with an OIDC provider, you’ll receive a client_id (along with other credentials like a client_secret in some cases). You’ll then configure your application to use this ID when making authentication requests.
Usage: The client_id is included in authentication requests sent to the OIDC provider. It’s used to identify the application and retrieve the appropriate configuration details.
Setup
The below images show an example of a default created client id for a web application. The name is created with a unique trailer to allow it to work into a sub-org that might have a same-named application.
The fields are:
Client ID: the OpenID Connect client-id. This must be unique within all of your orgs
Application: this is a pull down, selecting which application in the system to tie to
Secret: this string is used when configuring an OAUTH2 3-legged flow (see The OAuth 2.0 Authorization Framework) in which a backend, non-graphical component participates as well as a browser
Allowed Organisations: This can be used to control, grossly, which org can use this Client ID (rather than relying solely on assigned permissions). Valid values include: “Here Only”, “Here and Down”, “Any”, “<this org name>”, “<This org sub name>”.
Multi-Factor. This is an alternate way of assigning multi-factor “when”. Valid values include: “Always”, “User preference”, “Trust upstream”
Single Sign On Preference: This allows controlling whether a user can use ‘cached’ credentials (e.g. sign-in once for all apps, or, be forced to sign-in to each). Valid values include “User preference”, and “Never”.
Redirects. If you add applications outside the scope of the Agilicus AnyX platform, you may need to configure a redirect URI that is specific to it.
Authentication Attributes. This can be used to set fields that will appear in the ID Token to the application, e.g. username.
Identify Provider Aliases. Cause one identity provider to alias another.
A “User” is an identity which has a set of authorisations, a set of permissions. A user may be identified by one or more Identity Providers (e.g. Azure Active Directory, Google, Apple, etc.)
Users’ may be collected into groups, and, groups behave the same as a user for permission purposes. Groups may also aggregate other groups.
Identity Provider
An Identity Provider authenticates a user. It may do this with a password, with biometric, or with any trustworthy means. Agilicus acts as an Identity Provider for your applications.
Upstream Issuer
An Upstream Issuer is an Identity Provider that is federated in to the Identity Provider. This might include Apple, Google, Azure, Okta, Auth0, etc. The Upstream Issuer acts to authenticate a user.
Authentication Rules are a type of Conditional Access. They are logically part of the authentication flow, after the user has proven identity. These rules can augment the logic with things like:
has provided multi-factor authentication
is in / not in IP ranges
application properties
user properties
device properties
The system has a set of policy presets. These operate like macros, overriding the current rules and then leaving them free to configure.
Theory of Operation
The Authentication Rules are a set of Conditions (things we measure) and Actions (things we do).
Conditions
Conditions include any field in any Object in the system. The generic Object types include:
User
(Application) Client
Issuer
Login Session
Details
Clients.application == name of the Authentication Client
Clients.id == ID of the Authentication Client
Clients.issuer_id
Clients.mfa_challenge
Clients.single_sign_on
Clients.name
Clients.org_id
Clients.organisation_scope
Clients.secret
User.id
User.external_id
User.enabled
User.status
User.first_name
User.last_name
User.email
User.provider
User.org_id
User.type
User.created
User.updated
User.auto_created
User.member_of.external_id
User.member_of.enabled
User.member_of.status
User.member_of.first_name
User.member_of.last_name
User.member_of.email
Issuers.id
Issuers.issuer
Issuers.org_id
Issuers.upstream_redirect_uri
Users.multi-factor_challenge_type
Login.session.number_of_logins
Login.session.number_of_failed_multi_factor
Login.session.single_sign_on_time
Login.session.user_is_authentication
Login.session.user_is_authenticated_by_upstream
Login.session.user_is_authenticated_by_cache
Presets
Default
You should choose this option for strong security and convenience for your users. Using a single identity source of truth among many applications enables maximal ease of use, while enabling multi-factor-authentication ensures that anyone without physical access to their device(s) cannot compromise the account. You will always be able to revoke a user’s access at any time and audit their usage of any applications or services. Details: Multi-factor authentication can be enabled per client, by default it will follow a user’s preference A user’s session is shared between apps unless that app’s client has Single Sign-On set to ‘never’ A user’s session lasts up to 7 days Multi factor authentication must be used to log in after every 30 days if a multi-factor authentication method has been configured
Permissive
You should choose this option if the data you need to get to your employees needs to be protected, but is not of a particularly sensitive nature. This option enables low barrier to entry to get as many users as possible onto the system with as little administrative overhead as possible. You will always be able to revoke a user’s access at any time and audit their usage of any applications or services. Details: Multi-factor authentication can be enabled per client, by default it will follow a user’s preference. A user’s session is shared between apps unless that app’s client has Single Sign-On set to ‘never’ A user’s session lasts up to 14 days Multi factor authentication must be used to log in after every 30 days if enabled
Strict
You should choose this option if you need the minimum ‘blast’ radius from a compromised device. By reducing the sharing of sessions between applications, minimizing multi-factor authentication duration and requiring frequent logins you can guarantee that in the event an employee’s device is compromised they cannot access anything other than what the employee is currently logged into. You will always be able to revoke a user’s access at any time and audit their usage of any applications or services. Details: Multi-factor authentication can be enabled per client, by default it will follow a user’s preference A user’s session is not shared between apps unless that app’s client has Single Sign-On set to ‘always’ A user’s session lasts at most 1 day Multi factor authentication must be used to log in every 7 days
Example Authentication Policy
Below is the expanded ‘strict’ example, applied to an organisation with solely Time-Based One Time.
First, groups. Rules in a group are evaluated until a match occurs. All groups are evaluated.
In this example, our first group is called ‘default authentication rules’. Inside it, the first rule:
“If Login.session.user_is_authenticated == False then Authenticate”
forces the user to get credentials.
Next, we disable single-sign-on and caching for strong-authentication clients, this forces the user to provide credentials each time to these sensitive apps.
“If Clients.single_sign_on == never && Login.session.user_is_authenticated_by_cache then Authenticate”
Now we check for > 1 day old (86400 s) cached credentials, and disallow
“If Login.session.single_sign_on_time > 86400 && Login.session.user_is_authenticated_by_cache then Authenticate”
Now, for any authentication client which forces a 2nd factor:
“If Clients.mfa_challenge == Always then Require 2nd Factor”
“If User.multi-factor.challenge_type in totp then Require 2nd Factor”
JSON API Example
The above ‘strict’ example looks as below in the API:
Authentication sessions identify users to Agilicus automatically so that they need not log in every time they try to access the system. This session is tied to a given browser/device. When users accesses the system from a new browser, or a new device, they will be prompted to log in. If their session has expired, users will be prompted to re-authenticate.
A session expires according to the authentication policy rule which controls its lifetime. The rule, expressed in seconds, constrains for how long the session is valid.
For the policy shown in above screenshot, session is valid for 1209600 seconds, or 14 days. Users will be required to reauthenticate every 14 days. This particular rule fires for users who have authenticated, but whose session was created more than 1209600 seconds ago. The action is Authenticate, meaning that when the rule matches, users are forced to authenticate.
Configuring Maximum Session Duration
To configure the maximum session duration, either apply a new preset, or edit the “User has successfully authenticated” rule’s “login session single sign on time” condition. For the preset, configure the “Sessions valid for” field.
For the existing rule, choose “configure condition”.
Then edit the value in the “Configure condition details” section. Do not change its operator.
Note that the minimum effective value is 86400 seconds, or one day.
On initial product signup you may be offered the ability to “Sign in with Microsoft (Azure, Skype, …)”. This option is a zero-configuration setup, and will allow you to assign users from any Microsoft certified source. This includes your own Active Directory, but also can include XBox Live, Skype, hotmail, etc.
Once you have signed up, you have a choice. You can continue to use this pre-setup shared Identity Provider. Or, you may configure the system to use your own Azure Active Directory.
The pro/con of each approach are discussed below.
As an administrator, you will be granting access to this shared Microsoft Issuer. The first time you sign in you will see a screen as below.
In it, you are requested to
This screen requests 2 permissions:
“Sign you in and read your profile”. This is granting the Agilicus platform to the following information, called ‘profile’ in OpenID terminology (for more information see Section 2.4 “Scope Values” of the OpenID Connect specification).
First Name
Last Name
Email
Maintain access to data you have given it access to. This is commonly called a ‘refresh’ token, and it allows the platform to cache access so you can sign in a second time on the same device without re-authenticating.
There is a 3rd box, ‘Consent on behalf of your organisation’. Checking this will ensure that end users are not asked these questions.
If you use the shared Identity provider you can set the theme & branding information on the initial Agilicus screen. However, once the user chooses ‘SIgn in with Microsoft’ there is no option to set branding information. The end user will see a a generic Microsoft screen.
Consideration: Auto Create users
In the event you create and assign your own Azure Active Directory Application for Agilicus you can use ‘auto create’ users. In this model you may choose to auto-trust. “If my Active Directory trusts the user, so will Agilicus”.
The ‘Group’ concept exists in several locations in Agilicus AnyX. It can apply to users (giving the ability to simplify permissions), to resources (also giving the ability to simplify permissions), and, to the system level (given administrative distinctions).
System Groups
There are 3 system groups used to govern administration:
‘admin’: a global admin, can do any action
‘apps-admin’: can create / update any resource (SSH, Desktop, Share, …)
‘users-admin’: can add/delete users, assign permission to them.
A service account is a specific subset of permissions assigned to a non-human user. The most common use is the Agilicus Connector.
Service accounts (typically) do not sign in via an OpenID Connect web-based identity-provider. Instead they use an ‘Authentication Document’ which is a cryptographic proof of identity and scopes combined, which is periodically refreshed.
Service accounts behave the same as all other users for the sake of permission assignment.
When you install your Agilicus Connector, a service account is created for it at that time. If you delete the Connector, you can delete the service account for it. WARNING: do not delete the service account if the Connector is still in use (it will stop functioning).
Service accounts show up in the audits as any other user: all actions are audited individually.
Service account’s have a name which is similar to an email address, in the format of:
An Identity provider holds the user database, and, authenticates users against it. Agilicus supports any OpenID-Connect based identity provider. This includes Okta, Microsoft, Google, etc.
An Identity provider holds the user database, and, authenticates users against it. Agilicus supports any OpenID-Connect based identity provider. This includes Okta, Microsoft, Google, etc.
Most customers will use the ‘Shared Identity’ feature which is zero-touch configuration. However, some will wish to implement custom rules inside their identity provider, requiring creation of a ‘new application registration’.
To add a custom provider, select ‘add provider’
You will see two choice: ‘Azure Active Directory’ (which will give you a guided walk through), or, ‘Other’. In other you will configure a row in a table.
Once you have added the row, you have these columns:
name — what the user will see on the sign in page
issuer — the URI (e.g. https://login.microsoftonline.com/TENANTID/v2.0)
icon — from your theme, e.g. google, microsoft
client id — as given by your identity provider (e.g. TENANTID)
secret — as given by your identity provider
auto-create — if set, users will be created automatically in Agilicus if they can sign in via this upstream identity provider. Do not use with public providers.
type — Generic (or Microsoft for non-compatible extensions)
offline consent — if true, ask for consent to do refresh flow (aka offline)
request user info — if true attempt to fetch additional user info (e.g. group mappings)
issuer external host — leave blank typically
username key — blank (or e.g. username, email, etc)
email key — typically email
verifies email — if set the upstream provider forces verification of email address
redirect uri — the redirect URI to your Agilicus-provided authentication federation. Typically https://auth.ca-1.agilicus.ca/callback
You may also use the action-button (3-dots) to configure group mappings, these will import groups from your upstream identity provider automatically
The Authentication audit provides a trail of all attempts by users (or service accounts) to prove their identity. This authentication process can have multiple steps, depending on authentication rules and upstream identity providers.
The Authentication audit provides a trail of all attempts by users (or service accounts) to prove their identity. This authentication process can have multiple steps, depending on authentication rules and upstream identity providers.
Not all stages will have all fields available. Each step has a timestamp (in UTC), an ‘Email’ (user), ‘Source IP’, Stage, Event, and Application Name (authentication client).
Authentication audits are also available via the API where additional columns may be extracted.
user_id: string
The system-local id of the user performing the action.
upstream_user_id: string
The id of the user in the upstream system, if available.
org_id: string
The id of the organisation of the issuer against which the user is authenticating.
org_name: string
The name of the organisation of the issuer against which the user is authenticating.
time: date-time
the time at which the record was generated.
event: string
The event which generated the record. The meaning of the event depends on the stage where it occured.
source_ip: string
The IP address of the host initiating the action
token_id: string
The id of the token issued or reissued as part of the authentication.
trace_id: string
A correlation ID associated with requests related to this event
session: string
The session associated with tokens related to this event. This can be used to tie the actions undertaking by requests bearing tokens with the same session back to the authentication events which created the tokens.
issuer: string
The issuer the user logged in to.
client_id: string
The client id of the web application, client, etc. that the user is logging in with. Note that this is not the id of the IssuerClient, but rather the id presented to the authentication system to identify that client. This corresponds to name in the IssuerClient.
application_name: string
The name of the application within the system the user is logging in to.
login_org_id: string
The id of the organisation that the user is logging in to. Note that this is disctinct from the org_id field, which is tied to the issuer. This id is tied to the application.
login_org_name: string
The name of the organisation that the user is logging in to. This corresponds to login_org_id.
upstream_idp: string
The name of the identity provider proving the identity of the user.
stage: string
The stage of the login process. This identifies where in the pipeline the event was generated.
user_agent: string
The user agent of the client used to perform the login.
Auto-Create Users From Specific Domain With Google Workplace
The Agilicus Managed Upstream Providers option of ‘Google’ allows users to sign in with GMail and Google Workplace (G Suite) with zero-configuration. In some circumstances (for example, to enable the use of auto-create locked to a specific domain) you may wish to create your own Google Identity Provider setup.
Auto-Create Users From Specific Domain With Google Workplace
The Agilicus Managed Upstream Providers option of ‘Google’ allows users to sign in with GMail and Google Workplace (G Suite) with zero-configuration. In some circumstances (for example, to enable the use of auto-create locked to a specific domain) you may wish to create your own Google Identity Provider setup.
To do so, we will use the Google Console, create a Credential, OAUth2, Web application, and from there obtain a client-id and client-secret.
We will then configure the list of acceptable domains which may use it, and cross-configure this information into the Agilicus admin portal.
There is no general requirement to create your own Credentials in Google: do so if you wish finer-grained control by e.g. restricting source domain, or if you have specific audit requirements.
Create a new OAUTH2 client of type Web Application.
Give this “credential” a name. Add a redirect URI of https://auth.ca-1.agilicus.ca/callback
At this stage you will be given two facts (client ID, client secret). You will now enter these into the Agilicus Admin portal.
In the Agilicus Admin portal, add a new Identity Provider of type ‘Other’ (this is a generic OpenID Connect Identity Provider).
Enter a name (your users’ will see this, so e.g. “Agilicus Google Workplace”), the Issuer url (https://accounts.google.com), the Client ID (from above) and the Secret (from above).
You may wish to enable auto-create on this Identity Provider, in which case authenticated users will be automatically provisioned.
At this stage, you may wish to enable “Authorized Domains” in your Google Workplace settings.
Users may now sign in to the system via this Identity Provider.
In some circumstances, a local, on-premise identity provider is the best source available. The Agilicus Connector facilities, providing a bridge between a local machine acting as an authentication proxy, and a proper OpenID Connect web public interface. The user credentials are encrypted end-to-end, from the user’s browser to the backend.
Care must be taken when using Onsite Identity. If the connector facilitating is removed, any user with this as a sole identity source will be unable to sign in.
