Skip to main content
Skip table of contents

Microsoft ADFS 2019

This is the procedure to integrate TrustBuilder multi factor authentication (MFA) service with Microsoft Active Directory Federation Services 2019 (ADFS 2019) → Windows Server 2019.

This documentation explains how to use TrustBuilder MFA with various existing products running as a relying party trust with ADFS 2019 (examples : MS SharePoint, MS Office 365, etc…).

ADFS 2019 is fully integrated in Windows Server 2019 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 inWebo ADFS plugin (.exe file): you'll need to install the plugin on your ADFS server. You can download it here. Once downloaded, upload it to any accessible place from your ADFS server.

  • A PKCS12 Certificate file for the InWebo 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 inWebo 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 inWebo 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 inWebo authentication to be transparent for the end user. No pin code is asked in this case. inWebo 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 inWebo user login.

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

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

Directory Search Path

For multiple Active Directory forests, when using the "SamAccountName" attribute login, if needed you can provide the Global Catalog search path: "GC://DC=mycompanu,DC=com" 

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

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: Customize the HTTP security response headers

As you are installing inWebo ADFS plugin on Windows Server 2019, you should let your ADFS contact the inWebo domain (http://ult-inwebo.com). ADFS 2019 added the functionality to customize the HTTP security response headers sent by ADFS. This is accomplished through the introduction of two new cmdlets: Get-AdfsResponseHeaders and Set-AdfsResponseHeaders.

You should add the address https://ult-inwebo.com to the default CSP header for ADFS on 2019 Windows server. (By default on Windows 2019 → Content-Security-Policy: default-src ‘self’ ‘unsafe-inline’ ‘’unsafe-eval’; img-src ‘self’ data:;)

To customize the HTTP security response headers to add inWebo in Cross Origin Resource Sharing (CORS) and Content Security Policy (CSP) headers in ADFS 2019, paste the following PowerShell Command lines :

  • Change HTTP security settings for inWebo (restaining the access in HTTPS):

    POWERSHELL 
    Set-AdfsResponseHeaders -SetHeaderName "Strict-Transport-Security" -SetHeaderValue "max-age=31536000; includeSubDomains"

  • Modifying Content-Security-Policy values to accept script from ult-inwebo.com:

    POWERSHELL 
    Set-AdfsResponseHeaders -SetHeaderName "Content-Security-Policy" -SetHeaderValue "default-src 'self' 'unsafe-inline' 'unsafe-eval' https://ult-inwebo.com;"

  • Modifying CORS values to accept access to ult-inwebo.com:

    POWERSHELL 
    Set-AdfsResponseHeaders -EnableCORS $true
Set-AdfsResponseHeaders -CORSTrustedOrigins https://ult-inwebo.com

  • Checking the current HTTP security settings:

    CODE 
    Get-AdfsResponseHeaders

The response headers should look like this:

As you can see, ult-inwebo.com is now a trusted domain.

  • Restart the ADFS service.

Step 4: Enable inWebo Authentication provider

  • Log onto your ADFS server.

  • Open the ADFS management console.

  • 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 5: 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 inWebo 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 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

    JS 
    IW_jQuery(document).ready(function() {

	var s = document.getElementById("iwnewbrowser");
	var f = document.getElementById("standardlogin");
	var h = document.getElementById("helium_form");
	var m = document.getElementById("iwmobileotp");
	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