VMware NSX Network Detection and Response SAML v2.0 SSO Integration

Integration with SAML v2.0 provides single sign-on (SSO) services for the User Portal running on On-Premises appliances.

About SAML v2.0 Integration

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, typically an Identity Provider and a Service Provider. SAML is an XML-based markup language consisting of security assertions used for access-control decision making.

The resulting SSO services enhance usability by reducing password fatigue — the number of passwords a user must remember and use as part of their daily workload. It also provides improved security by decreasing potential attack surfaces.

VMware supports SAML v2.0 using an existing Identity Provider to provide SSO services for the User Portal running on the Analyst, Manager, or All-In-One in an On-Premises environment.

Note:

You can configure more than one Identity Provider if needed. Your users will then be presented with multiple SSO options at login.

For an active/standby installation, the SAML v2.0 integration is only supported on the active Manager. After an active/standby failover, you will need to configure the SSO services on the newly active Manager.

Terminology

The following terms are used in this documentation:

SAML v2.0 SSO

XML based protocol that uses security tokens and assertions to allow information about users to be passed securely from one system to another. Information about the user is passed from an Identity Provider (producer) to a Service Provider (consumer).

Identity Provider

An Identity Provider is a system that creates, maintains, and manages identity information while providing authentication services to subscribing applications within a distributed network.

The SAML Identity Provider is a special type of authentication authority; a system that issues authentication assertions in conjunction with an SSO profile of SAML. The subscribing application that consumes these authentication assertions is called a Service Provider. A user must first successfully authenticate with the Identity Provider. This information is then passed to the Service Provider, asserted, then performs the login action.

Service Provider

The Service Provider receives and accepts authentication assertions about a user from the Identity Provider (using cryptographic signatures). This assertion is used to verify that the user identity is correct. After successful assertion, the Service Provider is then responsible for performing the authentication process to the system.

The User Portal is the Service Provider in this integration.

Architecture

For a user to login to the User Portal when using the SAML v2.0, the VMware NSX Network Detection and Response appliance performs a cross-domain request to the Identity Provider. If they have not done so already, the user must authenticate with the Identity Provider. Once the user is authenticated, the Identity Provider sends a cross-domain request back to the Service Provider, containing information about the user. The Service Provider asserts that this information is correct by checking that the signature of the request is valid (using the public x509 certificate provided by the Identity Provider).

If the assertion is successful, the Service Provider will then perform the authentication process to allow the user to be logged into the appliance. If the user’s account does not exist on the VMware NSX Network Detection and Response appliance, the login fails (see VMware NSX Network Detection and Response requirements).

The User Portal is the Service Provider in this integration.

Requirements

VMware NSX Network Detection and Response requirements

For a user to login to the VMware NSX Network Detection and Response appliance using SAML v2.0, their account must be identical to the account located on the Identity Provider. For example, if the username returned by the Identity Provider is "john_doe@example.com", then an identical user account must exist on the appliance. Otherwise, an authentication error will occur and the login fails.

Identity Provider requirements

The Identity Provider must be configured to work with the SAML v2.0 protocol. It must also provide the following XML metadata values:

<entityID>

The unique identifier of the Identity Provider. This is normally the metadata URI. For example, https://example.com/SAML2.

<NameIDFormat>

Indicates which SAML name identifier format the SSO service supports. See Assertions and Protocols for the OASISSecurity Assertion Markup Language(SAML) v2.0, Section 83: Name Identifier Format Identifiers for allowed values.

<SingleSignOnService[Binding]>

Standard URI specified in the SAML v2.0 binding specification. This will indicate whether the request to the Identity Provider will be a POST or REDIRECT.

<SingleSignOnService[Location]>

The location that will POST or GET an AuthNRequest for the Identity Provider.

<X509Certificate>

The public X509 Certificate is used to validate the assertion data of the Identity Provider.

Configuration

Adding SSO using example script

The easiest way to configure SAML v2.0 is to download and use the example script included with the NSX PAPI client implementation. The script is located in the examples directory and is named add_saml_sso_from_metadata.py. The script requires:

The following are required arguments:

appliance_uuid

Determines which VMware NSX Network Detection and Response appliance that SSO it to be configured on. You can obtain the appliance_uuid from the User Portal. Navigate to the Admin→Appliances→Status page. Scroll down to the Appliance UUID entry.

Alternatively, the UUID can be retrieved using the accounting API.

url_or_file

This can be a URI to the XML metadata or it can be the actual XML metadata file. The script uses this XML to parse the necessary information to configure the SSO.

display_name

Used to show the Identity Provider when logging in. For example, if the display name is "example.com sso" the button to login using SSO will be Login with example.com sso.

The following are optional arguments:

-n, --index

The configuration index for the SSO. This is used when multiple configurations are present. For example, if there are two SAML configurations, the first configuration will have the option -n 0 while the second will have the option -n 1.

–-skip-verify-ssl

If a URI is specified for the XML metadata file and the SSL certificate is not valid (for example, a self-signed certificate), this option skips a validity check for the certificate.

-c, –-config

Use the defined PAPI client configuration file.

Configure SAML v2.0 by downloading and running the add_saml_sso_from_metadata.py example script.

  1. Download and install the papi-client

    Download the NSX PAPI software from the User Portal. Decompress the papi_client.tar.gz file and install it.

  2. Create a configuration file

    Create a configuration file structured similar to the following:

    [papi]
url = https://user.lastline.com/papi
auth_method = account
username = user@example.com
password = portal_password
verify_ssl = true|false
timeout = seconds

    Name the configuration file, for example, config.ini. The [papi] section is required and consists of the following entries:

    • url — URL to reach the VMware backend. For NSX PAPI, use https://user.lastline.com/papi.

    • auth_method — Method of authentication. Must be "account".

    • username — User Portal account username.

    • password — User Portal account password.

    • verify_ssl — Defines whether to perform SSL certificate validation. Set this to "false" if you are using a self-signed certificate.

    • timeout — HTTP request timeout in seconds. "20" is recommended.

    The NSX PAPI download contains a template file, papi_client.ini.template, that you can copy or modify to create the configuration file.

  3. Run the script

    From the examples directory run the add_saml_sso_from_metadata.py script.

    lastline@lastline-manager:~$ python3 add_saml_sso_from_metadata.py add B425732F3CDE6415022DF9BF47E8E6F5 https://example.com/SAML2 "Example.com SSO" --config config.ini

Adding SSO using PAPI client

As an alternative, you can configure SAML v2.0 directly from the NSX PAPI client implementation using the following values:

display_name

The Identity Provider that is displayed in the login form. For example, "example.com sso".

entity_id

The unique identifier of the Identity Provider. This is normally the metadata URI. For example, https://example.com/SAML2.

This value maps to the <entityID> XML element.

idp_binding

Standard URI specified in the SAML v2.0 binding specification. This will indicate whether the request to the Identity Provider will be a POST or REDIRECT. For example, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

This value maps to the <SingleSignOnService[Binding]> XML element.

name_id_format

Indicates which SAML name identifier format the SSO service supports. For example, urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

This value maps to the <NameIDFormat> XML element.

sso_service_url

The location that will POST or GET an AuthNRequest for the Identity Provider. For example, https://idp.example.com/SAML2/SSO/POST

This value maps to the <SingleSignOnService[Location]> XML element.

x509_cert

The public X509 Certificate is used to validate the assertion data of the Identity Provider. This x509 certificate must be base64 encoded, exactly as you would see in an Identity Provider metadata file.

This value maps to the <X509Certificate> XML element.

The above settings must be in a JSON dictionary under the key sso_saml2_config{0-3}. Another key, sso_saml2_enabled{0-3}, must be set to true in order for the configuration to work.

Note:

The {0-3} represents that any value between 0 to 3 may be used. This allows you to configure multiple SSO options. If sso_saml2_enabled3 is set to true, then the corresponding setting must contain the same index, sso_saml2_config3.

Configure SAML v2.0 directly from the NSX PAPI client implementation.

  1. Download and install the papi-client

    Download the NSX PAPI software from the User Portal. Decompress the papi_client.tar.gz file and install it.

  2. Create a configuration file

    Create a configuration file structured similar to the following:

    [papi]
url = https://user.lastline.com/papi
auth_method = account
username = user@example.com
password = portal_password
verify_ssl = true|false
timeout = seconds

    Name the configuration file, for example, config.ini. The [papi] section is required and consists of the following entries:

    • url — URL to reach the VMware backend. For NSX PAPI, use https://user.lastline.com/papi.

    • auth_method — Method of authentication. Must be "account".

    • username — User Portal account username.

    • password — User Portal account password.

    • verify_ssl — Defines whether to perform SSL certificate validation. Set this to "false" if you are using a self-signed certificate.

    • timeout — HTTP request timeout in seconds. "20" is recommended.

    The NSX PAPI download contains a template file, papi_client.ini.template, that you can copy or modify to create the configuration file.

  3. Run the script

    From the de-compressed papi_client directory run the papi_shell.py script.

    lastline@lastline-manager:~$ python3 scripts/papi_shell.py --config config.ini
  4. Run the appliance_mgmt command

    Use the following command to configure SSO.

    client.appliance_mgmt.configure(
  appliance_uuid = appliance_uuid,
  settings = {
  "sso_saml2_enabled0": true,
  "sso_saml2_config0": json.dumps({
    "display_name": "Example.com SSO",
    "entity_id": "https://idp.example.com/SAML2",
    "sso_service_url": "https://idp.example.com/SAML2/SSO/POST",
    "idp_binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
    "name_id_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
    "x509_cert": "BASE64ENCODEDCERTIFCATE"
  })
})

    Obtain the appliance_uuid using the Portal or the API. The x509_cert must be Base64 encoded.

    Refer to the documentation for the appliance_mgmt.action_request command.

Login

Once the SSO configuration has successfully completed, the new settings are applied to the VMware NSX Network Detection and Response appliance. The configuration update task may take a few minutes. Once it completes, the option to use SSO for login to the User Portal hosted on the appliance is displayed:

If this login page is not displayed, then there was either an error in the configuration or the configuration process is still pending.

To view the configuration status, navigate to the Action logs tab on the Admin page. Then select the correct appliance. For details, see the Action logs tab help page.