> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aviatrix SAML Authentication on Okta IdP

> Aviatrix allows for centralized management of user access by integrating with your chosen Identity Provider (IdP) (in this case, Okta) via SAML. This allows you to control user access to Controller and CoPilot, as well as user access to the cloud environment using Aviatrix UserVPN (if desired).

## Overview

Aviatrix allows for centralized management of user access by integrating with
your chosen Identity Provider (IdP) (in this case, Okta) via SAML. This allows
you to control user access to Controller and CoPilot, as well as user access to
the cloud environment using Aviatrix UserVPN (if desired).

This guide provides an example on how to configure Aviatrix to authenticate
against Okta. When SAML is configured, your Aviatrix CoPilot acts as the Service
Provider (SP) that redirects the user to the IdP for authentication.

## Pre-Deployment Checklist

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

1. The Aviatrix Controller is deployed.
2. You have a valid [Okta account](#okta-account) with admin access.
3. You have downloaded and installed the
   [Aviatrix SAML VPN client](#aviatrix-vpn-client).

### Okta Account

A valid Okta account with admin access is required to configure the integration.

### Aviatrix VPN Client

All users must use the Aviatrix VPN client to connect to the system. Download
the client for your OS

<a href={"/docs/enterprise/" + "10.1" + "/guides/uservpn/user-vpn-client-download"}>here</a>
.

### Custom SAML Request Template (Optional)

This can be used in either the Controller/CoPilot or the UserVPN SAML setup.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="$ID" Version="2.0" IssueInstant="$Time" Destination="$Dest" ForceAuthn="false" IsPassive="false" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="$ACS">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">$Issuer</saml:Issuer>
</samlp:AuthnRequest>
```

## Configuration Steps

Follow these steps to configure Aviatrix to authenticate against your Okta IDP:

1. Create an [Okta SAML App](#creating-an-okta-saml-app-for-aviatrix) for
   Aviatrix.
2. Retrieve [Okta IDP metadata](#retrieving-okta-idp-metadata).
3. Launch an [Aviatrix Gateway](#launching-an-aviatrix-vpn-gateway).
4. Create Aviatrix [SAML SP Endpoint](#creating-aviatrix-saml-endpoint).
5. [Test that the Integration](#testing-the-integration) is set up correctly.
6. Create [Aviatrix VPN User](#creating-a-vpn-user).
7. [Validate](#validate).

### Creating an Okta SAML App for Aviatrix

<Note>This step is usually done by the Okta Admin.</Note>

1. Log in to the Okta Admin portal.
2. Follow
   [Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta)
   to create a new application.

| Field          | Value    |
| -------------- | -------- |
| Platform       | Web      |
| Sign on method | SAML 2.0 |

3. General Settings

| Field          | Value         | Description                                               |
| -------------- | ------------- | --------------------------------------------------------- |
| App name       | Aviatrix      | This can be any value. It will be displayed in Okta only. |
| App logo       | Aviatrix logo | Aviatrix logo (optional)                                  |
| App visibility | N/A           | Leave both options unchecked                              |

4. SAML Settings

   **General**

<img src="https://mintcdn.com/aviatrix-14b37c43/MwMAaVUDwCmP6YfF/images/guides/uservpn/saml-general.png?fit=max&auto=format&n=MwMAaVUDwCmP6YfF&q=85&s=1a53659d0620bf5e487450f5b8313c3b" alt="images2" width="728" height="453" data-path="images/guides/uservpn/saml-general.png" />

| Field                       | Value                                                            |
| --------------------------- | ---------------------------------------------------------------- |
| Single sign on URL          | `https://[host]/flask/saml/sso/[SP Name]` (host = Controller IP) |
| Audience URI (SP Entity ID) | `https://[host]/` (host = Controller IP)                         |
| Default RelayState          |                                                                  |
| Name ID format              | Unspecified                                                      |
| Application username        | Okta username                                                    |

`[host]` is the hostname or IP of your Aviatrix CoPilot. For example,
`https://copilot.demo.aviatrix.live`.

`[SP Name]` is an arbitrary identifier. This same value should be used when
configuring SAML in Aviatrix CoPilot.

**Attribute Statements**

<img src="https://mintcdn.com/aviatrix-14b37c43/MwMAaVUDwCmP6YfF/images/guides/uservpn/saml-attribute.png?fit=max&auto=format&n=MwMAaVUDwCmP6YfF&q=85&s=a81784b24a69017bcfebc641a2c83ed1" alt="images3" width="725" height="313" data-path="images/guides/uservpn/saml-attribute.png" />

| Name      | Name format | Value          |
| --------- | ----------- | -------------- |
| FirstName | Unspecified | user.firstName |
| LastName  | Unspecified | user.lastName  |
| Email     | Unspecified | user.email     |

#### Retrieving Okta IDP Metadata

<Note>This step is usually completed by the Okta admin.</Note>

After the application is created in Okta, go to the Sign On tab for the
application. Then, click **View Setup Instructions**.

Look for the section titled "Provide the following IDP metadata to your SP
provider."

<img src="https://mintcdn.com/aviatrix-14b37c43/MwMAaVUDwCmP6YfF/images/guides/uservpn/idp-metadata.png?fit=max&auto=format&n=MwMAaVUDwCmP6YfF&q=85&s=9dad4f5af440415acd3ed341edde07ff" alt="idp_metadata" width="1902" height="968" data-path="images/guides/uservpn/idp-metadata.png" />

<Note>
  Copy the text displayed. This value will be used to configure the SAML "IDP
  Metadata URL" field in Aviatrix CoPilot.
</Note>

You need to assign the application to your account. Please follow steps 11
through 14 at
[Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta).

### Launching an Aviatrix VPN Gateway

<Note>This step is usually completed by the Aviatrix admin.</Note>

See

<a href={"/docs/enterprise/" + "10.1" + "/guides/uservpn/user-vpn-gateway-guide"}>Create a UserVPN Gateway</a>
.

### Creating Aviatrix SAML Endpoint

<Note>This step is usually completed by the Aviatrix admin.</Note>

1. Go to **Aviatrix CoPilot > CloudFabric > UserVPN > select the Settings tab**.
2. Under SAML, click **+ SAML Endpoint**.
3. Enter the following information:

| Field             | Value                                                                        |
| ----------------- | ---------------------------------------------------------------------------- |
| Name              | SP Name (Use the same name you entered in the Okta Application previously)   |
| IDP Metadata Type | Text                                                                         |
| IDP Metadata Text | Value Copied from Okta (Paste the value copied from Okta SAML configuration) |
| Entity ID         | Hostname                                                                     |

4. Click **OK**.

### Testing the Integration

1. Start the Aviatrix VPN Client.

<Note>
  If you don't start the client, you will receive a warning from the browser in
  the last step of this process
</Note>

2. Log into **Aviatrix CoPilot > Cloud Fabric > UserVPN > select the Settings
   tab**.
3. Under SAML, find the SAML endpoint. In the Test column, select the link
   provided.
4. You should be redirected to the IdP. Now, you can log in and should be
   redirected back to CoPilot.

<Note>
  You will need to assign the new Okta application to a test user's Okta account
  before clicking **Test**.
</Note>

5. Now, you can log in and should be redirected back to CoPilot.
6. If everything is configured correctly, once you have authenticated you will
   be redirected back to CoPilot and the window will close.

### Creating a VPN User

<a href={"/docs/enterprise/" + "10.1" + "/guides/uservpn/user-vpn-saml-authentication"}>Create a new VPN user</a>
. Use the VPN gateway created above.

#### Validate

1. Go to **Aviatrix CoPilot > CloudFabric > UserVPN > select the Users tab**.
2. Download the configuration for your test user created in the previous step.
3. Open the Aviatrix VPN Client application.
4. Click **Load Conf** and select the file downloaded.
5. Click **Connect**.

<Note>
  SAML VPN supports shared certificates. You can share the certificate among VPN
  users or create more VPN users.
</Note>

#### Configuring Okta for Multi Factor Authentication (Optional)

Once you have successfully configured Okta IDP with Aviatrix SP, you can
configure Okta for Multi Factor Authentication.

Please read this
[article](https://support.okta.com/help/s/end-user-adoption-toolkit/setting-up-mfa-for-end-users?language=en_US)
from Okta on Multifactor setup.

See this [article](https://duo.com/docs/okta) if you're interested in using Duo.