This section explains the process to configure an application for SAML-based authentication. This application needs to be registered at an IdP, such as Okta or PingFederate, with details including the redirect URLs, and more. This will yield an IdP metadata XML file that needs to be configured on the SP. In this scenario, the Avi Load Balancer virtual service acts as the SP.

Note:

  • Avi Load Balancer supports sending Assertion Consumer Service (ACS) URL and index to the IdP as part of the auto authentication.

  • Ensure that the SSO URL and entity ID match on the IdP and the SP as mentioned below.

Configuring the Authentication Profile using UI

1. Navigate to Templates > Security > Auth Profile.

2. Click CREATE.

3. Enter the Name for the Auth profile.

4. Select SAML as the Type of Auth profile.

5. Under the SAML tab, configure the following:

Use IdP Metadata

  • Paste the IdP Metadata (The xml that contains the information that will be shared with the SPs) in the text box provided.



Use IdP Metadata URL

  • Metadata URL is the URL where the metadata can be accessed and shared with the SPs.

  • If the initial metadata download fails during the configuration, a mustcheck prevents the configs from being saved. Please contact support to understand the reason for failure.

  • Select Enable Periodic Download for dynamic metadata update. This automatically retrieves, monitors, and updates the SAML IDP metadata. The new data is compared against the existing data and if they are different, the Auth Profile's metadata value is replaced with the updated value.

  • Enter the Update Interval, the duration after which the meta data is queried.

  • If your metadata is not changing so dynamically, it is recommended to configure a higher update interval.



6. Under the Service Provider section, select Use user-provided entity ID.

Note:

Once the Service Provider details are configured in the auth profile, the information cannot be modified.



7. Click Save.

Troubleshooting Metadata Related Issues

Metadata download failure during initial configuration

If the initial metadata download fails during the configuration, a mustcheck prevents the configs from being saved. Please contact support to know the reason for failure.



Periodic Metadata Download Failures

Due to several reasons (Network issue, Server Down, Server Application, and more) metadata download failures can occur. In such cases, the previously downloaded metadata will be used for SAML transactions. An event is generated which mentions about the failure happened.

An sample event is shown below:



SSO during non-synced metadata

In a Scenario where metadata has been updated in the server but not yet downloaded due to Periodic metadata job not running, the SSO authentication during this interval may fail. Specifically where the keys got rolled over as part of metadata update and assertion signature verification fails, there is a new significance log added describes the scenario.



Creating an SSO Policy

  1. Navigate to the Templates > Security > SSO Policy > CREATE.

  2. Enter a Name for the SSO Policy.

  3. Select the SSO Policy Type as SAML.

  4. Under Default Auth Profile, select the Auth Profile created.



  5. Under Authentication Rules, click Add and configure the Authentication Rules as required.

  6. Under Authorization Rules, click Add and configure the Authorization Rules as required.

  7. Click Save.

Binding an SSO Policy to the Virtual Service using UI

  1. Navigate to Applications > Virtual Services.

  2. Click the edit icon for a virtual service to open the Edit Virtual Service screen. Alternatively, this configuration can be done in the create mode for a new virtual service.

  3. Under the Policies tab, select Access.

  4. Select the SSO Policy created.

  5. Enter a unique value as the Entity ID. Ensure this value is the same on the IdP and the SP.

  6. Enter the SSO URL as https://SPresource/sso/acs/. Ensure the same URL is used in the IdP as well. For example, https://sales.avi.com/sso/acs/.

    Note:

    The trailing slash after acs is mandatory.

  7. In the field Session Cookie Name, enter the HTTP cookie name for authenticated session. Avi Load Balancer validates the assertion and sets a cookie for the client. The client sends a GET request to access the resource with the cookie that the SP provided. The cookie name is configurable and be specified through this field. If no name is specified, the Avi Load Balancer VS uses a randomly generated name for the cookie such as XRWDFG.

  8. To customize the cookie expiry time, enter the Session Cookie Timeout in minutes. The default value is 60 minutes.

  9. In the SSL Key field, select an SSL certificate or create one. This SSL certificate is used to sign requests going to the IdP and decrypt the assertions coming from the IdP.

  10. Select an option from the ACS Type which allows Avi Load Balancer to send either ACS URL, ACS index, or None to the IdP as part of the Authentication request. In some IdPs where multiple ACS URLs are allowed to be configured, IdPs use either ACS Index or ACS URL to identify the Service provider. The three ACS Type options are as follows:

    • None – This is the default behavior. If ACS Type is set to none, Avi Load Balancer does not send ACS URL or ACS index in the authentication request to the IdP.

    • URL – ACS URL Specifies by value the location to which the SAML response must be returned to the SP (Avi Load Balancer) by the IdP. If ACS URL is selected, Avi Load Balancer sends ACS URL as part of authentication request to the IdP. IdP then uses the ACS URL to post back the SAML response to the SP.

      Note:

      The value of the ACS URL is same as the SSO URL configured above.

      Use Case - If multiple hostnames are mapped to the same Avi Load Balancer VS (SP), and the requirement is to use the same VS (SP) for all those different hostnames, then follow the steps below:

      • Configure SSO URL to /sso/acs/.

      • Select the URL in ACS type.

        If the SSO URL is set to /sso/acs/ and the URL option is selected in ACS type, then Avi Load Balancer fetches the hostname from the incoming client request and uses that hostname to construct the ACS URL when sending the SAML authentication request to the IdP. For example, If the client request is https://sales.avi.com/, then ACS URL for Avi Load Balancer is https://sales.avi.com/sso/acs/.

      • Ensure the IdP is configured with an SSO/ACS URL for all desired hostnames. For example, https://sales.avi.com/sso/acs/, https://demo.avi.com/sso/acs/, https://foo.example.com/sso/acs/, https://saml.demo.com/sso/acs/, and more.

    • Index - Like ACS URL, the ACS index is used by the IdP to identify the location to which the SAML response must be returned to the SP. If the ACS index is specified, Avi Load Balancer sends the ACS index as part of the authentication request. The range for ACS index is 0-64. Where,

      • 0 means index is 0

      • 1 means index is 1 and, so on



  11. Click Save.

Note:

Using the same SSO configuration for both frontend VS and backend pool server in your NSX Advanced Load Balancer leads to requests getting blocked with a 401 - access denied response. To address this, ensure separate SSO configurations or use different URLs for frontend and backend components to prevent conflicts.

Configuring using Avi Load Balancer CLI

Configure the Auth Profile using the CLI commands shown below:

[admin:saml-ctrlr-1]: > configure authprofile Saml-auth-profile

[admin:saml-ctrlr-1]: authprofile> type auth_profile_saml
[admin:saml-ctrlr-1]: authprofile> saml
[admin:saml-ctrlr-1]: authprofile:saml> sp
[admin:saml-ctrlr-1]: authprofile:saml:sp> saml_entity_type auth_saml_app_vs
[admin:saml-ctrlr-1]: authprofile:saml:sp> save
[admin:saml-ctrlr-1]: authprofile:saml> save
[admin:saml-ctrlr-1]: authprofile> saml
[admin:saml-ctrlr-1]: authprofile:saml> new idp
metadata : ‘metadata_string’

A sample configuration is shown below:

metadata:  ‘<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/exk2c02xxTcM9pIr0355"><md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MIIDtjCCAp6gAwIBAgIGAWPuJWSOMA0GCSqGSIb3DQEBCwUAMIGbMQswCQYDVQQGEwJVUzETMBEG
A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU
MBIGA1UECwwLU1NPUHJvdmlkZXIxHDAaBgNVBAMME2F2aW5ldHdvcmtzLWF1dGhsYWIxHDAaBgkq
hkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMTgwNjExMDkxOTE4WhcNMjgwNjExMDkyMDE3WjCB
mzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lz
Y28xDTALBgNVBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRwwGgYDVQQDDBNhdmluZXR3
b3Jrcy1hdXRobGFiMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0B
AQEFAAOCAQ8AMIIBCgKCAQEAiFKBy70aa5G2I5JH+uUqXef9jrhUtx6CX1nmrg26FXtsKYdjRm5v
otxbjfNdcXeXRXHu5scMwAgMy9EZM+AXehlm/qnahNWvEZ+YgPZS55UzkcSXJ30dl62kbUAyXxo3
CQQs+Hj5k7W0rcZAj405qxOZVgtkrs6cB3uS/pn02eV4EHA6ECReQLrEPFcy6zLZpIChbkzyz372
ZLbwMCSjF5DLh52MSGgWixwvs5Mq20WofBWMOnS0ofnZq6+TM6XK7P8VEQxJe37sWi0W+RrR6685
T+bnlM6GMg24wRHt/1fouUbZQuBgoc0/HNKywlO9BXLoJ9j02/VYn3Uex9bumQIDAQABMA0GCSqG
SIb3DQEBCwUAA4IBAQAmAh0fXL7gU1ivV3hWdl0AlLPENREAzKbHwuthtTySBr6rmreo6j8SvOMW
pKQzNznmzU3zyeLd96j6lfA7PIDGyBGmNB6z0Va0bPvOQe+a2f3/cmumVdrKFv7I5ZiR0UNbeBmG
BIeWkJ+Rx+FcaIzP2IiFddmvpdh1nLae7FS9F1jvnioSIwq2PlFZuMMFb2TrMXrqqEMp9CeGfEag
bjxQcWEW1ifNxeKrI/LcS5g5mTf4gx41bgo/w9x6MRsK+bIbYv680mdtb6LhWiT1lZU+ZAYJTKMr
HHoIxYFPW8Zcs7DGirOOYMbSU97G0rljQzbv9gcS+FhwPffBaHi3spk9</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat><md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://avinetworks-authlab.okta.com/app/avinetworksorg108212_apmssotest_1/exk2c02xxTcM9pIr0355/sso/saml"/><md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://avinetworks-authlab.okta.com/app/avinetworksorg108212_apmssotest_1/exk2c02xxTcM9pIr0355/sso/saml"/></md:IDPSSODescriptor></md:EntityDescriptor>’

Complete the CLI sequence with two save commands.

[admin:saml-ctrlr-1]: authprofile:saml> save	
[admin:saml-ctrlr-1]: authprofile> save	
+----------------------+------------------------------------------------+	
| Field                | Value                                                                            
+----------------------+------------------------------------------------+	
| uuid                 | authprofile-789ce4af-6b9d-4a73-bd26-d00f670a19c0                                 |	
| name                 | Saml-auth-profile                                                                |	
| type                 | AUTH_PROFILE_SAML                                                                |	
| saml                 |                                                                                  |	
|   idp                |                                                                                  |	
|     metadata         | <?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:n |	
|                      | ames:tc:SAML:2.0:metadata" entityID="http://www.okta.com/exk2c02xxTcM9pIr0355">< |	
|                      | md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration=" |	
|                      | urn:oasis:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInf |	
|                      | o xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate |	
|                      | >MIIDtjCCAp6gAwIBAgIGAWPuJWSOMA0GCSqGSIb3DQEBCwUAMIGbMQswCQYDVQQGEwJVUzETMBEG A1 |	
|                      | UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU MBIGA |	
|                      | 1UECwwLU1NPUHJvdmlkZXIxHDAaBgNVBAMME2F2aW5ldHdvcmtzLWF1dGhsYWIxHDAaBgkq hkiG9w0B |	
|                      | CQEWDWluZm9Ab2t0YS5jb20wHhcNMTgwNjExMDkxOTE4WhcNMjgwNjExMDkyMDE3WjCB mzELMAkGA1U |	
|                      | EBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lz Y28xDTALBgNVBA |	
|                      | oMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRwwGgYDVQQDDBNhdmluZXR3 b3Jrcy1hdXRobGFiM |	
|                      | RwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0B AQEFAAOCAQ8AMIIBCgKC |	
|                      | AQEAiFKBy70aa5G2I5JH+uUqXef9jrhUtx6CX1nmrg26FXtsKYdjRm5v otxbjfNdcXeXRXHu5scMwAg |	
|                      | My9EZM+AXehlm/qnahNWvEZ+YgPZS55UzkcSXJ30dl62kbUAyXxo3 CQQs+Hj5k7W0rcZAj405qxOZVg |	
|                      | tkrs6cB3uS/pn02eV4EHA6ECReQLrEPFcy6zLZpIChbkzyz372 ZLbwMCSjF5DLh52MSGgWixwvs5Mq2 |	
|                      | 0WofBWMOnS0ofnZq6+TM6XK7P8VEQxJe37sWi0W+RrR6685 T+bnlM6GMg24wRHt/1fouUbZQuBgoc0/ |	
|                      | HNKywlO9BXLoJ9j02/VYn3Uex9bumQIDAQABMA0GCSqG SIb3DQEBCwUAA4IBAQAmAh0fXL7gU1ivV3h |	
|                      | Wdl0AlLPENREAzKbHwuthtTySBr6rmreo6j8SvOMW pKQzNznmzU3zyeLd96j6lfA7PIDGyBGmNB6z0V |	
|                      | a0bPvOQe+a2f3/cmumVdrKFv7I5ZiR0UNbeBmG BIeWkJ+Rx+FcaIzP2IiFddmvpdh1nLae7FS9F1jvn |	
|                      | ioSIwq2PlFZuMMFb2TrMXrqqEMp9CeGfEag bjxQcWEW1ifNxeKrI/LcS5g5mTf4gx41bgo/w9x6MRsK |	
|                      | +bIbYv680mdtb6LhWiT1lZU+ZAYJTKMr HHoIxYFPW8Zcs7DGirOOYMbSU97G0rljQzbv9gcS+FhwPff |	
|                      | BaHi3spk9</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md: |	
|                      | NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFor |	
|                      | mat><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md: |	
|                      | NameIDFormat><md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindin |	
|                      | gs:HTTP-POST" Location="https://avinetworks-authlab.okta.com/app/avinetworksorg1 |	
|                      | 08212_apmssotest_1/exk2c02xxTcM9pIr0355/sso/saml"/><md:SingleSignOnService Bindi |	
|                      | ng="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://avinet |	
|                      | works-authlab.okta.com/app/avinetworksorg108212_apmssotest_1/exk2c02xxTcM9pIr035 |	
|                      | 5/sso/saml"/></md:IDPSSODescriptor></md:EntityDescriptor>                        |	
|   sp                 |                                                                                  |	
|     saml_entity_type | AUTH_SAML_APP_VS                                                                 |	
| tenant_ref           | admin                                                                            |	
+----------------------+------------------------------------------------+	
[admin:saml-ctrlr-1]: >

Configure the SSO policy using the code below:

[admin:saml-ctrlr-1]: configure ssopolicy saml_ssopolicy
[admin:saml-ctrlr-1]: ssopolicy> authentication_policy default_auth_profile_ref Saml-auth-profile
[admin:saml-ctrlr-1]: ssopolicy:authentication_policy> save
[admin:saml-ctrlr-1]: ssopolicy> save
+----------------------------+------------------------------------------+
| Field                      | Value                                          
+----------------------------+------------------------------------------+
| uuid                       | ssopolicy-23bf7f51-d95a-4f1d-9dbb-648dd7ad11e6 |
| name                       | saml_ssopolicy                                 
| authentication_policy      |                                                
|   default_auth_profile_ref | Saml-auth-profile                              
| tenant_ref                 | admin                                          
+----------------------------+------------------------------------------+

Configure the virtual service using the steps shown below:

  • Bind the SSO Policy

[admin:saml-ctrlr-1]: > configure virtualservice VS-SAML
  Updating an existing object. Currently, the object is:
       < Object specifics would appear here. Left out of article for brevity's sake. >
[admin:10-30-2-30]: virtualservice> sso_policy_ref saml_ssopolicy

  • Configure SP

[admin:saml-ctrlr-1]: virtualservice> saml_sp_config
  [admin:saml-ctrlr-1]: virtualservice:saml_sp_config> single_signon_url https://sales.avi.com/sso/acs/
  [admin:saml-ctrlr-1]: virtualservice:saml_sp_config> entity_id SAML_app
  [admin:saml-ctrlr-1]: virtualservice:saml_sp_config> cookie_name MyCookie
  [admin:saml-ctrlr-1]: virtualservice:saml_sp_config> cookie_timeout 60
  [admin:saml-ctrlr-1]: virtualservice:saml_sp_config> save
  [admin:saml-ctrlr-1]: virtualservice> save