Skip to main content
Skip table of contents

Microsoft ADFS 3.0 and ADFS 4.0

This is the procedure to integrate TrustBuilder MFA with:

  • Microsoft Active Directory Federation Services 3.0 (ADFS 3.0) → Windows Server 2012 R2

  • Microsoft Active Directory Federation Services 4.0 (ADFS 4.0) → Windows Server 2016

If you want to integrate TrustBuilder MFA service on Windows Server 2012, see Microsoft ADFS 2.0 integration documentation.

If you want to integrate TrustBuilder MFA service on Windows Server 2019, see Microsoft ADFS 2019 integration documentation.

This documentation details how to integrate TrustBuilder MFA with various existing products running as a relying party trust with ADFS 3.0 and ADFS 4.0 (examples : MS SharePoint, MS Office 365, etc…).

  • ADFS 3.0 is fully integrated in Windows Server 2012 as a role to be activated on Server Manager.

  • ADFS 4.0 is fully integrated in Windows Server 2016 as a role to be activated on Server Manager.

Prerequisites

Before you start, please ensure that the following requirements are fulfilled.

  • A TrustBuilder MFA service with administrator rights (if you don't have any TrustBuilder MFA service yet, you can register for a trial account here).

  • Firewalls/TCP Filtering: your ADFS server will need to communicate with the TrustBuilder Cloud service. Thus, you have to open the network stream and route TCP packets from your ADFS server to api.myinwebo.com on HTTPS port (443)

  • The TrustBuilder ADFS plugin (.exe file): you'll need to install the plugin on your ADFS server. You can download it directly here. Once downloaded, upload it to any accessible place from your ADFS server.

  • A PKCS12 Certificate file for the TrustBuilder Web Services API Access. You should download it from your Administration Console following these steps :

    • Go to the 'Secure Sites' tab and click on “Download a certificate for API access”.

    • As it is an authentication certificate, set the certificate rights to ‘Yes’ for Authentication and to ‘No’ for Provisioning.

    • Enter a passphrase (7 characters or more).

    • Define a validity period (10 years by default).

    • Choose “PKCS12 format (.p12)”.

    • Click the “Download” button.

  • TLS 1.2 is required (see “Updating TrustBuilder ADFS plugin version” sub-section below).

Installation

Step 1: Create a secure site 

  • Open a browser and login to your administration console.

  • Go to the “Secure Sites” tab.

  • Click on “Add a secure site of type…” and choose “Web Service Connector”.

  • In the opening window, enter the following properties for the secure site:

    For ADFS authentication, it's mandatory to fill the following fields:

    • Called URL: https://<your_ADFS_server>/yourApp

    • Authentication page: //<your_ADFS_server>/adfs/ls* (info) If this path does not work, it may be related to your custom ADFS configuration. Please try //<your_ADFS_server>/adfs/*

    • Wildcard used in path: Yes

    • Form name: loginForm

    • Login field name: heliumlogin

    • Password field name: token

  • Click on “Add”.

  • Click the “Browser token activation” button.

  • Copy the "Bookmark alias" long string to your clipboard. (32 char string)

Step 2: Install the inWebo ADFS plugin on your ADFS server

If you have several ADFS servers in your farm, the TrustBuilder ADFS plugin must be installed on each server.

  • Create a C:\InWebo directory on your ADFS server.

  • Copy the InWebo PKCS12 API certificate file (format PKCS12) to the C:\InWebo directory (See the “Prerequisites” section).

  • Launch the inWebo plugin .exe file you have previously downloaded (See the “Prerequisites” section).

  • Enter “C:\InWebo” for target destination folder.

  • Specify your inWebo properties:

Setting

Description

Service

Enter your Service ID

You can retrieve your Service ID in the administrator console’s header.

Enter your Bookmark Alias

Paste the Bookmark Alias (See the “Step 1: Creating a secure site” sub-section)

Certificate

Path to your InWebo Certificate

Enter C:\InWebo\<cert_name>.p12 or browse for it

Certificate Password

Enter the passphrase previously defined (See the “Prerequisites” section > “PKCS12 Certificate file” )

Browser Token

This setting depends on your service type:

  • Standard service, must be 'Virtual Authenticator'.

  • White Label service, must be 'Helium'.

Services created before May 10 2016, both values (Virtual Authenticator or Helium) are acceptable (if the chosen token is activated on the service)

PIN mode

This parameter is useful to override the global service pin parameter:

  • Ask for pin: the plugin will use the global service policy.

  • Force no pin: must be set if your global service policy is set to pin activated, and you want TrustBuilder authentication to be transparent for the end user. No pin code is asked in this case. TrustBuilder is used as a second factor only.

AD Attribute for login

Select the AD attribute to use during the user authentication process. Note that the AD attribute selected must match the TrustBuilder MFA user login.

  • userPrincipalName (UPN): the AD username 'user@domain.ext' form is used as the TrustBuilder MFA user login.

  • SamAccountName: the short AD username 'user' form is used as the TrustBuilder MFA user login.

Directory Search Path

For architecture with multiple Active Directory forest trust, you can provide the Global Catalog search path to point to each domain of the forest trust so the plugin can search users in each domains: "GC://DC=companyA,DC=com;GC://DC=companyB,DC=com" .

  • Once all settings are correct, click the 'Install' button.

  • Restart the ADFS services.

The inWebo ADFS plugin installation is successful.

 The service account that runs ADFS Federation Service must have write rights in the plugin directory.

Step 3: Enable TrustBuilder Authentication provider

  • Log onto your ADFS server.

  • Open the ADFS management console.

If you want to limit the TrustBuilder application to some users, in the Edit Global Authentication Policy window, add the required users and groups (optional). Depending of your ADFS version you can also do that through the Relying Party Trust configuration (see step 4 below).

ADFS 3.0 (Windows server 2012)

  • Go to Authentication Policies folder > “Multi-factor Authentication” section.

  • Click on “EDIT” the Global Settings.

  • Enable “inWebo Authentication Provider”.

  • You should now see “inWebo Authentication Provider” in the “Multi-Factor authentication settings” list of your ADFS management console.

ADFS 4.0 (Windows server 2016)

  • Go to Service > “Authentication Methods” folder > “Multi-factor Authentication” section.

  • Click on “EDIT” the Authentication methods and go to the “Multi-factor” tab.

  • Enable “inWebo Authentication Provider”.

  • You should now see “inWebo Authentication Provider” in the “Multi-Factor authentication” tab.

Step 4: Configure Relying Party Trust to be protected by TrustBuilder MFA

  • In the ADFS management console, go to Relying Party Trusts. You see a list of your ADFS applications.

  • Right-click on the application you want to be protected by TrustBuilder MFA.

  • Choose Edit Access Control Policies.

  • Choose a policy that includes MFA, for example the default policy “Permit everyone and require MFA” (or any other customized Access Control Policy requiring MFA) and click on “Apply”.

You can edit and create an Access Control Policy. For example, you can choose a specific user/group to be concerning by the policy. It is useful in test case for example.

The selected applications will be protected by the chosen Access Control Policy, asking to perform a MFA.

Configuration

Moving the inWebo log storage to another destination

inWebo.log4net file modification:

You will find this file at the root of the inWebo directory "C: \ inwebo"

In this file, you can modify the line:
<file value = "C: \inWebo\inwebo.log"\>
with the destination path you have chosen for your logs

You must restart the ADFS service for the change to the log storage path to take effect.

Updating the inWebo ADFS plugin

In order to strengthen its platform, inWebo supports TLS v1.2 flows on all its services. A transition will take place from July 2021 to December 2021 with the objective of closing all TLS v1 and 1.1 flows by December 31, 2021.

If you are using an obsolete SSL protocol (TLS 1.0 and TLS 1.1), you should upgrade the inWebo ADFS plugin version. Read the following procedure.

The up-to-date version of the ADFS plugin is available for download here. To check your current ADFS plugin version, go to C:\inwebo directory > inwebo-install.log file.

  • Step 1: preserve current state and data

    • If possible, take a VM Snapshot to do a rollback if needed.

    • Copy the current C:\inwebo directory and paste it in C:\inwebo_OLD.

    • Open the inwebo.config file.

    • Copy (or write down) the inWebo plugin properties: Service ID, Bookmark Alias, inWebo Certificate path and password, AD attribute, PIN Mode, BrowserToken.

  • Step 2: in ADFS management, disable inWebo as an authentication provider.

    • for ADFS 3.0: go to Authentication Policies folder> “Multi-factor Authentication” section. Click on “EDIT” the Global Settings and disable “inWebo Authentication Provider”.

    • for ADFS 4.0: go to Service > “Authentication Methods” folder > “Multi-factor Authentication” section. Click on “EDIT” the Authentication methods and go to the “Multi-factor” tab. Disable “inWebo Authentication Provider”.

  • Step 3: Hot-swap uninstall of the previous inWebo plugin ⚠ Do not stop the ADFS service.

  • Step 4: install the up-to-date version of the inWebo ADFS plugin.

    • Hot-swap install the up-to-date version of the inWebo ADFS plugin. ⚠ Do not stop the ADFS service.

    • In inWebo ADFS plugin installer, paste the properties previously retrieved from inWebo C:\inwebo\inWebo.config.

  • Step 5: in ADFS management, enable inWebo as an authentication provider.

    • for ADFS 3.0: go to Authentication Policies folder folder > “Multi-factor Authentication” section. Click on “EDIT” the Global Settings and enable “inWebo Authentication Provider”.

    • for ADFS 4.0: go to Service > “Authentication Methods” folder > “Multi-factor Authentication” section. Click on “EDIT” the Authentication methods and go to the “Multi-factor” tab. Enable “inWebo Authentication Provider”.

  • Step 6: Restart the ADFS service.

  • Step 7: Check the ADFS service and the plugin inWebo display.

Force browser token and push authentication (3 factors)

To protect users against Man-in-the-middle attacks with push authentication method, we recommend a specific configuration involving web browser token (VA) and push notifications with TrustBuilder Authenticator. This configuration forces the browser token activation and enables the browser token to send notifications only. It adds an authentication factor: a hacker will not be able to send push notifications to a user without an enrolled browser token.

  1. Configure the browser token (VA) to send push notifications only:
    In the admin console, go to Service parameters tab, in Virtual Authenticator (browser) section. Set “Authentication with notifications allowed” to Yes and “Authentication with notifications only” to Yes

  2. Force users to activate browser token (VA):
    In inwebova.js file (located in the inWebo ADFS plugin installation folder), edit the script to force the authentication through Virtual Authenticator (VA). You should delete a few lines from the script (see comment lines 6 to 12 in the code below).
    Download the inwebova.js file set to force VA

    CODE 
    	iwstart("vaAuthenticate", function (iw, data) {
	    if (data.type == "success" && data.code == "ok" && data.action == "authentication") {
			iw.insertFields(data.result);
		}
	    if (data.type == "error" && data.code == "nok" && data.result.reason == "no_profile") {
			/* IW_jQuery('#heliumAuthenticate').attr('action', 'push_authenticate');
			m.style.display = "block";
			start_helium("heliumAuthenticate", function (iw, helium_data) {
			    if (helium_data.result == 'ok') {
			        iw.insertFields(helium_data);
				} else { */
					s.style.display = "block";
					f.style.display = "block";
					h.style.display = "none";
					m.style.display = "none";
				}

Troubleshooting

Allow read/write permissions to C:\inwebo for ADFS service account.

ADFS is unable to modify/read inWebo.config. Verify c:\inwebo\inWebo.log for read/write error. The following error message is displayed.

Error message displayed in inWebo.log:

TEXT 
2019-03-19 07:47:10,797 [5] ERROR inWebo.AuthenticationAdapter - System.UnauthorizedAccessException: Access to the path 'C:\inwebo\inWebo.config' is denied.
at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share, Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share, Int32 bufferSize, FileOptions options, String msgPath, Boolean bFromProxy)
at System.IO.FileStream..ctor(String path, FileMode mode)
at inWebo.AuthenticationAdapter.loadConfig()

To allow read/write permissions to C:\inwebo for ADFS service account, read the following procedure:

  • On the c:\inwebo folder change security settings (security tab of the folder) EDIT to change permissions

  • Click on "Add" to Security Objects and select "Object Types".

  • Check "Service Accounts" and type the ADFS service account created in Active Directory (ex: FsGmsa). Click on “OK”.

  • Check read/write options for the ADFS service and press "OK" to close.

The error message should have disappeared.

References

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/customize-http-security-headers-ad-fs

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close