AWS SSO IdP for SAML Integration

Overview

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

Before configuring SAML integration between Aviatrix and AWS SSO, make sure you have a valid AWS account with administrator access.

Tip

If your AWS account is a consolidated account, you cannot set up SSO. SSO can only be enabled with a master account.

Configuration Steps

Follow these steps to configure Aviatrix to authenticate against your AWS SSO IdP:

Step 1. Retrieve Aviatrix SP Metadata from the Aviatrix Controller

Step 2. Create an AWS SSO SAML Application for Aviatrix

Step 3. Retrieve AWS SSO IdP metadata

Step 4. Update Aviatrix SP Endpoint in the Aviatrix Controller

Step 5. Test the Integration is Set Up Correctly

Step 1. Retrieve Aviatrix SP Metadata from Aviatrix Controller

Before creating the AWS SSO SAML Application, AWS SSO requires the Service Provider (SP) metadata file from the Aviatrix Controller. You can create a temporary SP SAML endpoint to retrieve the SP metadata for now. Later on in the guide, the SP SAML endpoint will be updated.

Visit one of the following links based on your use case and follow step1 (Create temporary Aviatrix SP Endpoint for Aviatrix) from the link’s Configuration section:

  1. If integrating AWS SSO IdP with Controller Login SAML Config

  2. If integrating AWS SSO IdP with OpenVPN with SAML Authentication

For AWS SSO, right click the SP Metadata button next to the SAML endpoint and save the file.

imageSPMetadataURL

Tip

Save this XML file to your local machine. It will be uploaded to the AWS SSO IdP in the later steps.

This step will ask you to pick a short name to be used for the SAML application name [Endpoint Name]. In the notes below we will refer to this as aviatrix_awssso. It can be any string that will identify the SAML application you create in the IdP.

We will use the string you select for the SAML application name to generate a URL for AWS SSO to connect with Aviatrix. This URL is defined below as SP_ACS_URL. This URL should be constructed as:

https://<<<your controller ip or host name>>>/flask/saml/sso/<<<aviatrix_awssso>>>

Tip

Replace <<<your controller ip or host name>>> with the actual host name or IP address of your controller and <<<aviatrix_awssso>>> with the [Endpoint Name] you chose to refer to the SAML application.

Step 2. Create an AWS SSO SAML Application

Note

This step is usually done by the AWS SSO Admin.

  1. Login to your AWS console

  2. Go to the AWS Single Sign-On service

  3. Add a new Application (Applications > Add a new application)

    imageAddAppsMenu

  4. Click Custom SAML 2.0 application

    imageSelectCustom

  5. Enter a Display Name

  6. Scroll to Application metadata

  7. Browse… to the SP Metadata file saved in the previous step (Step 1)

  8. Leave the Application start URL blank

  9. Click Save changes

    imageAppMetadata

Add Attribute Mappings

  1. Click on the Attribute mappings tab

  2. Add the following attributes:

    User attribute in the application

    Maps to this string value or user attribute in the AWS SSO

    FirstName

    ${user:givenName}

    LastName

    ${user:familyName}

    Email

    ${user:email}

As shown below:

attribute_mapping

  1. Click Save changes

Step 3. Retrieve AWS SSO IdP metadata

Copy the AWS SSO IdP metadata file URL. This URL will be provided to the Aviatrix SP endpoint later on.

imageCopyURL

Step 4. Update Aviatrix SP Endpoint

Note

This step is usually completed by the Aviatrix admin. AWS SSO IdP provides IdP Metadata through URL obtained in Retrieve AWS SSO IdP metadata (Step 3). AWS SSO IdP requires a custom SAML request template.

Continue with updating Aviatrix SAML Endpoint by visiting one of the following links based on your use case:

  1. If integrating AWS SSO IdP with Controller Login SAML Config

  2. If integrating AWS SSO IdP with OpenVPN with SAML Authentication

Note

Each endpoint only supports one type of access. If you need admin and read-only access, create two separate SAML apps. Hostname is the default for Entity ID, but if you have other apps using the same hostname, use a custom Entity ID.

add_saml_endpoint

  1. Remove the XML element <samlp:NameIdPolicy>..</samlp:NameIdPolicy>

    Note

    This is required to connect with AWS SSO. If you don’t do this, you will receive an error message when testing.

  2. Click OK

  3. Right click on the SP Metadata button next to the SAML endpoint just created and save the file to your local machine.

    imageSPMetadataURL

    Tip

    Save this XML file to your local machine. It will be used in the next step.

5. Test the Integration

Tip

Be sure to assign users to the new application in AWS Single Sign-on service prior to validating. You can use AWS SSO Directory service under AWS SSO page to assign users. If you do not assign your test user to the Aviatrix SAML application, you will receive an error.

Continue with testing the integration by visiting one of the following links based on your use case:

  1. If integrating AWS SSO IdP with Controller Login SAML Config

  1. Click Settings in the left navigation menu

  2. Select Controller

  3. Click on the SAML Login tab

  1. If integrating AWS SSO IdP with OpenVPN with SAML Authentication

  1. Expand OpenVPN® in the navigation menu and click Advanced

  2. Stay on the SAML tab

You can quickly validate that the configuration is complete by clicking on the Test button next to the SAML endpoint.

imageAvtxTestButton