Procedure to configure Single Sign-On on standalone NSX 4.2

Products

• VMware NSX

Issue/Introduction

Support for Single Sign-On (SSO) on NSX for Web browsers was introduced in NSX 4.2.1.0. However, it was only validated in VCF 5.1 and VCF 5.2 deployments when configured through SDDC Manager.

NSX 4.2.1.0 supports the protocols OpenID Connect (OIDC) for user authentication and SCIM 2.0 for user searches. NSX can be configured to connect to a vCenter instance where an external Identity Provider (IDP) is configured. NSX is not designed to connect to external IDPs.

vCenter has an agent, called VMware Identity Broker (vIDB), that manages the protocols and small variations with the different 3rd-party IDPs supported, while it provides a consistent and uniform interface with other VMware components like NSX.

This article describes the steps to configure Single Sign-On (SSO) for NSX Managers 4.2.x, including NSX Global Managers, that are not deployed using SDDC Manager.

 

Environment

VMware NSX

Resolution

Requirements:

You need to have a vCenter instance with version 8.0x, where x is U3 or later. This vCenter instance is configured with an external IDP, such as OKTA or Microsoft Entra ID.  You can refer to the following KB article for additional details:

• OKTA: KB 322197
• Microsoft Entra ID: KB 322179
  
  

You also need NSX 4.2.x, where x is 1.3 or later. Note that this procedure might not work with the next NSX major release.

 

Considerations:

NSX supports only one OIDC connection to vCenter even though the NSX WebUI displays that 10 OIDC connections can be created.  Configuring a new OIDC with vCenter will override and replace the previous one.

NSX supports only one URL for redirection, i.e., the URL that the external IDP will invoke after a user is successfully authenticated. The recommendation is to use the NSX cluster virtual IP address (VIP) or its Fully Qualified Domain Name (FQDN). If you have a load balancer in front of NSX, you can use its address or FQDN.

You cannot configure SSO for individual NSX nodes in an NSX cluster.

 

Procedure:

There is one simple API to invoke on NSX, Local and Global Managers:
POST ../v1/trust-management/oidc-uris/action/configure-ws1b-oidc-endpoint

This invocation requires Enterprise Admin permissions.

Note: There is a script attached to this KB that facilitates the configuration of SSO in NSX

This API is idempotent, i.e., it can be invoked multiple times. However, the last invocation overrides and replaces the previous configuration, so there is only one OIDC connection with vCenter.

The payload takes the following parameters:

• oidc_uri: Well-known OIDC endpoint of the vCenter instance. It has the format:
  https://<vcenter-fqdn>/acs/t/customer/.well-known/openid-configuration
• api_token: vCenter’s vIDB access token 
• certificate_chain: vCenter X509 certificate in PEM format
• nsx_fqdn: NSX FQDN to be used for the redirect URL. Log in at https://<nsx_fqdn>/login.jsp

 

Example of an invocation from Linux:

curl -k -s -X POST \   'https://nsx-mgmt.vcf.sddc.lab/api/v1/trust-management/oidc-uris/action/configure-ws1b-oidc-endpoint' \   --user 'admin:<password>' \   --header 'Accept: application/json' \   --header 'Content-Type: application/json' \   --data '{     "oidc_uri": "https://vcenter-mgmt.vcf.sddc.lab/acs/t/customer/.well-known/openid-configuration",     "api_token": "eyJ0eXAiOiJKV1QiLCJhb...",     "certificate_chain": "-----BEGIN CERTIFICATE-----\nMIIF ... x8Y=\n-----END CERTIFICATE-----",     "nsx_fqdn": "nsx-mgmt.vcf.sddc.lab"   }'

 

After SSO is configured, you must log into NSX as Enterprise Admin, navigate to System > User Management > User Role Assignment. Click on ADD ROLE FOR OPENID CONNECT USER/GROUP.
On the new dialog, select vcenter-idp-federation and type the federated users and groups that you want to assign NSX roles.

After groups and users are assigned NSX roles, log out and use https://<nsx-fqdn>/login.jsp to log in and then select SIGN IN WITH VCENTER-IDP-FEDERATION. After you authenticate, you will not be asked to enter your credentials if you open a Web session with another VMware component configured with the same vCenter / vIDB endpoint.

You can learn more about the NSX and vCenter APIs in the following URLs:

• NSX API reference: https://developer.broadcom.com/xapis/nsx-t-data-center-rest-api/latest
• vCenter – vIDB API: https://developer.broadcom.com/xapis/vmware-identity-broker/latest

Scripts:

For convenience, there are two scripts attached to this article that automate the entire process. They perform the same operation, one written in Bash and another in Python. Both take the same parameters:

• -v: vCenter FQDN
• -a: vCenter Administrator password
• -n: NSX FQDN
• -b: NSX Enterprise Admin password

The Python version needs the library Requests. Install it with:

pip install requests

The Bash version needs the JSON processor jq tool. Install it with your package manager, for example:

apt install jq -y

Run either script from a device that can connect to vCenter and NSX. After SSO is configured and federated users or groups are assigned NSX roles, use https://<nsx-fqdn>/login.jsp to log in with SSO across vCenter and all other VMware components configured with the same vCenter / vIDB endpoint.

 

Examples:

Linux:

chmod +x configure_nsx_sso.sh

./configure_nsx_sso.sh -v vcenter-mgmt.vcf.sddc.lab -a 'password' -n nsx-mgmt.vcf.sddc.lab -b 'password'

 

Windows:

python configure_nsx_sso.py -v vcenter-mgmt.vcf.sddc.lab -a "password" -n nsx-mgmt.vcf.sddc.lab -b "password"

 

Attachments

configure_nsx_sso.sh

configure_nsx_sso.py