Enable IP Surrogates for SAML

SAML uses a cookie surrogate. The proxy checks the request for a cookie, and if we can't set a cookie, then we can't authenticate the user. Enabling IP surrogates works in cases where the browser cookie can't be set in all cases.

Note: We recommend using IP Surrogates when the user's private IP address is visible, when your tunnels don't use NAT, or when networks incorporate a Proxy Chain with XFF. If the user’s private IP address or an IP address is shared by multiple users (for example, Citrix or VDI environments) then using cookie surrogates is recommended. You can bypass IP surrogates for specified internal networks by selecting Add Internal Network Bypass.

Table of Contents

• Prerequisites
  • HTTPS Inspection
• Map Tunnels to Sites
• Enable IP Surrogates
• Add a New IP Surrogate Bypass
• Delete an IP Surrogate Bypass
• View Identities in Activity Search

Prerequisites

• You must have a working SAML configuration. For more information, see Configure SAML Integrations.
• Proxy networks with XFF and/or tunnels without NAT. IP surrogate needs to be able to see the internal private IPs in order to work.
• HTTPS inspection must be enabled.
• Deleting cookies at the end of a browser session or browsing in incognito mode is not recommended.
• Overlapping IP addresses are not allowed. If internal IP addresses are overlapping across locations, then each location must be defined as a separate Umbrella Site and tunnels must be mapped to the respective Site. See Map Tunnels to Sites for more information.

HTTPS Inspection

Before redirecting a request to an identity provider, Umbrella SWG uses HTTPS inspection to determine if a request is from a browser that supports cookies. Umbrella SWG can establish the identity of a user through the browser cookies and map the identity to an IP address. For subsequent requests, Umbrella uses the IP address as a surrogate for the user identity. Umbrella SWG periodically inspects the cookies in a browser request to ensure the identity is still mapped to the correct IP address.

Umbrella checks to determine if an IP address has been reassigned; only requests from browsers are checked. This check is affected when browsing in incognito mode or deleting cookies from a browsing session and will require the user to re-authenticate. If the user has not browsed for over 12 hours since the last identity check, the IP is discarded from user to IP mapping until the user re-authenticates. After this, the policy will match either a tunnel or network identity.

Map Tunnels to Sites

IP surrogates maps each user identity based on three characteristics which combine to provide a unique identity: Org ID + Site + IP address = User. If you are using SAML IP surrogates, then it is important that the IP addresses used to identify users remain unique for each user. If different branch locations have overlapping IP addresses, use Sites to set the boundaries.
By default, Umbrella assumes there are no overlapping IP addresses and all IPsec tunnels are mapped to a single Default Site. If your organization has overlapping IP addresses at different branch locations, you must create additional Sites and map the tunnels to their respective Sites.

1. Navigate to Deployments > Configuration > Sites and Active Directory, click Settings, then click Add New Site.
2. Give your site a meaningful name and click Save.

3. Map a tunnel to the site.

3a. Add a new tunnel to map to this site.

1. Navigate to Deployments > Core Identities > Network Tunnels and click Add.
2. Give your tunnel a meaningful name, select your Device Type, and choose the Site to associate this tunnel with. then click Save.

3b. Map a tunnel already created.

1. Click the More Actions menu next to the tunnel you wish to map to the site and click Edit.

2. Click on the drop-down menu for Associate Tunnel with Site and choose the site to map the tunnel too, then click Save.

Enable IP Surrogates

1. Navigate to Deployments > Configuration > SAML Configuration.

2. Click IP Surrogate Disabled to enable IP surrogate. The option to Add Internal Network Bypass appears.

You can choose internal networks to bypass the SAML IP surrogate authentication challenge and revert to SAML with cookie surrogates. You should bypass IP surrogates for internal networks from IP surrogates where the IP address is shared by a number of users, such as a virtual desktop deployment. In these cases, where an IP address is shared, we recommend cookie surrogates because they associate the user's browser session to the identity. Internal networks must be defined for the IP address before you can add it to the IP surrogate bypass list.

For more information about configuring internal networks, see Sites and Internal Networks.

Add a New IP Surrogate Bypass

1. With IP Surrogates enabled, click Add Internal Network Bypass.
2. Select the internal network(s) or tunnel(s) where you would like to to disable IP surrogates and click Apply.

3. Click Save.

Delete an IP Surrogate Bypass

1. With IP Surrogates enabled, click Add Internal Network Bypass.
2. Select the internal network(s) or tunnel(s) where you would like to enable IP surrogates and click Apply.

Note: The Delete command on the SAML User Configuration page does not delete an IP Surrogate Bypass; it removes the entire SAML configuration.

View Identities in Activity Search

The details shown in an Activity Search Report indicate when the user identity source is "IP Surrogate":

---

Configure Other IdPs for SAML < Enable IP Surrogates for SAML > Configure SAML for Multiple EntityIDs