The Umbrella User Guide Developer Hub

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

Get Started    

Add Customer CA Signed Root Certificate

The ability to use your own CA signed root certificate instead of the Cisco Umbrella root certificate is limited to identities that are added to the Web policy. For more information about the Web policy, see Manage the Web Policy.

Umbrella requires that you configure identities to use a certificate in any circumstance where Umbrella must proxy and decrypt HTTPS traffic intended for a website. A trusted root certificate must be installed in all browsers that an identity uses. It is required for Block Pages and HTTPS Inspection. For Block Pages, if you visit a blocked domain through HTTPS, a certificate must be installed so that Umbrella presents a block page rather than a browser error. For HTTPS Inspection, if a domain is proxied, a certificate must be installed so that Umbrella can decrypt HTTPS traffic without the browser presenting an error.

For DNS policies, you can only use the Cisco Umbrella root certificate. For the Web policy, you can use either the Cisco Umbrella root certificate or your own CA-signed certificate. To use your own certificate there are several extra steps you must take so that Umbrella "knows" about your certificate.

By default, all identities use the Cisco Umbrella root certificate unless you configure identities to use your own CA-signed certificate.

Certificate Requirements

When issuing your own CA-signed certificate, the following requirements must be followed:

  • The “Subject Name” in the CSR file downloaded from Umbrella must be honored.
  • The certificate must be valid for no more than three years.
  • The certificate must be an X509v3 certificate with an RSA public key not less than 2048 and no more than 4096.
  • One of the following signature algorithms must be used:
    • SHA256withRSA
    • SHA384withRSA
    • SHA512withRSA
  • The following X509v3 extensions must be included:
    • X509v3 Basic Constraints marked as critical: CA:TRUE
    • X509v3 Key Usage, marked as critical: Certificate Sign, CRL Sign

For more information about how to install certificates in browsers, see Install the Cisco Umbrella Root Certificate.

Procedure

Note: Umbrella supports a maximum of six certificates.

  1. In Umbrella, navigate to Deployments > Configuration > Root Certificate and click Add.
  1. Give your certificate a good descriptive name—Certificate Identifier—and then click Save.
  1. Download Umbrella's certificate signing request (.csr) file and then click Done.
    Use a tool such as Microsoft Certificate Services or OpenSSL to sign it with your CA.

Certificate status is "Pending CA Signing" until you upload your own CA signed root certificate.
Note: If you do not download the CSR file, status is "Pending CSR Download".

  1. Sign the download .csr file with your CA.
  2. Once you have signed the downloaded .csr file, click Upload CA.
    Note: If you do not download the CSR file, the button is labeled "Download CSR".
  1. Browse to the certificate you have generated with Umbrella's CSR, and then click Save.
    You can optionally also upload your CA's public root certificate to Umbrella. This allows Umbrella to validate the certificate you are uploading to Umbrella.
  1. Click Save again.
    Certificates are added to Umbrella.
  1. Click Select Identities.
  1. Select identities that will use this certificate and then click Save.
    Expand identities to select individual identities that will use this certificate.
    Note: Greyed out identities have already been assigned to a certificate. You can only assign an identity to one certificate.

Note: It may take several minutes for configuration changes to take effect.

  1. Install your own signed certificate into all browsers that selected identities will use. Umbrella now knows to trust this certificate. For more information about how to install certificates in browsers, see browser specific documentation.

Updated 3 months ago

Add Customer CA Signed Root Certificate


Suggested Edits are limited on API Reference Pages

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