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    

Provision Identities from Okta

Cisco Umbrella supports the provisioning of user and group identities from Okta.
This integration can be used for the following deployments:

  • Umbrella DNS:
    • To enable user identity support for the Umbrella Roaming Client and AnyConnect.
  • Umbrella SWG:
    • To enable user identity support for the AnyConnect SWG module.
    • To provision user and group identities for use with SAML-based user authentication.

The Okta integration eliminates the need to deploy an on-premise Umbrella Active Directory Connector for these use cases.

Note: An on-premise Umbrella AD connector is mandatory for virtual appliance or IP-to-user mapping deployments because Okta does not store the private IP – AD user mappings that are required for these deployments.

Table of Contents


  • A valid Okta subscription.
  • No concurrent provisioning from on-premise Active Directory and Okta .
    If you are using the on-premise Umbrella AD Connector to import user and group identities to Umbrella, and now wish to import the same identities from Okta, ensure that the on-premise Umbrella AD connector is switched off or that the OpenDNS Connector service on the connector machine is stopped.
  • Full admin access to the Umbrella dashboard. See Manage User Roles.

Note: Concurrent synchronization of the same user and group identities from the Umbrella AD Connector and the Cisco Umbrella Okta application is not supported and will lead to inconsistent policy enforcement. 


  • A maximum of 200 groups can be provisioned from Okta to Cisco Umbrella. Any groups beyond this number that are in scope can not be provisioned. There is no restriction on the number of users that can be provisioned from Okta to Umbrella.
  • To ensure that all users are provisioned, ensure that the ‘Everyone’ group is assigned to the Cisco Umbrella app.  You can push other additional groups as required for group-based Umbrella policy enforcement. 
  • Okta does not support nested groups.
  • If you have previously imported groups from on-premise Active Directory and are pushing the same groups from Okta, the groups from Okta will not overwrite the groups imported from on-premise Active Directory. You will need to re-assign any group-based Umbrella policies to the groups imported from Okta.
  • Depending on the number of users and groups being provisioned, it can take several hours for these identities to be available on the Umbrella dashboard.
  • After the initial provisioning of users and groups, it can take up to one hour for subsequent changes to users and groups to reflect on the Umbrella dashboard.

Supported Features

The following Okta provisioning features are supported:

  • Create Users—New users created in Okta will also be created in Umbrella.
  • Update User Attributes—Updates to a user's profile through Okta will be pushed to Umbrella.
  • Deactivate Users—Deactivating a user through Okta deactivates the user in Umbrella.
  • Group Push—Groups in Okta can be pushed to Umbrella.

Import the ObjectGUID Attribute from Okta

The on-premise Umbrella AD Connector, Cisco AnyConnect, and Umbrella Roaming Clients rely on the objectGUID attribute for user and group identification. You need to ensure that the objectGUID attribute of users is synchronized from Okta to Cisco Umbrella only if either of the conditions below are true:

  • You have previously imported AD users to Umbrella using the on-premise Umbrella AD connector, are now importing the same user identities from Okta and want the previously imported identities to be persisted for policy or reporting purposes.
  • You have endpoints that are authenticating against on-premise Active Directory and are running the Cisco AnyConnect agent or Umbrella Roaming Client.

Note: Before setting up the import of the objectGUID, ensure that the on-premise Umbrella AD Connector that is synchronizing these identities is switched off or that the OpenDNS Connector service on the connector machine is stopped.

The Okta Active Directory agent does not synchronize the ObjectGUID attribute of users from on-premise Active Directory to Okta by default.

  1. Navigate to the Directory Integrations tab on your Okta portal, and click the Provisioning tab. Select To Okta from the drop-down list.
  1. Navigate to Profile Editor under Okta Attribute Mappings and create a custom attribute of string type called objectGUID.
  1. Create a new User Profile Mapping for your AD domain to Okta User:
    appuser.externalId > objectGUID
  2. Under Okta Attribute Mappings, do a Force Sync of attributes to ensure that the objectGUID attribute for users is imported from AD.

Configure the Cisco Umbrella App

  1. In Umbrella, navigate to  Deployments  >  Core Identities  >  Users and Groups.
  1. Expand the Okta card and click API Keys.
  1. Expand Okta provisioning on the API Keys page and click  Generate Token.

Umbrella only displays the generated token once. Copy and save the URL and the token.

  1. Log into Okta and add the Cisco Umbrella User Management app.
  2. On the Provisioning tab of this app, select Enable API Integration and add the API token. Test the API credentials and save.
  1. In the Provisioning to App section, enable the Create Users, Update User Attributes, and Deactivate Users options. Without these options selected, identities will not be provisioned.
  1. Verify that the following attributes are chosen for synchronization to Umbrella. Other attributes are not required.
    • Username 
    • Given name 
    • Family name 
    • Display name
    • Primary email

Note: Umbrella does not list the Given name and Family name attributes for users. Umbrella only lists the Display name and Username attributes.

  1. If you need to import the ObjectGUID attribute for users:

a. Add a new attribute with the following criteria:

  • Display name, Variable name, and External name set to nativeObjectId
  • Scope set to User personal
  • External namespace set to urn:ietf:params:scim:schemas:extension:ciscoumbrella:2.0:user

b. Navigate to the Profile Editor and create a new User Profile Mapping (Okta User to Cisco Umbrella User Management user) for user.objectGUID > nativeObjectId and save the mapping. Select the option to Apply the Mappings to All Users with this Profile.

  1. Once provisioning is configured, assign users (people) to this app through the Assignments tab of the app.  You can assign individual users or specific groups to the app. To assign all users, assign the Everyone group to the app. 

Note: Assigning groups to the app will not provision these groups to Umbrella. Only users that are members of the assigned groups will be provisioned.  Do not manually enter any value for the nativeObjectId field when assigning any groups and users. To avoid provisioning errors, leave this field as-is.

Once users and groups are assigned, these users will automatically start getting provisioned to Umbrella. Wait for all users to show up on the Umbrella dashboard before starting to push groups. This can take time depending on the number of users provisioned.  

  1. Once you have confirmed that all users have been provisioned to Umbrella, you can provision groups and group membership to Umbrella using the Push Groups tab of the Cisco Umbrella app on the Okta portal. Pushing a group does not sync any users and only provisions the group to Umbrella.

Note: Okta does not recommend pushing groups that are assigned to the application. So if you have assigned the ‘Everyone’ group to the application, you should not push the same group.

Cisco Umbrella supports provisioning of 200 groups maximum. It is recommended to push only the groups that you wish to configure Umbrella policy on.

  1. You can view the provisioning logs from the Cisco Umbrella app to analyze the progress of provisioning. 
  1. You can view the users and groups provisioned from Okta on the Users and Groups page.

Note: Cisco Umbrella recommends refreshing the SCIM token at least once every 180 days for security reasons. You can refresh the token on the API Keys page of the Umbrella dashboard. Ensure that you immediately copy the new token to the Cisco Umbrella app on Okta so that provisioning is not impacted. Refreshing the SCIM token is the full responsibility of the user; Umbrella does not perform this action.


For any issues integrating Okta SCIM with Umbrella, contact Umbrella Support.

Provision Identities from Azure AD < Provision Identities from Okta > Active Directory Integration with Virtual Appliances

Updated 18 days ago

Provision Identities from Okta

Suggested Edits are limited on API Reference Pages

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