Cisco Secure Access Help

PDF

Cisco Secure Access Help

Manage AD Connectors

Updated: August 24, 2026

Want to summarize with AI?

Log in

Describes Manage AD Connectors in Cisco Secure Access. The Cisco Active Directory (AD) Connector integrates Cisco Secure Access with your instance of Microsoft Active Directory (AD).

The Cisco Active Directory (AD) Connector integrates Cisco Secure Access with your instance of Microsoft Active Directory (AD). Before you can provision users, groups, and endpoint devices from AD to Secure Access, complete the setup of the AD components, register the AD Components in Secure Access, and install the Cisco AD Connector in the organization's environment.

How to Connect Active Directory to Secure Access

The deployment of the AD Connector has various components and configuration settings. You can configure the Cisco AD Connector to provision users and groups from Microsoft AD using LDAP or LDAPS (domain controller or domain), or LDAP Interchange Format (LDIF) source files.

  1. Add domain controllers or domains in Secure Access for LDAP or LDAPS deployments. For more information, see Add AD Components to Secure Access.

  2. (Optional) Configure authentication for the AD Connectors in your environment. For more information, see Configure Authentication for AD Connectors and VAs.

  3. (Optional) Configure updates for the AD Connectors in your environment. For more information, see Configure Updates for on AD Connectors.

  4. Download the AD Connector software package and install it on your AD server. For more information, see Connect Active Directory to Secure Access.

  5. (Optional) Configure the provisioning of users, groups, and endpoint devices with LDIF source files. For more information, see Deploy LDIF Files for AD Connector.

  6. (Optional) Change the AD Connector account password. For more information, see Change the Connector Account Password.

  7. View the installed AD components in Secure Access and verify that users and groups begin to sync with Secure Access. For more information, see View AD Components in Secure Access.

Configure Authentication for AD Connectors and VAs

Cisco Secure Access communicates with the deployed Cisco Active Directory (AD) Connectors in your environments. Secure Access makes software syncs and health checks to the AD Connectors and requires that API requests from the AD Connectors use authentication. For information about deploying the Cisco AD Connector, see Connect Active Directory to Secure Access.

To manage the authentication of the communications from the AD Connectors to Secure Access, we recommend that you configure API key credentials for your AD Connector deployments. Your API key credentials apply to all AD Connectors and Secure Access Virtual Appliances that are deployed in your environment.

For more information about authentication and deploying Virtual Appliances, see Configure Authentication for Virtual Appliances.

Note
The API key authentication is available for Secure Access Virtual Appliances version 3.7.0 and newer and the Cisco AD Connector version 1.14.4 or newer. The API keys apply to the Virtual Appliances and the Cisco AD Connectors in the organization.

How to Set Up Your API Credentials

Create a Secure Access Key Admin API key and secret. Then, use the Secure Access Key Admin API credentials to generate your Secure Access client API key credentials.

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

AD Connectors use the organization's Secure Access client API key credentials to generate an OAuth 2.0 access token, which authorizes API requests from the AD Connectors to Secure Access. The access token is included in every API request from the AD Connector to Secure Access.

Note
Secure Access client API key credentials are valid for 90 days.

Step 1 – Create the Key Admin API Key Credentials

Create a Secure Access Key Admin API key. For more information, see Add Key Admin API Keys

Before you begin

  • Full Admin user role. For more information, see Manage Accounts.
  • Cisco AD Connector version 1.14.4 or newer.

Procedure

Select each type of permission for the key.
Note
Save your Key Admin API key and secret and use these credentials to configure the authentication for the AD Connectors in the organization.

The Key Admin with All Permissions interface.

Step 2 – Add the Key Admin API Key Credentials

Add the Secure Access Key Admin API key and secret to the AD Connector in Users and Groups > Configuration Management > API Authentication. Then, generate a Secure Access client API key and secret.

Before you begin

  • Full Admin user role. For more information, see Manage Accounts.
  • Cisco AD Connector version 1.14.4 or newer.

Procedure

  1. Navigate to Connect > Users, Groups, and Endpoint Devices, and then click Configuration management.



  2. Click Advanced Settings.


    The Secure Access Advanced Settings interface.

  3. For Key Admin API Key, add the Key Admin API key, and for Key Admin Key Secret, add the Key Admin API key secret.

    For information about creating the Key Admin API key, see Step 1 – Create the Key Admin API Key Credentials.

    The Secure Access AD Connector Auth Add Keys interface.

  4. After you add the Key Admin API key and secret, click Generate Client API Key Pair.

  5. Save the Secure Access client API key and secret.

    Secure Access updates the client API key and secret automatically every 90 days.

    The Secure Access Authentication AD Generated interface.

Refresh Client API Key and Secret

Refresh your Secure Access client API key and secret.

Before you begin

  • Full Admin user role. For more information, see Manage Accounts.
  • Cisco AD Connector version 1.14.4 or newer.

Procedure

  1. Navigate to Connect > Users, Groups, and Endpoint Devices, and then click Configuration management.



  2. Click Advanced Settings.

  3. Click Refresh.

    Secure Access refreshes the client API key and secret.

    The Secure Access Authentication AD Generated interface.

  4. For Refresh Client Keys, check the box to confirm the deletion of the client API key and secret.


    The Secure Access Refresh AD Keys interface.

  5. Click Refresh.

Reset Client API Key

Delete your Secure Access Key Admin API key and Secure Access client API key.

Note
After you delete the Key Admin API key and client API key, existing AD Connector deployments may continue to use the stored Secure Access client API key and secret for up to 90 days.

Before you begin

  • Full Admin user role. For more information, see Manage Accounts.
  • Cisco AD Connector version 1.14.4 or newer.

Procedure

  1. Navigate to Connect > Users, Groups, and Endpoint Devices, and then click Configuration management.



  2. Click Advanced Settings.

  3. Click Reset Client API Key.


    The Secure Access Authentication AD Generated interface.

  4. For Reset Client Keys, check the box to confirm the deletion of both the Key Admin API key and client API key for the AD Connectors in the organization.


    The Secure Access AD Reset Key Dialog interface.

  5. Click Reset.

Configure Updates on AD Connectors

You can schedule the date and time that Cisco Secure Access updates the Active Directory (AD) Connector software on your deployed Cisco AD Connectors. When scheduled, Secure Access checks if an AD Connector has the latest version of the software.

If a new version is available, Secure Access removes the installed AD Connector software from your systems and deploys the latest version of the AD Connector.

Select the day and time to update your deployed AD Connectors automatically.

Before you begin

Procedure

  1. Navigate to Connect > Users, Groups, and Endpoint Devices, and then click Configuration management.



  2. For Provisioning, expand Active Directory.

  3. Navigate to Active Directory Connector Auto-Upgrades, and then click Edit.


    The AD Connector Update Configure interface.

  4. For Day, choose the day of the week to update the AD Connector software.

    Note
    The default Day is Any day—On every day of the week, if a software update is available, Secure Access attempts to redeploy the AD Connectors with the latest version of the software.

    The AD Connector Choose Date interface.

  5. For Time Range, choose the four-hour time period to update the AD Connectors on the scheduled day.

    Note
    The default Time Range is 2:00 am - 6:00 am PST.

    The AD Connector Choose Time interface.

  6. Click Save.

Connect Active Directory to Secure Access

The Cisco Active Directory (AD) Connector integrates Cisco Secure Access with your instance of Microsoft Active Directory (AD). Before you can provision users, groups, and endpoint devices from AD to Secure Access, register the AD Components in the environment (domain controller or domain) to Secure Access. Then, download the Cisco AD Connector software package and install the AD Connector in the organization's environment.

This guide describes the steps to install the Cisco AD Connector for LDAP or LDAPS, and provision users and groups from your instance of Microsoft AD to Secure Access.

Step 1 – Download the Active Directory Connector

Download the Cisco AD Connector from Secure Access to your server.

Note
When you download the Cisco AD Connector software package, and if you did not configure API key credentials for the AD Connectors, Secure Access displays a warning message. We recommend that you configure API keys for your AD Connectors. For more information, see Configure Authentication for AD Connectors and VAs.
Note
You must download the ZIP file to the local machine where you plan to run it, or copy it locally from another machine. We do not recommend that you install the Cisco AD Connector from a network drive or run the setup.msi directly from the compressed file.

Before you begin

Procedure

  1. Configure a server to run the Cisco AD Connector, and then sign in to Secure Access on that server.

  2. Navigate to Connect > Users, Groups, and Endpoint Devices, and then click Configuration management.

  3. Under Directories, expand Active Directory.

  4. For Active Directory Connector, click Download to save the Cisco AD connector software package to the server. The deployment package is named: CiscoAuditClient_vX.X.X.zip.


    The AD Connector Download interface.

Step 2 - Install the Active Directory Connector

As an administrator, extract the contents of the Cisco AD Connector ZIP file to a folder on the server, and then navigate to that folder.

Note
If you run the AD Connector installer from the root directory of your server, you may encounter installation errors.

Before you begin

Procedure

  1. Run setup.msi, and then in the Cisco AD Connector Setup wizard, click Next.



  2. Choose the directory on the server to install the Cisco AD Connector.


    The 2 Installation Wizard Default Program Files Folder interface.

  3. Confirm that you permit your AD Users and Groups to sync to Secure Access from the Cisco AD Connector.


    The 2 Installation Wizard Selective Sync and Backend References interface.

  4. Add your Active Directory credentials. Enter the Username of the Connector user (Cisco_Connector or custom username) and the Password.

  5. Follow the remaining prompts in the setup, and when finished click Finish.

(Optional) Specify AD Groups in Selective Sync File

You can specify the AD Groups for the purpose of creating Access rules in Secure Access. Users and computers belonging to these Groups synchronize to Secure Access.

Supported Organizational Units

CN=My Group,OU=Organizational Unit,DC=sample,DC=local

Unsupported Organizational Units

OU=My OU,OU=Organizational Unit,DC=sample,DC=local

Sample File Entries

CN=Engineering,CN=Builtin,DC=ciscoumbrella,DC=com
CN=Sales,CN=Builtin,DC=ciscoumbrella,DC=com
CN=Marketing,CN=Builtin,DC=ciscoumbrella,DC=com

Total Number of Groups Selected for Synchronization

Groups specified in the selective sync file and all of their subgroups should not exceed 15,000. Also, these Groups should not be nested within more than five OU levels. Selective synchronization fails in both cases.

Note
If you can not meet either of these requirements, we recommend that you do not use the selective sync file. Instead, you can do a full AD tree synchronization.

Rename Selective Sync File After Upgrading to AD Connector v1.14.4

If you use selective sync and upgrade the Cisco AD Connectors to v1.14.4 or later, you must rename the current selective sync file C:\CiscoUmbrellaADGroups.dat to C:\CiscoADGroups.dat.

Note: The selective sync file—previously named CiscoUmbrellaADGroups.dat—is not recognized by the Cisco AD Connector v1.1.4.4 or later.

After you rename the selective sync file, Secure Access automatically reads the selective sync file (C:\CiscoADGroups.dat) and syncs the Users in the specific Groups from AD to Secure Access. You are not required to restart the AD Connector service.

Create AD Groups in a Selective Sync File

Before you begin

Procedure

  1. Identify the AD Groups of interest. Users and computers belonging to these Groups synchronize to Secure Access. For each sub-tree, only the parent group needs to be specified. All AD groups, users, and computers that are part of this parent group are automatically included.

    Note
    If you enabled Selective Sync, AD Users and Computers that are not members of Groups specified in CiscoADGroups.dat or their subgroups are not synchronized to Secure Access and are completely exempt from Secure Access access rules and reports.
    Note
    When configuring Selective Sync for Cisco AD Connector, do not use top-level built-in groups such as Domain Users or Domain Computers in the group filter. These built-in primary groups typically include most or all identities in the domain. In multi-domain environments, their use may result in users and computers from all domains being synchronized unintentionally. To maintain precise and predictable control over which identities are synchronized, create and use dedicated custom groups for selective sync instead.

  2. Create a CiscoADGroups.dat file in the C:\ drive of each machine where the connector is installed. The connector only reads the C:\CiscoADGroups.dat file. If the file is incorrectly named or is not present in the C:\ drive, all groups are imported to Secure Access.

  3. List the AD groups that need to be synchronized in distinguished name (DN) format in this file.

  4. Ensure that there are no blank lines anywhere in the file.

    Note
    If you are running multiple AD Connectors, the file C:\CiscoADGroups.dat should be present on each system running the AD Connector and should be identical on each system.

Deploy LDIF Files for AD Connector

The Cisco Active Directory (AD) Connector integrates with Cisco Secure Access to provision the organization's users and groups from AD. You can install and configure the AD Connector to provision users and groups using LDAP Interchange Format (LDIF) source files. Once you deploy the LDIF files on your server, the AD Connector syncs the users and groups in your organization with Secure Access.

For information about deploying the AD Connector with LDAP or LDAPS, see Connect Active Directory to Secure Access.

Best Practices for LDIF Source Deployments

  • Do not combine manually provisioned (CSV file) users and groups with LDIF-based sourcing deployments. If you use both deployment methods, you may add duplicate users and groups in your organization.
  • To migrate from the manually provisioned users and groups to LDIF-based sourcing, delete the CSV file with the users and groups that you uploaded to Secure Access.
  • If you have multiple Active Directory deployments and choose to manually provision users and groups, we recommend that you deploy the AD Connector with LDIF source files.
  • Once you provision users and groups with LDIF-based sourcing, we do not recommend that you delete the deployment and provision the users and groups using another deployment method.
  • LDIF-based sourcing does not require Secure Access Domain Controllers.

Requirements

Requirements for deploying LDIF source files on your server:

  • LDIF can support multiple domains.
  • Create the LDIF files in the Text document format.

Known Limitations

  • No support for selective groups-only sync.
  • No support for incremental sync.

Download, install, and configure the Cisco AD Connector. Then, deploy the LDIF source files.

Step 1 – Download the Active Directory Connector

Download the Cisco AD Connector from Secure Access to your server.

When you download the Cisco AD Connector software package, and if you did not configure API key credentials for the AD Connectors, Secure Access displays a warning message. We recommend that you configure API keys for your AD Connectors. For more information, see Configure Authentication for AD Connectors and VAs.

Note
You must download the ZIP file to the local machine where you plan to run it, or copy it locally from another machine. We do not recommend that you install the Cisco AD Connector from a network drive or run the setup.msi directly from the compressed file.

Before you begin

  • Full Admin user role. For more information, see Manage Accounts.
  • For information about network requirements, and connector user account and server prerequisites, see Prerequisites for AD Connectors.
  • Cisco AD Connector version 1.14.4 or newer.

Procedure

  1. Configure a server to run the Cisco AD Connector, and then sign in to Secure Access on that server.

  2. Navigate to Connect > Users, Groups, and Endpoint Devices, and then click Configuration management.

  3. Navigate to Directories, expand Active Directory.

  4. For Active Directory Connector, click Download to save the Cisco AD connector software package to the server. The software package is named: CiscoAuditClient_vX.X.X.zip.


    The AD Connector Download interface.

Step 2 – Install the Cisco AD Connector

As an administrator, extract the contents of the ZIP file that you downloaded to a folder and then navigate to that folder.

If you run the Cisco AD Connector installer files from the root directory of your device, you may encounter installation errors.

Before you begin

  • Full Admin user role. For more information, see Manage Accounts.
  • For information about network requirements, and connector user account and server prerequisites, see Prerequisites for AD Connectors.
  • Cisco AD Connector version 1.14.4 or newer.

Procedure

  1. Run setup.msi.

  2. Enter the username of the Connector user (Cisco_Connector or custom username) and the password.

    For more information, see Prerequisites for AD Connectors.

  3. Select Local LDIF files lookup, and then click Next.

  4. Follow the prompts in the setup, and then click Finish.


    The AD Connector Ldif Select interface.

Step 3 – Deploy the LDIF Source Files

Deploy the LDIF source files on your server.

Before you begin

  • Full Admin user role. For more information, see Manage Accounts.
  • For information about network requirements, and connector user account and server prerequisites, see Prerequisites for AD Connectors.
  • Cisco AD Connector version 1.14.4 or newer.

Procedure

  1. Navigate to the C:\ drive on your server.

  2. Generate the LDIF files for the users and groups in your organization, and zip the files into a file. Name the file Cisco-AD-Connector-LDIF.zip.

    • Base-64 encode the value of the objectGUID fields.
    • Use two colons (::) to separate the objectGUID fields.
    • For users, create an UserStruct.ldif file. The supported fields are:
      • dn, objectGUID, sAMAccountName, userPrincipalName, memberOf, and primaryGroupID.
    • For groups, create a GroupStruct.ldif file. The supported fields are:
      • dn, objectGUID, sAMAccountName, userPrincipalName, memberOf, and primaryGroupToken.

    The AD Connector Ldif Directory interface.

Troubleshooting

Various configuration conditions of the AD Connector with LDIF source files can result in provisioning errors.

Scenario 1

  • You uploaded an Cisco-AD-Connector-LDIF.zip file with users and groups in a particular set of domains. Later, you uploaded another Cisco-AD-Connector-LDIF.zip file (with a different set of domains) and expected only the identities from these domains to be present. However, the identities from the domain of the previous upload were retained and not removed.

Possible Cause: This configuration is not supported.

Solution: Raise a request with Cisco Support.

Scenario 2

The Cisco-SSE-AD-Connector-LDIF.zip file is not found. The Cisco AD Connector can not sync the users and groups with Secure Access.

Solution: Ensure that the Cisco-AD-Connector-LDIF.zip file is located under the C:\ drive on the server.

Scenario 3

If one or both of the LDIF source files (UserStruct.ldif and GroupStruct.ldif) are not present or empty, then the Cisco AD Connector can not sync the users and groups with Secure Access.

Solution: Verify the contents in the Cisco-AD-Connector-LDIF.zip file and upload the file to the C:\ drive on the server.

Scenario 4

Ensure that all fields in the LDIF source files are valid with no inappropriate values. The dn field is required and should contain appropriate values.

Analyze Logs

You can find the Cisco AD Connector logs on the server in the C:\Program Files (x86)\Cisco\CiscoAD Connector\v1.14.4 folder. The log files are:

  • For errors—CiscoAuditClient.error.log.
  • For all events—CiscoAuditClient.log.

Change the Connector Account Password

For regulatory compliance, you may need to change the password of the Cisco Active Directory (AD) Connector account. You can modify this password without impacting the functionality of the Cisco AD Connector.

Changing the password on the Cisco AD Connector ensures that the AD connector can communicate with Microsoft AD using the new credentials. If the AD Connector account password is not correct, the Cisco AD Connector is unable to subscribe to login events and AD changes.

Note
If the password is not changed, Secure Access can not identify DNS requests with the AD users or groups accurately, and can not sync user and group changes from AD.

Before you begin

  • Administrative privileges on the server where you will install the AD Connector.

  • Install and set up the AD Connector on a server in your organization. For more information, see Connect Active Directory to Secure Access.

Procedure

  1. Sign in to the account from any system that is a member of the domain and then set the new password.

  2. Stop the Cisco AD Connector service.

  3. Navigate to C:\Program Files (x86)\Cisco\CiscoADConnector and run the file CiscoPasswordManager.exe.

    You may need to run this utility as an administrator.

  4. When prompted, add your new password.

  5. Start the Cisco Active Directory Service service.

What to do next

Repeat steps 2 and 3 for each deployed AD Connector.

AD Connector Communication Flow and Troubleshooting

The Cisco Active Directory (AD) Connector is a Windows application and service that communicates with Cisco Secure Access and AD domain controllers. The Cisco AD Connector only syncs the required AD User and Group attributes with Secure Access.

The following information describes the communication flow between a Cisco AD Connector and AD domain controllers, the attributes that sync between AD, the AD Connector, and Secure Access, and the steps that you can take to troubleshoot your Cisco AD Connector deployment. The diagram includes the deployment of the Secure Access Virtual Appliance.


The AD Conn Comm Flow interface.

Communication Flow

  1. The Cisco AD Connector first attempts to communicate to the AD domain controller over secure lightweight directory access protocol (LDAPS) on port 646. If unsuccessful, the Cisco AD Connector falls back to communicating over LDAP on port 389 using first Kerberos authentication and if that does not succeed, NTLM authentication (Windows NT LAN Manager) over LDAP.

  2. The Cisco AD Connector retrieves the AD Users, Groups, and Endpoint Devices details only. Secure Access stores these required attributes from each object:

    • cn—The common name.

    • dn—The distinguished name.

    • dNSHostName—The device name as it is registered in DNS.

    • mail—Email addresses associated with the user.

    • memberOf—The groups that include the user.

    • objectGUID—The group ID of the object. This property is sent to Secure Access as a hash.

    • primaryGroupId—The primary group ID that is available for Users and Groups.

    • primaryGroupToken—The primary group token that is available only for Groups. Passwords or password hashes are not retrieved. Secure Access uses the primaryGroupToken data in the access policy and configuration and reporting. This data is also required for each user or per-computer filtering.

    • sAMAccountName—The username that you use to sign into the Cisco AD Connector.

    • userPrincipalName—The user's principal name.

      Note
      If there are updates, the Cisco AD Connector sends the AD data every five minutes using an HTTPS connection on TCP port 443. However, it can take an hour or longer for changes to reflect in Secure Access.

  3. The Cisco AD Connector stores the AD User and Group data locally in .ldif files.

    The local AD User and Groups data is contained within this folder: C:\\Program Files (x86)\\Cisco\\CiscoADConnector\\ADSync.

    Review the files in the .ldif files in the ADSync directory to confirm that the Cisco AD Connector synchronized the AD Users and Groups data to Secure Access.

    Note
    When you install the Cisco AD Connector, you have the option to turn off the local storage of .ldif files.

    The 2 Installation Wizard AD Provisioning and LDIF File Name interface.

Troubleshooting

Recommendations for troubleshooting the communications with the Cisco AD Connector.

Network Requirements

The Cisco AD Connector communicates with Secure Access and the deployed domain controllers. Ensure that you allow certain domains and services on your firewalls. For more information, see Network Requirements for Secure Access.

Port and Protocol Source Destination Note
443/TCP AD Connector api.sse.cisco.com disthost.umbrella.com
  • Initial registration with the Secure Access
  • Automatic updates
  • Health status reporting in Secure Access
80/TCP AD Connector validation.identrust.com/crl/hydrantidcao1.crl Check for certificate revocations through the certificate revocation list (CRL).
80/TCP AD Connector commercial.ocsp.identrust.com/ Check for certificate revocations through the Online Certificate Status Protocol (OCSP).
389/TCP 636/TCP AD Connector Domain controller or domain Sync with LDAP/LDAPS
Note
The Digicert domains resolve to various IP addresses based on a CDN and are subject to change.

If you experience any issues communicating with Secure Access, we recommend that you check for any Layer-7 application proxies, which may block or drop data sent to Secure Access. A common case is the inspect feature on Cisco devices that communicate on DNS, HTTP, or HTTPS. For more information, see Cisco Security Appliance Command Line Configuration Guide, Version 7.2.

Restart the Active Directory Connector

You can restart the Cisco AD Connector service on the AD Connector server. Restarting the Cisco AD Connector triggers a full synchronization of the AD Users and Groups, not only the changes from the previous sync to Secure Access.

If your Cisco AD Connector is not in the Okay state, contact Support. For more information, see the contact support section in the Welcome to Secure Access topic.