Aviatrix SAML-Based Authentication

This step-by-step guide shows you how to use an Aviatrix VPN client to authenticate an IdP. When SAML is configured, your Aviatrix CoPilot acts as the Service Provider (SP) that redirects browser traffic from client to IdP (such as Entra ID) for authentication.

IdP integration documents:

Pre-Deployment Checklist

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

  1. Aviatrix CoPilot is deployed.

  2. You have an IdP account with admin access.

  3. 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, or Azure AD. 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

Download the client for your OS here.

Configuration

The configuration consists of eight steps:

  1. Create a temporary Aviatrix SAML Endpoint for Aviatrix.

  2. Create a SAML IdP App with a specific IdP.

  3. Retrieve IdP Metadata from IdP.

  4. Update Aviatrix SAML Endpoint with IdP metadata.

  5. Test SAML Integration.

  6. Launch Aviatrix Gateway.

  7. Create Aviatrix VPN user(s).

  8. Test VPN Connectivity.

Creating a Temporary Aviatrix SAML 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.

This SAML endpoint is selected when you create a VPN user from UserVPN > Users.

  1. Go to Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab.

  2. Under SAML, click + SAML Endpoint.

    Field Value

    Name

    Enter a unique identifier for the service provider.

    Identity Provider Metadata Type

    URL or Text

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

    If you select the Text option, you must enter the text and then any related xml code.

    Entity ID

    Select Hostname for now.

    Sign Auth Requests

    Sign the certificate when requesting to IdP from the client.

    Turn this setting on to have Auth Requests 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

    or now leave blank. Depending on your specific IdP, you may have to check this option. If so, replace the sample template with your own template.

  1. Click Save.

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

  2. After a temporary SAML endpoint is created:

    1. Right-click on the vertical ellipsis icon 25 next to the SAML endpoint and click Download SP Metadata. Save the file to your local machine.

    2. 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:

  1. Assertion Consumer Service URL – This value is available in Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab. Find the SAML endpoint and click the vertical ellipsis icon 25 on the right.

  2. 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.

  3. SP Metadata URL - Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab.

  4. SP Login URL – This value is provided by your IdP.

  5. Default RelayState - Leave this value blank. RelayState is currently not used by the Aviatrix SP.

  6. Application username – This is your IdP username.

The following SAML attributes are expected:

  1. FirstName

  2. LastName

  3. 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.

  1. Azure AD - provides IdP metadata URL and needs a custom SAML request template.

  2. Okta - provides IdP metadata text.

  3. OneLogin - provides IdP metadata URL.

Updating the Aviatrix SAML 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.

  1. Go to Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab.

  2. Under SAML, click the Edit icon edit icon next to the SAML endpoint you created earlier.

  3. Paste the IdP Metadata URL from the SAML provider into the Identity Provider Metadata URL field.

  4. Click Save.

Testing the Integration

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

  1. Log into Aviatrix CoPilot > Cloud Fabric > UserVPN > select the Settings tab.

  2. Under SAML, find the SAML endpoint. In the Test column, select the link provided.

  3. 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

  1. Download and install the Aviatrix VPN client for your platform from here.

  2. Launch the Aviatrix client and load the certificate ("Load config")that you downloaded/received from email on the Testing the Integration" section above.

  3. Click Connect. This should launch the browser instance and prompt you for authentication, if not already logged in.

  4. If the connection is successful, the client icon should turn green.

  5. 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.