Aviatrix Controller Login with SAML Authentication

1. Overview

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

The Aviatrix controller 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.

2. Pre-Deployment Checklist

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

  1. Aviatrix Controller is setup and running
  2. Have a valid IdP account with admin access

2.1 Aviatrix Controller

If you haven’t already deployed the Aviatrix controller, follow the Controller Startup Guide.

2.2 IdP Account

An IdP refers to an identity provider for SAML. This could be any provider that supports a SAML end point like Okta, OneLogin, Google, AWS SSO, Azure AD, and PingOne. 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

3. Configuration Steps

Follow these steps to configure Aviatrix to authenticate against IdP:

  1. Create temporary Aviatrix SP Endpoint for Aviatrix controller
  2. Create SAML IdP App with specific IdP
  3. Retrieve IdP Metadata from IdP
  4. Update Aviatrix SP Endpoint with IdP metadata
  5. Test the Integration is set up correctly
  6. Validate

3.1 Create 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. Login to the Aviatrix Controller

  2. Click Settings in the left navigation menu

  3. Select Controller

  4. Click on the SAML Login tab

  5. Click ADD NEW button

    image3-1-1

    image3-1-2

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:
  • Click DOWNLOAD SP METADATA button next to the SAML endpoint and save file to your local machine
  • Click SP METADATA button, and copy the SP metadata as text

3.2 Create 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>

Important

You can find these values in the controller under the Settings navigation item. Then, select Controller and go to the SAML Login tab. Click on the button for the respective value, and copy the URL on the new page. RelayState is currently not used by the Aviatrix SP

image3-2

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 IdP’s include: VmWare VIDM, ForgeRock’s OpenAM etc.

3.3 Retrieve 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 URL
  6. OneLogin - provides IdP metadata URL
  7. PingOne - provides IdP metadata URL

3.4 Update Aviatrix SP Endpoint

Note

his 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. Login to the Aviatrix Controller

  2. Click Settings in the left navigation menu

  3. Select Controller

  4. Click on the SAML Login tab

  5. Click Edit button

    Field Value
    Endpoint Name Unique name that you chose in step 3.1
    IPD Metadata Type Text or URL (depending on what was provided by the SAML provider)
    IdP Metadata Text/URL IdP metadata URL/Text copied from the SAML provider configuration
    Entity ID Select Hostname or Custom
    Custom Entity ID Only visible if Entity ID is Custom
    Access Select admin or read-only access
    Custom SAML Request Template Depending on your specific IdP, you may have to check this option. 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.

  1. Click OK

3.5 Test the Integration

  1. Click Settings in the left navigation menu

  2. Select Controller

  3. Click on the SAML Login tab

  4. Click the Test button next to your SAML endpoint name

    image3-5

  5. You should be redirected to IdP. Login with your test user credentials.

Important

If everything is configured correctly, once you have authenticated, another windows should open with the test user’s access.

3.6 Validate

  1. Logout of the Aviatrix Controller

  2. Choose from the dropdown box your SAML endpoint name

  3. Login to the Aviatrix Controller by clicking the SAML Login button.

    image3-6

  4. You should be redirected to IdP. Login with your test user credentials.

Important

If everything is configured correctly, once you have authenticated you will be redirected to the dashboard’s controller.