The deployment-mssp Developer Hub

Welcome to the deployment-mssp developer hub. You'll find comprehensive guides and documentation to help you start working with deployment-mssp as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Create and Apply Policies

Policies control the level of protection, content filtering, and logging provided by Umbrella for all of your customer's identities. In Umbrella, you create, update and manage each customer's policies through the Policy wizard (Policies > Management > All Policies). In the MSSP console, when you save a Centralized Setting, it is automatically shared with all existing Umbrella policies for the customer of the Centralized Setting. Centralized Settings are also available in Umbrella's policy wizard when you create a new policy.

In Umbrella, there's always at least one policy—the default policy. This policy applies to all identities when no other policy above it covers that identity. In other words, the Umbrella default policy is a catch-all to ensure all identities receive a baseline level of protection.

Note: Policies apply to identities on a first match basis and are not additive. The matching policy closest to the top of the order applies. You can drag and drop policies to reorder them at anytime. For more information, see Best Practices for Policies and Grouping Identities.

Create a New Policy

  1. Navigate to Customer Management and click View Dashboard for the customer you want to create and apply policies.

The customer's Umbrella dashboard opens in a new browser tab. You do not need to sign into your customer's Umbrella dashboard.
You can confirm that you're navigating the customer's Umbrella dashboard be reviewing sign in information listed in the the left-side navigation. The customer name is listed.
As well, the customer's name is listed in the search bar.

  1. In Umbrella, navigate to Policies > Management > All Policies and click Add or expand the Default policy.
  1. Select the identities you wish to apply this policy to and click Next.
    This determines to whom these settings will apply. This can be any combination of identities available in your account. Categories (such as AD Computers or Roaming Computers) can be drilled down to more selectively choose identities to apply to a policy.
    Note: If you are editing the Default policy from the Summary screen, the ability to edit identities is restricted because the Default Policy applies to all identities.
  1. Click Edit Settings. Icons change from shields to selectable checkboxes.
    By default, items selected are those that are shared with the customer from the MSSP console's Centralized Settings > Advanced Settings.

Available options correspond to policy features. If you clear an item, its corresponding Policy wizard step is skipped when moving through the Policy wizard and you cannot make changes for that policy feature. For example, If you clear Enforce Security at the DNS layer, when you click Next, the wizard skips the Security Settings step.

  • Enforce Security at the DNS Layer—When selected, the Security Settings step is available in the Policy wizard. These are settings related directly to the blocking of domains based on whether they are malicious and provides a base level of security protection. We recommend always selecting.
  • Inspect Files—Disabled unless selected. Inspects files for malicious content hosted on suspicious domains before downloading files. A suspicious domain is one that is neither trusted nor known to be malicious, but might potentially pose a threat—in this case we want to run deeper inspection. Our proxy captures the file, scans it to determine if a threat exists and, if a threat is detected, blocks the file from being downloaded. This can be an explicit download, such as when a user clicks on a link in an email or a download that happens behind the scenes, in so-called 'drive-by download' scenarios. The Umbrella Security Activity and Activity Search reports offer you data on these actions so you can review what Umbrella blocked. For more information about Umbrella's File Inspection feature, see Enable File Inspection .
  • Limit Content Access—When selected, the Limit Content Access step is available in the Policy wizard. These settings filter types of content based on your Organization's acceptable use policies.
  • Apply Destination Lists—When selected, the Apply Destination Lists step is available in the Policy wizard. If you have particular domains you'd like to allow or block, add them to a destination list. There are two by default, block or allow, and you can create more to organize groups of domains. The two defaults are the "Global" lists, meaning they apply to any policy.

Note: If an option listed isn't available, contact your account representative for more information.

Advanced Settings

Underneath the options for what the policy should do, you'll find Advanced Settings.

  • Advanced Settings / Use Custom Settings—The Advanced Settings drop-down list is populated with settings as configured and shared with the customer from the MSSP console. Select an item in the list to change Advanced settings. Use Custom Settings allows you to enable custom intelligent proxy settings for this policy—shield icons change to selectable checkboxes.
  • Enable Intelligent Proxy—The intelligent proxy may also be activated on select packages. Allows for URL-based malware filtering for domains with legitimate content where some pages may contain malicious files. If you choose to not enable the intelligent proxy, some options for what the policy will do are not available as they're not possible without the intelligent proxy. We encourage anyone who's not using the Intelligent Proxy as a part of their policies to try it out. For more information about the intelligent proxy, how it works, and how to enable HTTPS inspection, see Enable Umbrella's Intelligent Proxy.
  • SSL Decryption—Inspects HTTPS traffic. For more information, see SSL Decryption in the Intelligent Proxy.
  • Enable IP-Layer Enforcement—(Roaming Computer identities only.) Tunnels suspect IP connections. To learn more, see Add IP Layer Enforcement.
  • Enforce SafeSearch—A feature of the major search engines that restricts and filters explicit images and results. Umbrella provides the ability to enforce traffic to Google, YouTube and Bing on a per-policy basis. For more information, see What is SafeSearch.
  • Allow-Only Mode—Blocks access to all sites except those specifically allowed. We recommend that you only enable Allow Only Mode in cases where you wish to allow access to a small subset of domains and block all other domains. Since the result of enabling this feature is to effectively block the internet except for that part you've defined to allow, please use caution if enabling this feature.
  • Logging—Provides logging for requests and security events. Settings are:
    • Log All Requests—For full logging, whether for content, security or otherwise
    • Log Only Security Events—For security logging only, which gives your users more privacy (this is a good setting for people with the roaming client installed on personal devices)
    • Don't Log Any Requests—Disable all logging. If you select this option, most reporting for identities with this policy will not be helpful as nothing is logged to report on.
  1. Once you've selected options for what the policy should do, click Next and configure policy settings.
    When you click Next you'll see a progress meter with the number of steps remaining until you've fully configured the policy.

Configure Policy Settings

Security Settings

These settings determine which categories of security threat Umbrella blocks. For more information on what each of these categories represents, see Understanding Security Categories.

When you first access Security Settings, default settings are applied. The blue shield icon indicates a selected and enabled enabled category. You can leave this setting as is, select a different setting or edit settings and create a new one if needed.

  1. To edit settings, click Edit, select or clear categories, and then click Save.

As an alternative to clicking Edit, you can select preconfigured groupings of security settings or create a new setting that you can reuse.
Settings listed here include settings you've created in the MSSP console at Centralized Settings > Security Settings and settings created here in the Umbrella policy wizard.

  1. From the Security Settings drop-down list, choose a security setting or click Add New Setting.
    If you choose Add New Setting, a window appears allowing you to add a new setting.
  1. Give your new setting a meaningful name, select how it is created and then click Create.
  2. If you select Create from Scratch, select security settings and click Save.
    Your security setting is added to the drop-down list.

If you have any custom integrations, they are listed at the bottom of the page under Integrations. Only custom integrations enabled and configured under your account appear.

  1. To enable or disable integrations settings, click Edit.
  1. Select integrations as necessary and click Save.
  2. Once you've configured security settings, click Next.

Content Settings

These settings allow the selection of content categories to be blocked for the identities selected in Step 1 of the Policy wizard. By default, no content categories are blocked.

  1. Select a Content setting: High, Moderate, Low, or Custom.
  2. If you select Custom, select content categories.
    For a list of all categories and details for each, see Understanding Content Categories.
  1. For Custom, optionally select a setting from the drop-down list at the top of the page or select Create New Setting.
  1. If you select Create New Setting, in the Create New Setting window, select options and click Create.
  2. Once you've selected your content settings, click Next.

Destination Lists

Destination lists allow the customization of filtering by creating a list of domains that are explicitly blocked or allowed. Note that each destination list can be set to be a block list (default) or an allow list. Allow list entries will always take precedence over block list entries. For example:

  • Blocking domain.com and adding mail.domain.com to the allowed list will still allow mail.domain.com.
  • Adding domain.com to the Allow List and blocking sub.domain.com will still allow sub.domain.com.
  • Allowing a domain that has been blocked by either Security or Category settings will also trump those block lists.
  1. Select destination lists to include them in your policy.
  1. Click Add New List to create a new destination list.
  2. Pick the type of list you want, give your list a meaningful name, add the destinations you would like to allow or block, and click Save.
    For more information, see our article on adding/removing destinations from a Destination List.
    We recommend adding domains in the format "domain.com" rather than www.domain.com to ensure *.domain.com is included (a wildcard is implicit). However, if you only wish to block subdomain.domain.com, then be more specific when you define the entry here.

Note: Destinations added to a destination list are not saved until you click Save; although, it appears in the list view after adding it.

  1. Once you have selected your destination lists, click Next.

Block Pages

A block page is a page that's displayed when a user of the Umbrella service tries to go to a website that's blocked by the policy. You can also create a bypass so that access can be granted to the block page. You can customize the block page's appearance and redirect to a custom domain.

Note: Not all categories can be bypassed. If a user is blocked for a Security or Malware category, the site is considered malicious and should not be accessed under any circumstances.

  1. If you do not wish to change anything, select Use Umbrella Default Appearance or select Use a Custom Appearance and choose a setting from the list.
    Settings listed here include settings you've created in the MSSP console at Centralized Settings > Block Pages and settings created here in the Umbrella Policy wizard.
  1. Click Preview Block Page at any time to see what your Block page will look like. For example:
  1. To edit a block page setting, choose a setting from the Use a Custom Appearance pull-down, hover over its name and then click the Edit pen icon. The Edit Custom Block Page Appearance window opens.
  1. If you select Use a Custom Appearance and then choose Create New Appearance , first give your custom block page a meaningful name.
  1. Choose a generic message that all block pages will use, or customize the message based on the type of block page by selecting whether Blocked requests should be treated The Same or Differently.
    If you set a custom message, you may insert the [domain] variable into a custom message, which is substituted with the actual domain name that the end user attempted to browse to. You may also insert the [client_ip] variable, which shows the external IP address of the client that is hitting the block page.
    The block can also redirect to a custom URL.
  2. You can also add an email address to your block page that a blocked customer can use to contact an administrator and request access to the blocked destination.
  3. Finally, a custom logo can be uploaded that will be displayed on the block page in place of the Umbrella logo.
  4. Click Save.

Bypass Users

A bypass user can log in (when added to the policy) to bypass the selected type of block pages. The option to bypass the block page is encountered when the block page is presented and the user can then authenticate in order to bypass it. For people without these credentials, the block remains in place. A Bypass User must be checked on a policy in order for it to be active.

Note: Not all categories can be bypassed. If a user is blocked for a Security or Malware category, the site is considered malicious and should not be accessed under any circumstances.

  1. To add a user, navigate to Admin > Accounts.
    Note: The user must already exist in Umbrella to be added as a Bypass User.
  2. Once you have users, under Bypass Users, select a user or click Create New.

If you wish, the bypass can only by applied to specific category filters or destination lists. Note that it is not possible for a bypass user to bypass a security block.

Again, it's essential that this bypass user be applied to the policy that matches the identity that will hit the block page.

Bypass Codes

Bypass codes can be created to allow blocked users to bypass the block page. The bypass code is available for a specified period of time.

Not all categories can be bypassed. If a user is blocked for a Security or Malware category, the site is considered malicious and should not be accessed under any circumstances. If you think a domain shouldn't be blocked, please email us at [email protected].

If you'd like to know more about a block or have us review it in more detail, open a case by emailing [email protected] with information about the domain and our support and security teams will review it.

When enabled (with the check mark) on the policy, the selected categories and/or domains can be bypassed. Ensure to set an expiration for the code or the default is that it will expire within an hour.

Again, it's essential that this code be applied to the policy that matches the identity that will hit the block page.

  1. Once you've set your block page and bypass settings, click Next.

Review and Save Your Policy

Lastly, you'll reach the Policy Summary page. It list all of the configurations to the policy you just made.

  1. Give your policy a meaningful name.
  2. If you want to change anything, click Edit under that setting summary and you'll jump right back to that step. Click Disable to disable that setting.
  1. If you return to a Policy wizard step, when you've made your changes, click Set & Return.
  2. By default, Advanced Settings listed on the Policy Summary page are read-only. To edit an Advanced Setting you must first save your policy.
  1. Once saved, you can expand your policy and make changes to Advanced Settings from the Policy Settings page.
  1. Once you've got everything the way you want it, click Save.

And that's it! Your policy is all set up. As you set up additional identities and configurations for Umbrella, you may need to tweak your policy. When you open an existing policy, it will go directly to the Summary screen, and you can jump between steps in order to make the change you need to make without having to do redo the entire wizard.


Extend Enforcement < Create and Apply Policies > Enable the Intelligent Proxy

Updated 3 years ago

Create and Apply Policies


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.