Troubleshoot Android VPN app errors with SAML authentication

As an administrator, you can configure some Android Virtual Private Network (VPN) apps to use Security Assertion Markup Language (SAML) authentication. This requires a lot of configuration and coordination between the Identity Provider (IdP), the Service Provider (SP)—the VPN app in this case—, the PlayStore, and ChromeOS, making troubleshooting a complex process.

This article aims to assist in identifying the source of potential issues with this configuration.

Note: SAML configuration for VPN apps and integration with the IdP are outside the scope of this article and need to be handled solely with the relevant VPN app providers.

Configuring Android VPN apps for SAML authentication

SAML is a web protocol that requires a user agent—usually a web browser—to issue an authentication request to a SAML IdP. While the configuration steps can vary depending on the Android VPN app, the overall process is as follows:

1. The user opens the installed Android VPN app.
2. The user clicks Connect on the VPN app.
3. The VPN app directs them to the IdP sign-in webpage in a browser.
4. The user authenticates in the browser by using credentials, certificates, or a cookie if they have previously authenticated with the IdP.
5. The SAML assertion, containing the user authorization status, is forwarded back to the VPN app.

On Chromebooks, Android VPN apps can use either of the following browser options:

1. WebView
2. Android Chrome app
3. Native Chrome browser

Note: The best option depends on how your VPN and SAML are set up.

Configuration	VPN app WebView	Android Chrome app	Native Chrome browser
SAML auth with certificates	Certs need to be made available to the VPN app	Certs need to be made available to the VPN app	Works out-of-the box
SAML auth with credentials Note: The assumption is that the user already went through the SAML login flow on ChromeOS, most likely at the sign-in screen.	User needs to re-introduce credentials	User needs to re-introduce credentials	No user interaction required; uses the SAML auth cookies.
Lockdown mode interaction	Works out-of-the box	Not supported	Works in conjunction with the Always on VPN URL exceptions setting in the Google Admin console. For details, see policy AlwaysOnVpnPreConnectUrlAllowlist.
Special ChromeOS considerations	None; same setup as Android	None; same setup as Android	The SAML assertion needs to be re-directed back to the Android VPN app from ChromeOS.

Troubleshooting issues specific to ChromeOS

The VPN never finished connecting

This is the most common issue that happens when the VPN app uses the Chrome system browser to sign in to the IdP. It’s usually accompanied by a web navigation error in the system browser.

Root Cause

The SAML assertion result must be redirected back into the app after a successful authentication. Typically, this is achieved through an HTTP redirect that needs to be forwarded to the VPN app. This enables the app to transition to a connected or disconnected state based on the SAML authorization status.

While the VPN app declares an intent filter to signal to the Android system its intention to open the URL, this intent filter is only recognized by Android. The Chrome browser on ChromeOS is unaware of this intent filter.

Solution

To ensure the SAML assertion is correctly passed to the Android app, the redirect URL must use the intent:// scheme. Using a standard http:// URL causes the browser to try opening the URL itself, rather than forwarding it to the Android app for processing.

If you are using a third-party VPN app, contact your VPN service provider's support team to request that they implement this change.

The VPN connection requires the user to re-introduce credentials

Typically, after successful authentication with the IdP, a session cookie is issued. This cookie serves as a reminder of the user's authenticated status, eliminating the need for repeated credential entry when accessing different SPs.

Root Cause

Cookies are stored in the Chrome system browser and cannot be transferred to an Android appl. If the VPN app uses a WebView or delegates the authentication to another Android app, the user has to enter the SAML credentials again.

Solution

Due to network user data isolation and protection on Chrome OS, authentication cookies are not shared with VPN apps so users need to enter their credentials twice. This is expected behavior. To prevent confusion and concerns, it's important to inform employees about this requirement during the VPN setup process.

VPN lockdown is blocking SAML authentication via the system browser

Root Cause

When an Always-on VPN operates in lockdown mode, it blocks all connections that don't use the VPN app. SAML authentication, being a web-based process, typically functions exclusively within the VPN app's WebView in lockdown mode.

Solution

Since ChromeOS version 122, admins can use the Always on VPN URL exceptions setting in the Admin console to support SAML authentication using the system browser. Users can then navigate to any URL in this list while an Android Always-on VPN is set to lockdown mode and the VPN is not connected.

Certificate-based SAML authentication is not working

VPN authentication using a user certificate provisioned on the device is failing.

Root Cause

Certificates installed on ChromeOS are not automatically shared with Android apps.

Solution

In the Admin console, ensure that policy-provided ChromeOS Certificate Authority (CA) certificates, as well as user certificates, are shared with Android and Adndroid apps:

1. To give VPN app access to a policy-provided CA certificate, go to Devices > Chrome > Settings > Users & browser settings > Android apps and turn on Certificate synchronization.
2. To give VPN app access to a user certificate stored on an Android device, go to the relevant app page in the Admin console, access the configuration panel, and turn on Allow access to keys.