The Umbrella Deployment Documentation Developer Hub

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

Get Started    

Create and Apply Policies

Policies—created through the Policy wizard—let you set the level of protection and security, content access, and logging that are applied to each of your identities.

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

When you first access policies, there's always at least one policy—the Default policy. This policy applies to all identities and cannot be deleted. The Default policy is applied to an identity when no other policy covers that identity. Thus, the Umbrella default policy is a catch-all to ensure all identities within your organization receive a baseline level of protection.

Table of Contents

Step 1: Add a Policy

  1. Navigate to Policies > Management > All Policies and click Add.
    When the Policies page first opens, it only lists the Default policy. You can add a new policy or edit the Default policy. If you edit the Default policy the Summary page opens, from which you can edit the Policy.
    Note: For the Default policy, the ability to edit identities is restricted policy because the Default policy applies to all identities.

Step 2: Select Identities

  1. Select the identities you wish to apply this policy to and click Next.
    This can be any combination of identities available in your dashboard, even if there's just one or two right now. Categories (such as AD Computers or Roaming Computers) can be clicked through to more selectively choose identities. If you only have a single identity—the Network—select that identity.

If you have already created tags, you can also select these. Tags are groupings of roaming computer identities. To set these up, see the next section of documentation for policy best practice. For more information about tags, see Best Practices for Policies and Grouping Identities.

Step 3. Determine what you want this policy to do

  1. Select the policy components you'd like to enable.
    Note: If an option listed isn't available for you, contact your account representative for more information.

Listed options correspond to policy features:

  • Enforce Security at the DNS Layer—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 this.
  • Inspect Files—Selectively inspect files in the cloud, not on premise, so there is no need for additional hardware. The inspection is done with Cisco AMP and an antivirus. For more information, see Enable File Inspection.
  • Limit Content Access—These settings filter types of content based on your organization's acceptable use policies. Typically, this is recommended.
  • Apply Destination Lists—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. It's up to you whether you have anything in particular you'd like to block right away.

Note: A Global Destination List, whether Block or Allow, applies to all policies and all identities. It is 'global' across all your organization's configurations. To define a specific list, create a new list and add domains only to that list, then apply that list to individual sets of identities.

Advanced Settings

  1. Expand Advanced Settings to configure the intelligent proxy and related features, SafeSearch, Allow-Only mode, and logging options.
  • Enable Intelligent Proxy—Uses Cisco Talos web reputation and other third-party feeds to determine if a URL is malicious. The proxy also uses anti-virus (AV) engines and Cisco Advanced Malware Protection (AMP) to inspects files before they are downloaded. When disabled, options such as File Inspection are not available. For more information about the intelligent proxy, see Mange the Intelligent Proxy.

    Note: The intelligent proxy is only available with the Insights and Platform packages, or for customers of MSPs.

    • SSL Decryption—Allows the intelligent proxy to inspect traffic over HTTPS and block custom URLS in destination lists. For more information, see Selective Decryption.
      • Root Certificate—Download and install the Cisco Umbrella root certificate.
      • Selective Decryption—Create a list of content categories to exclude from inspection by the intelligent proxy. For more information, see Enable the Intelligent Proxy.
  • IP-Layer Enforcement—For roaming client identities only, tunnels suspect IP connections to gain visibility into threats that bypass DNS lookups. For more information, see Adding 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—Select 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 access to the internet except for that part you've defined to allow, please use caution if enabling this feature.

Logging 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—a good setting for people with the roaming client installed on personal devices
  • Don't Log Any Requests—Disables 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.

For more information about managing your logs, see Manage Your Logs.

  1. Click Next.
    When you click Next you'll see a progress meter with the number of steps remaining until you've fully configured the policy. Available steps correspond to your policy component selections.

Step 4. Setting your Security and Content Details

Step 4a. Configure Security Settings

These settings determine which categories of security threat Umbrella blocks. For more information on what each category 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.

  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.

Step 4b. Configure Content Settings

These settings allow the selection of content categories to be blocked for the identities selected in Step 1 of the Policy wizard. There are High, Moderate and Low settings with the ability to create a Custom grouping of category types or select an existing Custom list. For a list of all categories and details for each, see Understanding Content Categories.

To create a custom setting:

  1. Select the Custom Settings drop-down, click Create New Setting and select categories to block.

As with security settings, you can add a new content setting and modify an existing one directly from within the wizard.

Step 4c. Configure 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.

Creating a destination list is simple: first, pick the type of list you want, then add the domains you would like to have allowed or blocked and give the list a name.

For more information, see Working with Destination Lists.

Note: Destination lists are not saved until you click Save, although it appears in the list view after entering it.

Limited Availability – An IP Address or CIDR of IP Addresses (Roaming Client Only)

This feature is in Limited Availability and not available to all customers. It requires that the roaming client is installed on the identities for this feature in the policy. If you are running IP Layer Enforcement and would like to try this feature out, please contact to see if you are eligible.

For Destination Allow Lists only (for now), you can add an IP address or a block of IP addresses. The format for the block of IP addresses is standard CIDR notation.

The size of the CIDR cannot exceed a /8, otherwise, you'll receive this error:

If you enter an invalid subnet mask, such as, the IP will be added but the network notation will be ignored.

Otherwise, add any destination that you'd like to ensure isn't blocked now or in the future.

Step 4d. Configure Block Pages

Block Page Settings let you configure a block page that appears when a request is made to access a blocked page. 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.

  • Block Page Settings—This setting let you customize the block page appearance, redirect to a custom domain, and more.
  • Bypass Users—Users who can log in to bypass block pages on this policy. A Bypass User must be checked on a policy in order for it to be active.
  • Bypass Codes—Codes who can log in to bypass block pages on this policy. A Bypass Code must be checked (as above) 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. If you think a domain shouldn't be blocked, please email us at

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

Block Page Settings

If you do not wish to change anything, just use the Umbrella Default Appearance, but this setting also allows for the customization of the block page.

To edit an existing block page:

  1. Hover over the name and click the Edit pen icon.
  1. Select Use a Custom Appearance, then choose Create new Appearance from the drop-down list.

When you create or edit a page, give your settings an easy to remember name, such as "Corporate Block Policy."

Choose a generic message across all block pages, or customize the message per 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.

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

The block can also redirect to a custom URL.

If not redirecting to a custom URL, a contact form can be added to allow blocked users to contact the administrator at the email provided.

Finally, a custom logo can be uploaded to be displayed on the block page in place of the Umbrella logo.

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.

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 user can be 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.

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.

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

Step 5: Set Policy Details

Lastly, you'll reach the Policy Summary. It covers all of the modifications to the policy you just made. If you want to change anything, click the relevant Edit button and you'll jump right back to that step, or disable the feature directly from the Summary screen. When you've made the change, you can jump back to the summary directly without having to click through all the other steps (neat, right?).

Give your policy a meaningful name before saving it. Click Edit to go back and modify settings. Once you've got everything the way you want it, just click Save.

Your policy is complete. As you add identities and configurations for Umbrella, you may need to tweak your policy. When you open an existing policy, the Summary screen opens, and you can jump between steps in order to make the change you need to make immediately without having to do redo the entire wizard.

Point Your DNS to Cisco Umbrella < Create and Apply Policies > Best Practices for Policies and Grouping Identities