Aviatrix User VPN with SAML Authentication

There are two methods to authenticate a VPN client: password-based authentication or SAML.

Okta API Token or an Aviatrix VPN client.

This document shows you how to set up VPN authentication using an Aviatrix VPN client.

The Aviatrix user VPN is one of the UserVPN-based remote VPN solutions that provides a VPN client with SAML authentication capability.

This step-by-step guide shows you how to use an Aviatrix VPN client to authenticate an IdP. When a SAML client is used, the Aviatrix CoPilot acts as the service provider (SP) that redirects browser traffic from the client to the IdP for authentication.

For different IdPs, there will be links to each individual IdP integration.

Pre-Deployment Checklist

Before configuring the SAML integration between Aviatrix and your IdP, make sure the following is completed:

Aviatrix CoPilot is deployed.
You have an IdP account with admin access.
You have downloaded and installed the Aviatrix VPN client.

IdP Account

An identity provider (IdP) is any provider that supports a SAML endpoint like Okta, OneLogin, Google, AWS SSO, Azure AD, and PingOne. Administrator access is required to create IdP endpoints for SAML. See UserVPN Authentication for instructions for setting up your Aviatrix CoPilot to authenticate against an IdP.

Aviatrix VPN Client

All users must use the Aviatrix VPN client to connect to the system.

Download the client for your OS here.

Configuration

The configuration consists of eight steps:

Create temporary Aviatrix SP Endpoint for Aviatrix.
Create SAML IdP App with specific IdP.
Retrieve IdP Metadata from IdP.
Update Aviatrix SP Endpoint with IdP metadata.
Test SAML Integration.
Launch Aviatrix Gateway.
Create Aviatrix VPN user(s).
Test VPN Connectivity.

Creating a Temporary Aviatrix SP Endpoint

This step is usually completed by the Aviatrix admin. This endpoint will be updated later on in the guide; at this step, use placeholder values. Choose an endpoint name for your Aviatrix SAML endpoint which will be used throughout the guide. This guide will use aviatrix_saml_controller as an example for the endpoint name.

Go to Aviatrix CoPilot > CloudFabric > User VPN > select the Settings tab.
Under SAML, click + SAML Endpoint.

Field	Value
Name	Enter a unique identifier for the service provider.
Identity Provider Metadata Type	Select URL or Text, depending on what was provided by the SAML provider. For now, choose URL.
IdP Metadata Text/URL	IdP metadata URL/Text copied from the SAML provider configuration. For now, put in a placeholder URL, such as "https://www.google.com."
Entity ID	Select Hostname for now.
Sign Authn Requests	Sign the cert when requesting to IDP from client. Turn this setting on to have AuthnRequests sent from the Aviatrix Controller to the IdP signed by the Aviatrix Controller. The same Aviatrix Controller webserver certificate will be used to sign the request. The certificate is exported as part of the SP metadata. Turn this setting off if you do not need this setup for security or compliance.
Custom SAML Request Template	For now leave this setting off. Depending on your specific IdP, you may have to mark this checkbox.

Field

Value

Name

Enter a unique identifier for the service provider.

Identity Provider Metadata Type

Select URL or Text, depending on what was provided by the SAML provider. For now, choose URL.

IdP Metadata Text/URL

IdP metadata URL/Text copied from the SAML provider configuration. For now, put in a placeholder URL, such as "https://www.google.com."

Entity ID

Select Hostname for now.

Sign Authn Requests

Sign the cert when requesting to IDP from client.

Turn this setting on to have AuthnRequests sent from the Aviatrix Controller to the IdP signed by the Aviatrix Controller. The same Aviatrix Controller webserver certificate will be used to sign the request. The certificate is exported as part of the SP metadata.

Turn this setting off if you do not need this setup for security or compliance.

Custom SAML Request Template

For now leave this setting off. Depending on your specific IdP, you may have to mark this checkbox.

Click Save.
Depending on your IdP provider, you may need to upload SP metadata.

After a temporary SAML endpoint is created:

Right-click on the three dots next to the SAML endpoint and click Download SP Metadata. Save the file to your local machine.
Click SP Metadata and copy the SP metadata as text.

Creating a SAML App for Aviatrix with the IdP

This step is usually done by the IdP administrator. This section shows only a generalized process for creating a SAML application. See UserVPN Authentication for links to detailed steps with each particular IdP.

Create a SAML 2.0 app with the IdP Provider with the following values:

Assertion Consumer Service URL – This value is available in Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab. Find the SAML endpoint and click the three dots on the right.
Audience URI (Entity ID) - For custom Entity IDs, see Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab*. Find the SAML endpoint and click the Edit icon. The custom Entity ID is in the Custom Entity ID field.
SP Metadata URL - Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab.
SP Login URL – This value is provided by your IdP.
Default RelayState = Leave this value blank. RelayState is currently not used by the Aviatrix SP.
Application username – This is your IdP username.

The following SAML attributes are expected:

FirstName
LastName
Email (unique identifier for SAML)

These values are case-sensitive.

IdP-specific SAML App Integration

You will require administrator access to create IdP endpoints for SAML.

See UserVPN Authentication for instructions for each IdP.

Retrieving IdP Metadata

After creating the IdP, you need to retrieve IdP Metadata either in URL or text from the IdP application created in the previous step.

Azure AD - provides IdP metadata URL and needs a custom SAML request template.
Okta - provides IdP metadata text.
OneLogin - provides IdP metadata URL.

Updating Aviatrix SP Endpoint

This step is usually completed by the Aviatrix admin. Take note of the IdP Metadata type along with Text/URL your IdP provides, and if you need a custom SAML request template in the previous section.

Go to Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab.
Under SAML, click + SAML Endpoint.

Enter the following information:

Field	Description
Name	Unique name that you chose in the "Creating a Temporary Aviatrix SP Endpoint" section above.
IPD Metadata Type	Select URL or Text (depending on what was provided by the SAML provider).
IdP Metadata Text/URL	Paste in the IdP metadata URL or Text copied from the SAML provider configuration.
Entity ID	Select Hostname or Custom for the third-party endpoint you set up.
Custom Entity ID	Only visible if the Entity ID is Custom.
Custom SAML Request Template	If the default SAML request template does not fulfill the requirements of your IdP, use this option to customize it.

Field

Description

Name

Unique name that you chose in the "Creating a Temporary Aviatrix SP Endpoint" section above.

IPD Metadata Type

Select URL or Text (depending on what was provided by the SAML provider).

IdP Metadata Text/URL

Paste in the IdP metadata URL or Text copied from the SAML provider configuration.

Entity ID

Select Hostname or Custom for the third-party endpoint you set up.

Custom Entity ID

Only visible if the Entity ID is Custom.

Custom SAML Request Template

If the default SAML request template does not fulfill the requirements of your IdP, use this option to customize it.

Hostname is the default for Entity ID, but if you have other apps using the same hostname, use a custom Entity ID.

Testing the Integration

Have an instance of the VPN client running. If you do not, it might throw a warning.

Log into Aviatrix CoPilot > Cloud Fabric > UserVPN > select the Settings tab.
Under SAML, find the SAML endpoint. In the Test column, select the link provided.
You should be redirected to the IdP. Now, you can log in and should be redirected back to CoPilot.

Launching Aviatrix Gateway

Launch a VPN gateway [link]. See UserVPN Gateway Guide.

Creating VPN User(s)

Create UserVPN users.

Testing VPN Connectivity

Download and install the Aviatrix VPN client for your platform from here.
Launch the Aviatrix client and load the certificate ("Load config")that you downloaded/received from email on the Testing the Integration" section above.
Click Connect. This should launch the browser instance and prompt you for authentication, if not already logged in.
If the connection is successful, the client icon should turn green.
You can ensure VPN connectivity by trying to ping the private IP of the gateway you launched or any other instance in the same cloud network.

SAML Profile as an Attribute

The VPN user gets a VPN profile rule configured to the one that is attached to the VPN User from the CoPilot > CloudFabric > UserVPN > Profiles tab. This Profile can also be passed as attribute from the IDP. The IDP could send the "Profile" attribute along with the existing "FirstName," "LastName," and "Email" attributes.

If the "Profile" attribute is set and the value sent from the IDP matches with any of the profile names configured from CoPilot, the profile rules are applied accordingly. Note that if the IdP sends an invalid or empty Profile attribute, the default profile association is used.

This way Profile associations can be configured at IDP instead in CoPilot.

Multiple Profiles are supported when using Profile as attribute.
Multiple profiles can be added. Note that mixing of base rules is not allowed.
The profile association can be verified from the Aviatrix CoPilot dashboard after the VPN user has connected.