Web Authentication Methods on macOS

When connecting to an OpenVPN server that requests web authentication, the macOS version of Viscosity will automatically display a dialog window with a number of different web authentication methods that can be used. Each method has different advantages and disadvantages, so we recommend selecting the method that works best for your use-case.

Open in Web Browser

The default web browser (typically Safari) will be used to load the website used for web authentication.

Advantages:

• If you're already logged into the website in your web browser then this existing session can also typically be used for VPN authentication, avoiding the need to log in again.
• Autocomplete and browser extensions are available for all users.
• WebAuthn and Passkeys can be used for all users.

Disadvantages:

• macOS will display a permission prompt every time web authentication takes place.
• Certain Viscosity integration features are not available (please see "Open in Viscosity" below).

Open in Web Browser (Private Mode)

The default web browser (typically Safari) will be used to load the website for web authentication. The website will be loaded in private browsing (aka incognito) mode.

Advantages:

• No macOS permission prompt when web authentication takes place.
• Autocomplete and browser extensions are available for all users (if enabled for private browsing mode in your web browser).
• WebAuthn and Passkeys can be used for all users.

Disadvantages:

• It is necessary to log into the authentication website every time. However, this can be advantageous if connecting to multiple VPN connections simultaneously using different credentials, or during testing.
• Certain Viscosity integration features are not available (please see "Open in Viscosity" below).

Open in Viscosity

Viscosity will load the website for web authentication in an internal web view.

Advantages:

• No macOS permission prompt when web authentication takes place.
• Improved integration with Viscosity, such as the web authentication prompt only appearing when required, token enrolment support, and website validation using a custom CA certificate.
• Better placement of the web authentication window.

Disadvantages:

• Existing sessions in your web browser cannot be used.
• Autocomplete and browser extensions are not available unless an "associated domain" has been configured via MDM.
• WebAuthn and Passkeys are not available unless an "associated domain" has been configured via MDM.

To always use the same authentication method without being prompted, tick the "Always use this method when authenticating" checkbox. If you have previously checked the "Always use this method when authenticating" option, but would like to be presented with the decision again, edit your connection in Viscosity and remove the command/s listed in the section below from the Advanced Commands section.

If you are not seeing the prompt when connecting to an OpenVPN server that requests web authentication, the server may be explicitly requesting "Open in Viscosity" mode by setting the "internal" flag. If you are a VPN administrator and wish for users to see the prompt, please remove this flag or specify the "external" flag.

Advanced Commands

If you are a VPN administrator and want to always use a particular method without users being prompted, you can use the "web-authentication-method" and "web-authentication-ephemeral" advanced commands.

To specify that a VPN connection should always use the "Open in Web Browser" option add the following command to the VPN configuration:

#viscosity web-authentication-method external

To specify the "Open in Web Browser (Private Mode)" option use the following commands:

#viscosity web-authentication-method external
#viscosity web-authentication-ephemeral true

To specify the "Open in Viscosity" option use the following command:

#viscosity web-authentication-method internal

macOS Permission Prompts

When using web authentication on a Mac, macOS may display one or more permission prompts. These prompts, including how to avoid them, have been documented below.

Viscosity.app Wants to Use example.com to Sign In

When using the "Open in Web Browser" method for authentication, macOS will prompt for permission to continue with the message "Viscosity.app" Wants to Use "example.com" to Sign In. The domain name in the message will be that of the website being used for authentication. This message comes from macOS, not Viscosity, and it will appear every time web authentication or re-authentication takes place when using the "Open in Web Browser" method.

To avoid this message, the "Open in Web Browser (Private Mode)" or "Open in Viscosity" methods can be used instead. macOS will not display the prompt when using either of these options. Please see the Web Authentication Methods section above for more information about each method.

Apple Feedback

macOS currently does not provide a way for users to permanently allow an application to use a specific domain, so this prompt appears every time web authentication (or re-authentication) occurs. We understand this can be disruptive, and we encourage affected users to submit feedback to Apple requesting an option to always trust certain domains for web authentication with a given application.

For example, you could include feedback similar to the following:

"Please provide a way to always trust specific domains on macOS when using ASWebAuthenticationSession, so the '"Application.app" Wants to Use "example.com" to Sign In' dialog does not appear every time. For example, a checkbox in the dialog window, or an option in System Settings. This should be available to all end users, including on non-MDM managed Macs."