Guides
ProductDeveloperPartnerPersonal
Guides
ProductDeveloperPartnerPersonal

Configure Authentication for Virtual Appliances

Suggest Edits

Cisco Umbrella communicates with the Umbrella Virtual Appliances (VAs) that are deployed in your organization. Umbrella makes software syncs and health checks to your VAs and requires that API requests from the VAs use authentication.

To manage the authentication of the communications from the VAs to Umbrella, we recommend that you configure API key credentials for your VA deployments. Your API key credentials apply to all VAs deployed in your organization.

For more information about deploying Umbrella Virtual Appliances, see Deploy Virtual Appliances.

How to Set Up Your API Credentials

  1. First, create the Umbrella Key Admin API key and secret.
  2. Then, use your Umbrella Key Admin API key credentials to generate your Umbrella client API key and secret.

Your Umbrella client API key credentials are stored in the Virtual Appliances deployed in the organization.

Note: Umbrella client API key credentials are valid for 90 days.

Virtual Appliances use your Umbrella client API key credentials to generate an OAuth 2.0 access token. The access token is included in every API request from the Virtual Appliance to Umbrella.

Authentication for VAs is available in Umbrella Virtual Appliance version 3.7.0 and newer.

Table of Contents

Prerequisites

  • Full Admin role in Umbrella. For more information, see Manage Accounts.
  • Umbrella Virtual Appliance version 3.7.0 and newer.

Procedure

Create an Umbrella Key Admin API key and secret. Use the Umbrella Key Admin API credentials to generate your Umbrella API key credentials.

The Umbrella client API key and secret are stored in the VAs that you deploy in your environments. The generated API credentials (key and secret) apply to all VAs in the organization.

Step 1 – Create the Key Admin API Key Credentials

  1. Create an Umbrella Key Admin API key. For more information, see Add Key Admin API Key.
    Select all of the permissions for the key.



    Note: Save the Umbrella Key Admin API key and secret and use these credentials to configure the authentication for the VAs in the organization.

Step 2 – Add the Key Admin API Key Credentials to Sites and Active Directory

Add the Umbrella Key Admin API key and secret to the Sites (Virtual Appliances) and Active Directory configuration in Umbrella.

  1. Navigate to Deployments > Configuration > Sites and Active Directory.

  2. Click Settings and then select Manage Credentials.

  3. Add the Key Admin API key and secret. For more information, see Step 1 – Create the Key Admin API Key Credentials.


  1. Copy and save the Umbrella client API key and secret to your local environment.

Refresh API Key Credentials

Refresh your Umbrella client API key and secret.

  1. Navigate to Deployments > Configuration > Sites and Active Directory.

  2. Click Settings and then select Manage Credentials.

  3. Click Refresh, and then click Save.
    The Umbrella API client key and secret are removed.


Note: After you refresh your Umbrella API key credentials, create a new Umbrella API key and secret. For more information, see Step 1 – Create the Key Admin API Key Credentials.

Delete API Keys

Delete your Umbrella Key Admin API key and Umbrella client API key. Unless you have unusual circumstances, we do not recommend that you delete your Umbrella API keys.

🚧

Important

After you delete the Umbrella Key Admin API key and Umbrella client API key, existing Virtual Appliance deployments continue to sync with Umbrella and authenticate with your Umbrella API client credentials for up to 90 days.

  1. Navigate to Deployments > Configuration > Sites and Active Directory.

  2. Click Settings and then select Manage Credentials.

  3. Click Delete to open the confirmation window.

  4. Check the box to confirm the deletion of the Umbrella Key Admin API key and the Umbrella client API key.

  5. Click Delete to remove both API keys.

Recreate API Key Credentials for Authentication

Once you remove your Umbrella API key credentials, you can create new credentials and add these credentials to your VAs manually. For more information, see Other Configurations: Configure API Key Credentials for Authentication.


Deploy Virtual Appliances < Configure Authentication for Virtual Appliances > Deploy VAs in Hyper-V for Windows 2012 or Higher

Updated 2 days ago