CoPilot SAML Authentication

Overview

This guide provides an example on how to configure Aviatrix CoPilot to authenticate to an IdP. When SAML is used for Aviatrix CoPilot access authentication, your Aviatrix CoPilot acts as the Identity Service Provider (ISP) that redirects browser traffic from client to IdP (e.g., Okta) for authentication.

The Aviatrix CoPilot SAML login supports multiple SAML endpoints with varying access and utilizing different IdP’s.

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

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 IdP, make sure the following is completed:

The Aviatrix CoPilot 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 IdP:

Creating a Temporary Aviatrix SAML Endpoint for Aviatrix CoPilot.
Creating a SAML App for Aviatrix CoPilot with the IdP.
Retrieving IdP Metadata.
Updating the Aviatrix SAML Endpoint with IdP metadata.
Validating the integration setup.

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

Log in to Aviatrix CoPilot.
Go to Administration > User Access > Access Management.
Under Login Authentication, click +SAML Endpoint.

The Create SAML Endpoint dialog displays.

Enter the following information:

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	Hostname/Custom. Select Hostname for now. If you select Custom you must enter a Custom Entity ID.
Access Set By	Select Controller or SAML Identity Provider Attribute. If you select Controller, you must select a Permission Group. If you select SAML Identity Provider Attribute, you can choose to Block Empty Profiles. This prevents users who do not have a profile assignment sent by the IdP from accessing CoPilot.
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	For 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.

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

Hostname/Custom. Select Hostname for now.

If you select Custom you must enter a Custom Entity ID.

Access Set By

Select Controller or SAML Identity Provider Attribute.

If you select Controller, you must select a Permission Group.

If you select SAML Identity Provider Attribute, you can choose to Block Empty Profiles. This prevents users who do not have a profile assignment sent by the IdP from accessing CoPilot.

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

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

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

Click Save.
Depending on your IdP provider, you may need to upload SP metadata.
1. After the temporary SAML endpoint is created, click the vertical ellipsis 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 with the IdP Provider with the following values from the SAML endpoint you created above.

Assertion Consumer Service URL: to obtain this, in Aviatrix CoPilot click the vertical ellipsis 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 IdP, you need to retrieve IdP Metadata either in URL or text form 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 URL
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.

Go to Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab.
Under SAML, click the Edit icon next to the SAML endpoint you created earlier.
Paste the IdP Metadata URL from the SAML provider into the Identity Provider Metadata URL field.

Click Save.

Validating the Integration

Log out of Aviatrix CoPilot.
Choose your SAML endpoint name from the dropdown box.
Log in to Aviatrix CoPilot by selecting the SAML Provider and clicking Sign In with SAML.
You should be redirected to 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.