Skip to main content

​
Overview

This guide explains how to use Aviatrix CoPilot to configure your Aviatrix Controller to authenticate to an IdP. When SAML is used for Controller access authentication, the Controller acts as the Identity Service Provider (ISP) that redirects browser traffic from the client to the IdP (e.g., Okta) for authentication. CoPilot redirects to the Controller, which performs the SAML integration with the IdP. All CoPilot user logins are directed to the Controller, which handles all accounts and users. The Aviatrix CoPilot SAML login supports multiple SAML endpoints with varying access and different IdPs. Links to each IdP integration are provided below.
Setting up SAML authentication for the VPN client is something separate, although the interfaces are similar.

​
SAML Configuration Checklist

Before configuring SAML integration between Aviatrix and an IdP, make sure the following is completed:
  • The Aviatrix CoPilot associated with your Controller is up and running
  • You have a valid IdP account with admin access
An IdP refers to an identity provider for SAML. This could be any provider that supports a SAML endpoint such as Okta, OneLogin, or Azure AD. You will require administrator access to create IdP endpoints for SAML. Check IdP-specific SAML Integration to see a list of guides for supported IdP’s.

​
Configuring SAML Authentication

Follow these steps to configure Aviatrix to authenticate against an IdP:
  1. Creating a Temporary Aviatrix SAML Endpoint.
  2. Creating a SAML App for Aviatrix CoPilot with the IdP.
  3. Retrieving IdP Metadata.
  4. Updating the Aviatrix SAML Endpoint with IdP metadata.
  5. Validating the integration setup.

​
Creating a Temporary Aviatrix SAML Endpoint

This creates the SAML endpoint on the Controller.
This step is usually completed by the Aviatrix administrator. 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_copilot as an example for the endpoint name.
  1. Log in to Aviatrix CoPilot.
  2. Go to Administration > User Access > Access Management.
  3. Under Login Authentication, click +SAML Endpoint. image3-1-1 The Create SAML Endpoint dialog displays. Create SAML Endpoint dialog
  4. Enter the following information:
You can create the Aviatrix SAML endpoint using a placeholder or invalid IdP Metadata URL as the Identity Provider Metadata type, and the system will accept it. However, when authentication is attempted, an error message will appear because the metadata cannot be parsed.To avoid this, make sure to update the SAML endpoint with a valid IdP Metadata URL or XML from your Identity Provider before testing or enabling SAML login.Placeholder values such as https://www.google.com are intended for initial setup or demonstration purposes only.
Each endpoint only supports one type of access. If you need admin and read-only access, create two separate SAML apps.
  1. Click Save.
  2. Depending on your IdP provider, you may need to upload SP metadata.
    1. After the temporary SAML endpoint is created, click the vertical ellipsis threedot icon and select Download SP Metadata next to the SAML endpoint.
    2. Copy the SP metadata as text.

​
Creating a SAML App for Aviatrix CoPilot with the IdP

This step is usually done by the IdP administrator. This section shows only a generalized process for creating a SAML application.
Create a SAML 2.0 app in the IdP Provider (for example, Okta) with the following values from the SAML endpoint you created above:
  • Assertion Consumer Service URL: to obtain this, in Aviatrix CoPilot go to Administration > User Access > Access Management, click the vertical ellipsis threedot next to the SAML endpoint, and click Copy Assertion Consumer Service URL.
  • Audience URI (Entity ID)
  • SP Metadata URL
  • SP Login URL
  • Default RelayState = <empty>
The following SAML attributes are expected:
  • FirstName
  • LastName
  • Email (unique identifier for SAML)
These values are case-sensitive.
IdP-specific SAML App Integration
You 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:

​
Retrieving IdP Metadata

After creating the SAML app in the IdP as per the previous procedure, you need to retrieve IdP Metadata either in URL or text form from this SAML application.
  • Azure AD - provides IdP metadata URL and needs a custom SAML request template
  • Okta - provides IdP metadata URL
  • OneLogin - provides IdP metadata URL

​
Updating the Aviatrix SAML Endpoint

This step is usually completed by the Aviatrix administrator. 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 Aviatrix CoPilot go to Administration > User Access > Access Management.
  2. Under SAML, click the Edit icon edit icon next to the SAML endpoint you created earlier.
  3. Paste the IdP Metadata URL derived from the SAML provider application into the Identity Provider Metadata URL field.
  4. Click Save.

​
Validating the Integration

  1. Log out of Aviatrix CoPilot.
  2. Choose your SAML endpoint name from the dropdown box.
  3. Log in to Aviatrix CoPilot by selecting the SAML Provider and clicking Sign In with SAML.
SAML login dialog
  1. You should be redirected to the IdP. Log in with your test user credentials.
If everything is configured correctly, after you have authenticated, you will be redirected to the CoPilot dashboard.