OpenVPN® with SAML Authentication

Overview

There are two methods to authenticate a VPN client: Okta API Token or an Aviatrix SAML client.

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

The Aviatrix user VPN is one of the OpenVPN® 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 SAML client to authenticate an IdP. When a SAML client is used, the Aviatrix Controller 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:

  1. The Aviatrix Controller is set up and running.
  2. You have a valid IdP account with admin access.
  3. You have Downloaded and installed the Aviatrix SAML client.

Aviatrix Controller

If you haven’t already deployed the Aviatrix Controller, follow these instructions to deploy the Aviatrix Controller.

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. For a list of supported IdPs, see IdP-specific SAML App Integration.

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 8 parts:

  1. Create a temporary Aviatrix SP Endpoint for Aviatrix.
  2. Create a SAML IdP App with specific IdP.
  3. Retrieve IdP Metadata from IdP.
  4. Update the Aviatrix SP Endpoint with IdP metadata.
  5. Test the SAML Integration.
  6. Launch an Aviatrix Gateway.
  7. Create Aviatrix VPN user(s).
  8. Test VPN Connectivity.

Creating a Temporary Aviatrix SP Endpoint

Note

This step is usually completed by the Aviatrix admin. This endpoint will be updated later on in the guide; at this step, we will be using 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.

  1. Log in to the Aviatrix Controller and go to OpenVPN > Advanced > SAML > click + Add New.

    Field Value
    Endpoint Name Enter a unique identifier for the service provider.
    IPD Metadata Type Text or URL (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.
    Access (Removed from 6.0 and later) Select admin or read-only access.
    Custom SAML Request Template For now leave blank, depending on your specific IdP, you may have to mark this checkbox.

    create-endpoint

Note

Each endpoint only supports one type of access. If you need admin and read-only access, create two separate SAML apps.

  1. Click OK.
  2. Depending on your IdP provider, you may need to upload SP metadata. After temporary SAML endpoint is created:
  • Right-click the SP Metadata button next to the SAML endpoint and 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

Note

This step is usually done by the IdP administrator. This section shows only a generalized process for creating a SAML application. Refer to the IdP-specific SAML App Integration section 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*

  2. Audience URI(Entity ID)*

  3. SP Metadata URL*

  4. SP Login URL*

  5. Default RelayState* = <empty>

  6. Application username = IdP username

    You can find these values in your Controller. Go to Settings > Controller > select the SAML Login tab. * Assertion Consumer Service URL (ACS URL) - Click SP ACS URL in the URL column of the SAML Endpoints table. * Audience URI (Entity ID) Click SP Metadata to open the metadata. Find this URL listed by “entityID.”

    imagespmetadata

    • SP Metadata URL - Click SP Metadata to open this metadata. You can also click the download icon next to SP Metadata in the SAML Endpoints table to download the metadata file.
    • SP Login URL - Click Test to open this URL.

    RelayState is currently not used by the Aviatrix SP.

values-in-controller

The following SAML attributes are expected:

  1. FirstName
  2. LastName
  3. Email (unique identifier for SAML)

Note

These values are case sensitive.

IdP-specific SAML App Integration

Note

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

These are guides with specific IdP’s that were tested to work with Aviatrix SAML integration:

  1. AWS SSO
  2. Azure AD
  3. Centrify
  4. Google
  5. Okta
  6. OneLogin
  7. PingOne

Other tested IdPs include: VmWare VIDM, ForgeRock’s OpenAM etc.

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. AWS SSO - provides IdP metadata URL, needs a custom SAML request template, and will need to provide SP metadata file from Aviatrix.
  2. Azure AD - provides IdP metadata URL and needs a custom SAML request template.
  3. Centrify - provides IdP metadata URL and will need to provide SP metadata text from Aviatrix.
  4. Google - provides IdP metadata text.
  5. Okta - provides IdP metadata text.
  6. OneLogin - provides IdP metadata URL.
  7. PingOne - provides IdP metadata URL.

Updating Aviatrix SP Endpoint

Note

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. In your Controller, go to OpenVPN® > Advanced > on the SAML tab, click + Add New.

    Field Description
    Endpoint Name Unique name that you chose in the “Creating a Temporary Aviatrix SP Endpoint” section above.
    IPD Metadata Type Text or URL (depending on what was provided by the SAML provider).
    IdP Metadata Text/URL Paste in the IdP metadata URL/Text copied from the SAML provider configuration.
    Entity ID Select Hostname or Custom.
    Custom Entity ID Only visible if the Entity ID is Custom.
    Access Select admin or read-only access.
    Custom SAML Request Template Depending on your specific IdP, you may have to mark this checkbox. Refer to IdP-specific Integration.

Note

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

Note

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

  1. Log in to the Aviatrix Controller.
  2. Select OpenVPN® > Advanced on the left sidebar.
  3. Stay on the SAML tab.
  4. Select the row that was created in the previous step (that includes your endpoint name).
  5. Click on the Test action.
  6. You should be redirected to the IdP. Now, you can log in and should be redirected back to the Controller.

Launching Aviatrix Gateway

Note

This step is usually completed by the Aviatrix admin.

  1. In your Controller, go to Gateway > click + New Gateway.

  2. Select the appropriate values for where to provision this Gateway.

  3. Mark the VPN Access checkbox, the Advanced checkbox, and then the Enable SAML checkbox.

    gateway-options

  4. Leave the default settings for everything else.

  5. Click OK to launch the gateway.

Creating VPN User(s)

Note

SAML supports shared certificates. You can share the certificate among VPN users or create more VPN 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 OpenVPN > Profiles page. If preferred, this 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 the Controller, 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 of configuring at the Controller.

Multiple Profiles is supported when using Profile as attribute starting with release 5.4.

Multiple profiles can be added separated by commas. Note that mixing of base rules is not allowed.

The profile association can be verified from the Dashboard page after the VPN user has connected.

These are guides with specific IdP’s that were tested to work with Aviatrix SAML integration:

  1. Okta
  2. PingOne

OpenVPN is a registered trademark of OpenVPN Inc.