Skip to main content

Check out Interactive Visual Stories to gain hands-on experience with the SSE product features. Click here.

Skyhigh Security

SAML authentication using an external Identity Provider

To support organizations that want users to authenticate using a trusted, external Identity Provider, Web Gateway performs the SAML Service Provider role.

NOTE: SAML authentication refers to how identity information is shared between the Identity Provider and the Service Provider.

In this SAML scenario, the external Identity Provider is a database or authentication service that the organization trusts, but is outside the Web Gateway system. Web Gateway sends a SAML authentication request to the external Identity Provider. The Identity Provider authenticates the user using any authentication method and returns the identity information in a SAML assertion in the SAML authentication response. Web Gateway extracts the identity information from the SAML assertion and sets a cookie, which the user can use to authenticate to a cloud application.

Internally, Web Gateway implements SAML authentication using an external Identity Provider through the authentication server and the proxy, which provides the SAML functionality that the authentication server is missing.

NOTE: The application in the cloud provides a service and is also known as a Service Provider. However, in this scenario, the Identity Provider and Service Provider roles are assigned to the players in the SAML authentication process itself, not to the service provided in the cloud.

SAML authentication process using an external Identity Provider

The authentication server consumes the SAML assertion in the response sent by the external Identity Provider and sets a cookie for the authenticated user.

The SAML authentication process begins when the user requests access to an application in the cloud through Web Gateway. The process consists of HTTP Redirect (GET) and POST messages that are sent through the user's browser (dashed lines). It also consists of messages that are sent and received by the user (solid lines). The messages that are sent through the user's browser to another SAML party take place automatically and quickly. The user is not aware of the authentication process running in the background.

NOTE: Web Gateway sends the SAML authentication request to and receives the SAML authentication response from the Identity Provider using the HTTP POST method.

  1. The user requests access to an application in the cloud through Web Gateway.
  2. If Web Gateway does not recognize the user, the proxy redirects the request to the authentication server through the user's browser.
  3. The authentication server sends a SAML authentication request to the Identity Provider through the user's browser. The Identity Provider authenticates the user and sends a SAML authentication response back to the authentication server, also through the user's browser.

NOTE: If the authentication server URL is static, the proxy intercepts the authentication response, constructs a dynamic URL, and redirects the response to the authentication server.

  1. The authentication server consumes the SAML assertion in the response, sets a cookie, and redirects the authenticated user with the cookie to the application in the cloud through the proxy.
  2. The proxy redirects the user with the cookie to the application in the cloud through the user's browser.
  3. The application grants access to the user.
    clipboard_ee76780b7e3da53e47a948d32ff5e581b.png

How Web Gateway supports static ACS URLs

Web Gateway supports Identity Providers that do not support dynamic URLs by saving the dynamic ACS URL in the RelayState parameter.

RelayState parameter

The URL of the authentication server, which provides the Assertion Consumer Service, is dynamic. Not all Identity Providers support dynamic URLs, which contain parameters. Web Gateway supports these Identity Providers by saving the value of the dynamic ACS URL at the time the authentication request is created in the RelayState parameter.

NOTE: The RelayState parameter is configured automatically. No configuration is required on your part.

The authentication server sends the RelayState parameter and the authentication request to the Identity Provider in a POST form. When the Identity Provider returns the RelayState parameter and the authentication response, also in a POST form, the value of the RelayState parameter is unchanged.

If the ACS URL in the response is static, the proxy intercepts the response and restores the dynamic ACS URL from the static ACS URL and the RelayState value. Using the restored ACS URL, the proxy can redirect the SAML authentication response to the authentication server.

Configuring a static ACS URL

If the external Identity Provider supports dynamic URLs, the authentication server automatically sends the dynamic value to the Identity Provider and validates the ACS URL that it receives in return. No configuration is required in the Web Gateway interface.

If the external Identity Provider does not support dynamic URLs, the static ACS URL must be configured in two locations in the Web Gateway interface. The configured values must match.

  • Static ACS URL value sent to the Identity Provider in the SAML request — This value is configured in the Prepare fixed ACS URL rule.
  • Static ACS URL value expected in the SAML response from the Identity Provider — This value is configured in the SAML Response settings.

NOTE: The ACS URL value that you are expecting from the Identity Provider must also be configured at the Identity Provider.

High-level configuration tasks

Configuring SAML authentication with Web Gateway in the Service Provider role involves the following high-level tasks.

  1. Import the Cookie authentication with SAML back end and fixed ACS URL rule set from the Rule Sets Library.

NOTE: This rule set is located in the Authentication rule set group.

  1. Configure a static ACS URL.

NOTE: This task is required when the external Identity Provider does not support dynamic URLs.

  1. Configure the SAML authentication request.

NOTE: Web Gateway does not sign the SAML authentication request nor provide an X.509 certificate.

  1. Configure the SAML authentication response. This task includes importing the X.509 certificate that the Identity Provider uses to sign the SAML authentication response and assertion.
  2. To ensure that the authentication server recognizes the authentication response sent by the external Identity Provider, add the Identity Provider's service URL to the SAML IdP Whitelist.
  3. Configure the SAML attributes that you want mapped to the Authentication.UserName and Authentication.UserGroups properties.
  4. Manually configure the external Identity Provider to produce a SAML authentication response that meets the requirements you configure in the Web Gateway interface.

Configure a static ACS URL

Configure a static ACS URL when the external Identity Provider does not support dynamic URLs.

Before you begin

Make sure that the Cookie Authentication with SAML backend and fixed ACS URL rule set is imported from the Rule Set Library.

Task

  1. Select Policy | Rule Sets.
  2. Expand Cookie Authentication with SAML backend and fixed ACS URL | Cookie Authentication at Authentication Server, then select Authentication Server Request.
  3. Select the rule Prepare Fixed ACS URL, then click Edit.
    The Edit Rule dialog box opens.
  4. Select the step Events, select the event, then click Edit.
    The Edit Set Property dialog box opens with the User-Defined.SAMLUrlRewrite property selected.
  5. Select "- enter your URL here -", then click Edit.
  6. In the Enter a String dialog box, type the static URL, then click OK.
  7. To close the Edit Rule dialog box, click Finish.

The static ACS URL is updated in the Authentication Server Request rule set view.

Configure a SAML authentication request

Configure the SAML authentication request that the authentication server sends to the external Identity Provider.

Before you begin

Make sure that the Cookie Authentication with SAML backend and fixed ACS URL rule set is imported from the Rule Set Library.

Task

  1. Select Policy | Settings.
  2. Expand Engines | SAML Request, then select SAML Request.
    The Authn Request window opens for configuration.
  3. Provide values for the Authn Request settings.
  4. Click Save Changes.

Configure a SAML authentication response

Configure the SAML authentication response that the authentication server expects to receive from the external Identity Provider. To determine whether the SAML authentication response is valid, the authentication server compares the actual values in the response to the configured values.

Before you begin

Make sure that the Cookie Authentication with SAML backend and fixed ACS URL rule set is imported from the Rule Set Library.

Task

  1. Select Policy | Settings.
  2. Expand Engines | SAML Response, then select SAML Response.
    The Authn Response window opens for configuration.
  3. Provide values for the Authn Response settings.
  4. Click Save Changes.

Add external IdP URL to SAML IdP Whitelist

To ensure that the authentication server recognizes the authentication response sent by the external Identity Provider, add the Identity Provider URL to the SAML IdP Whitelist.

Before you begin

Make sure that the Cookie Authentication with SAML backend and fixed ACS URL rule set is imported from the Rule Set Library.

Task

  1. Select Policy | Lists.
  2. Expand Custom Lists | Wildcard Expression, then select SAML IdP Whitelist.
  3. Click Add.
    The Add Wildcard Expression dialog box opens.
  4. In the Wildcard Expression field, specify an expression that matches the URL of the external Identity Provider.
  5. Click OK.
    The matching expression is added to the SAML IdP Whitelist.

Configure SAML attribute mapping

You configure the names of the SAML attributes that you want mapped to the Authentication.UserName and Authentication.UserGroups properties.

Before you begin

Make sure that the Cookie Authentication with SAML backend and fixed ACS URL rule set is imported from the Rule Set Library.

Task

  1. Select Policy | Rule Sets.
  2. Expand Cookie Authentication with SAML backend and fixed ACS URL | Cookie Authentication at Authentication Server, then select Authentication Server Request.
  3. Select the rule Set user name and groups, then click Edit.
    The Edit Rule dialog box opens.
  4. Select the step Events, select an event, then click Edit.
    The Edit Set Property dialog box opens with the Authentication.UserName or Authentication.UserGroups property selected.
  5. Navigate to the Parameters for Property "Map.GetStringValue" dialog box.
  6. Select an option:
    • Authentication.UserName — Select 2. Key (String) Value: "userId". Replace userID with the name of the SAML attribute that you want mapped to the user name property.
    • Authentication.UserGroups — Select 2. Key (String) Value: "userGroup". Replace userGroup with the name of the SAML attribute you want mapped to the user groups property.
  7. To save your changes, click OK.
  8. To close the Edit Rule dialog box, click Finish.

The names of the SAML attributes that you want mapped are updated in the Authentication Server Request rule set view.

Validating the SAML authentication response

To validate the SAML authentication response sent by the external Identity Provider, the authentication server compares the values in the response to the values configured in the Web Gateway interface.

NOTE: You must manually configure the external Identity Provider to produce a SAML authentication response that meets the requirements configured in the Web Gateway interface.

To be valid, the SAML authentication response must meet the following requirements:

  • The response must be a valid XML string.
  • The response must include at least one SAML assertion.
  • The <saml2p:StatusCode> element in the response must have the value Success.
  • If configured, the response signature and assertion signature must be valid.
  • Response must be signed — If this setting is selected in the SAML authentication response configuration, the authentication server checks that the response is signed and that the signature is valid.
  • Assertion must be signed — If this setting is selected in the SAML authentication response configuration, the authentication server checks that the assertion is signed and that the signature is valid.
  • The value of the <saml2:Issuer> element in the response must match the EntityID setting in the SAML authentication response configuration.
  • The <saml2:Conditions> element in the response must include the attributesnotBefore andnotAfter.
  • The current local time must fall within the specified time range, as follows.
    • Response must be already valid — When selected, this setting specifies that the current local time must be greater than or equal to the notBefore value.
    • Negative clock skew — The current local time must be greater than or equal to the notBeforetime minus the negative clock skew value specified in the SAML authentication response configuration.
    • Positive clock skew —The current local time must be less than or equal to the notAftertime plus the positive clock skew value specified in the SAML authentication response configuration.
  • If configured, the audience element must be included in the response and set to a predefined value, as follows.
    • Audience must be set in the response — If selected in the SAML authentication response configuration, the response must include the element<saml2:Audience>.
    • Audience must match the predefined value — If selected in the SAML authentication response configuration, the value of the <saml2:Audience> element must match the value specified in the Audience URI or ACS URL field in the configuration.
  • The value of the Destinationattribute in the <saml2p:Response>element in the response must match the ACS URL setting specified in the SAML authentication response configuration.

 

  • Was this article helpful?