Technical Tip: FortiClient SAML Authentication Configuration Demystified

[MZBZ]

Description	This article describes the role of HTML renderers (browsers) in FortiClient when establishing VPN tunnels with SAML authentication. FortiClient displays the IDP login page to the end user using either internal or external browsers, depending on the VPN type, FortiOS version, and login context.
Scope	FortiClient, FortiClient EMS, FortiGate, FortiSASE.
Solution	When establishing a VPN tunnel connection with SAML authentication, FortiClient must present a SAML authentication request (idP authentication page) to the end user. These idP authentication pages can be either basic or complex HTML webpages (with complex webpages including JavaScript, CSS, and other elements). Therefore, FortiClient requires an HTML renderer to display these pages. An HTML renderer is essentially a web browser, so FortiClient relies on web browsers to provide access to the idP login page for the end user. Depending on the VPN technology (SSL or IPsec), FortiGate FortiOS version, the timing of the VPN connection request (before or after logging into the Windows OS), and FortiClient version, different options are available. From a FortiOS and FortiClient perspective, two major categories of browsers are available: Internal browsers are built-in and embedded into FortiClient. External browsers are the user's default web browsers (such as Firefox, Chrome, Opera, Edge, Brave, Vivaldi, and Safari, etc.). FortiClient Internal Browsers: <use_external_browser>0</use_external_browser>. FortiClient supports three types of internally embedded browsers: WebBrowser Control (Supported by FortiClient v7.0.0+, v7.2.0+, v7.4.0+): XML tags: FortiClient v7.0.0-10: <use_external_browser>0</use_external_browser> FortiClient v7.0.11+: <use_gui_saml_auth>0</use_gui_saml_auth> FortiClient v7.2.0-3: <use_external_browser>0</use_external_browser> FortiClient v7.2.4-8: <use_gui_saml_auth>0</use_gui_saml_auth> FortiClient v7.2.9: <use_gui_saml_auth>0</use_gui_saml_auth> and <use_webview2_saml_auth>0</use_webview2_saml_auth> FortiClient v7.4.0+: <after_logon_saml_auth>2</after_logon_saml_auth> <before_logon_saml_auth>2</before_logon_saml_auth> WebBrowser Control refers to a Microsoft product available in Microsoft's .NET Windows Forms. It relies heavily on Windows Internet Properties settings (Inetcpl.cpl) and is associated with Microsoft Internet Explorer. If JavaScript errors occur while accessing the idP login prompt, they are likely caused by Windows Internet Properties security settings. These errors resemble the JavaScript errors seen in older versions of Internet Explorer. WebBrowser Control Overview - Windows Forms .NET Framework | Microsoft Learn Electron (Supported by FortiClient v7.0.11+, v7.2.4+, v7.4.0+): XML tags: FortiClient v7.0.0-10: Not Supported. FortiClient v7.0.11+: <use_gui_saml_auth>1</use_gui_saml_auth> FortiClient v7.2.0-3: Not Supported. FortiClient v7.2.4-8:  <use_gui_saml_auth>1</use_gui_saml_auth> (Applies to just SSLVPN; defined under <vpn> <sslvpn>) FortiClient v7.2.9:  <use_gui_saml_auth>1</use_gui_saml_auth> (Applies to SSLVPN and IPSec; defined under <vpn> <sslvpn>) FortiClient v7.4.0+:   <after_logon_saml_auth>1</after_logon_saml_auth> <before_logon_saml_auth>1</before_logon_saml_auth> Built on the Electron framework, this browser relies on the Chromium browser engine. It should not be confused with the Chrome web browser as an external browser: BrowserWindow | Electron. Microsoft Edge WebView2 (Supported by FortiClient v7.4.0+): XML tags: FortiClient v7.0.0-10: Not Supported. FortiClient v7.0.11+: Not Supported. FortiClient v7.2.0-3: Not Supported. FortiClient v7.2.4-8: Not Supported. FortiClient v7.2.9: <use_webview2_saml_auth>1</use_webview2_saml_auth> (Applies to SSLVPN and IPSec; defined under <vpn> <options>) FortiClient v7.4.0+: <after_logon_saml_auth>0</after_logon_saml_auth> Not Supported for <before_logon_saml_auth>. In FortiClient v7.2.9, when both <use_webview2_saml_auth> and <use_gui_saml_auth> are 1, webview2 is used for normal VPN (after logon), and Electron is used for before logon VPN. WebView2 is based on the Microsoft Edge browser but is not a full-fledged Microsoft Edge web browser. It should not be confused with Microsoft Edge as an external browser: Microsoft Edge WebView2 | Microsoft Edge Developer and Differences between Microsoft Edge and WebView2 - Microsoft Edge Developer documentation | Microsoft... It may require manual installation of the WebView2 Runtime: https://go.microsoft.com/fwlink/p/?LinkId=2124703. External Browsers: <use_external_browser>1</use_external_browser>. Using an external browser for SAML authentication requires FortiGate support. These external browsers include popular choices like Firefox, Chrome, Opera, Edge, Brave, Vivaldi, Safari, and others. SAML authentication for SSL VPN using external browsers requires FortiGate FortiOS v7.0.1+. Use a browser as an external user-agent for SAML authentication in an SSL VPN connection 7.0.1 | For... SAML authentication for IPsec VPN using external browsers requires FortiGate FortiOS v7.6.1+. For security reasons, external browsers are not supported for Before Logon VPN configuration. Additional Notes: The related settings are configured, controlled, and modified inside the EMS Web UI. However, the functionality on the endpoint is solely managed by FortiClient. If mixed versions of FortiClient are used with the same remote access (VPN) profile from EMS, different XML tags must be utilized to ensure compatibility with all FortiClient versions. If a tag is unsupported or unknown to a specific FortiClient version, it will be ignored. For example, EMS v7.4.2 supports FortiClient v7.0, v7.2, and v7.4. If these versions are used in the same environment with one VPN profile from EMS, it is necessary to use the <use_gui_saml_auth>, <before_logon_saml_auth>, or <after_logon_saml_auth> tags together. The following PowerShell one-liner can be used to check what framework is used for SAML authentication on the endpoint (FortiClient log level must be on Debug, which is configurable from EMS Web UI under endpoint system settings profile): Get-Content -Path "$env:localappdata\FortiClient\logs\trace\FortiTray.exe_FortiAuth.log" -Wait -Tail 30 | Select-String -Pattern "provider-name" AzureAdJoined devices: SAML authentication will be seamless and performed in the background if a Microsoft Windows OS is AzureAdJoined or has the Azure account added as a 'work or school account' and FortiClient is using the internal (embedded) browser Windows Forms WebBrowser Control. The 'Access work or school' Windows setting page is accessible from Settings App -> Accounts -> Access work or school. A direct shortcut is 'ms-settings:workplace' in the run window. This should not be mistaken with the Azure Auto Logon feature, which is based on the OAuth 2.0 authorization workflow with the Microsoft Graph REST API. Although this method is still seamless to the user, it is still based on SAML and requires full SAML configuration. Another alternative for seamless VPN connection on AzureAdJoined devices is to use OAuth 2.0 authorization workflow with the Microsoft Graph REST API based on custom redirect URI (ms-appx-web://microsoft.aad.brokerplugin/<Client_ID>). This method is NOT based on SAML and does not require SAML SSO (idP/SP) configuration on Azure or FortiOS (FortiGate configuration in newer versions is done with 'config user external-identity-provider'). However, the configuration in earlier versions of FortiOS is done under the same section as 'config user saml' with "set auth-url', which has been a source of confusion. The following command can be used to check the AzureAdJoined status of a device: dsregcmd /status The following command can be used to confirm if the endpoint has a user account connected as a 'work or school account' (even if it is NOT AzureAdJoined): dsregcmd /listaccounts Feature Availability and Configuration Matrix: Refer to the attached PDF file (Fortinet_FortiClient_SAML_Config_GUIDE_10_JAN_2025.pdf).  Linux, macOS, Android, and iOS: The internal browser frameworks discussed in this article are specific to FortiClient for Windows. On other operating systems, FortiClient utilizes different internal (built-in) browser frameworks. For all platforms, when configured to use an external browser for SAML authentication, FortiClient will invoke the default system browser to handle HTTP[S]:// links. However, on mobile operating systems like Android and iOS, specific limitations based on the Android API level or iOS security settings may affect this behavior. It is important to consult FortiClient and EMS documentation and release notes for specific cases. For example, in FortiClient v7.2.8 on macOS SSL VPN with SAML FIDO2 authentication only supports external browser au....