CoPilot SAML Authentication

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.

    400

  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.
Field Value

Name

Enter a unique identifier for the service provider.

Identity Provider Metadata Type

Select 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 Text, you must enter the text and then any related xml code.

To avoid authentication, 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.

Entity ID

You can select Hostname or 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 access to the IdP from the client.

Turn this setting on to have Auth Requests sent from the Controller to the IdP signed by the Controller. The same 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.

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

<is this done in the IdP?> 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 15 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.

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

    400

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