In the Workspace ONE Access console, enter the information required to connect to your Active Directory and select the users and groups to sync to the Workspace ONE Access directory. The Active Directory connection options are Active Directory over LDAP or Active Directory over Integrated Windows Authentication. Active Directory over LDAP connection supports DNS Service Location lookup.

Prerequisites

  • Install the Directory Sync service, which is available as a component of the Workspace ONE Access connector beginning with version 20.01.0.0. See the latest version of Installing VMware Workspace ONE Access Connector for information.

    If you want to use the User Auth service to authenticate users of the directory, also install the User Auth service component.

  • Select the user attributes that are required, and add custom attributes, if necessary, on the Settings > User Attributes page in the Workspace ONE Access console. See Managing User Attributes in Workspace ONE Access. Keep the following considerations in mind:
    • If a user attribute is required, its value must be set for all the users that you want to sync. Users that do not have a value set are not synced.
    • Attributes apply to all directories.
    • After one or more directories are configured in the Workspace ONE Access service, attributes can no longer be marked required.
  • Make a list of the Active Directory users and groups to sync from Active Directory. Group names are synced to the directory immediately. Members of a group do not sync until the group is entitled to resources or added to a policy rule. Users who need to authenticate before group entitlements are configured should be added during the initial configuration.
    Note: Workspace ONE Access connector version 19.03 and older versions do not support the / and $ characters in a group's name or distinguishedName attribute. This limitation applies to groups that you add to the group DN as well as to groups that are not directly added to the group DN but are synced as part of a parent group when nested group memberships are selected.

    Do not use the / or $ character in a group's name or distinguishedName attribute if you plan to sync the group to Workspace ONE Access and you are using connector version 19.03 or older versions.

  • If you are creating a directory of type Active Directory over LDAP using the Global Catalog option, you must make sure that no other directories in the Workspace ONE Access tenant sync users from the same domains as the Global Catalog directory. The conflict can cause sync failures.
  • For Active Directory over LDAP, you need the Base DN, and the Bind user DN and password.

    The Bind user must have the following permissions in Active Directory to grant access to users and groups objects:

    • Read
    • Read All Properties
    • Read Permissions
    Note: Using a Bind user account with a non-expiring password is recommended.
  • For Active Directory over Integrated Windows Authentication, you need the user name and password of the Bind user who has permission to query users and groups for the required domains.

    The Bind user must have the following permissions in Active Directory to grant access to users and groups objects:

    • Read
    • Read All Properties
    • Read Permissions
    Note: Using a Bind user account with a non-expiring password is recommended.
  • If your Active Directory requires access over SSL/TLS, the Intermediate (if used) and Root CA certificates of the domain controllers for all relevant Active Directory domains are required. If the domain controllers have certificates from multiple Intermediate and Root Certificate Authorities, all the Intermediate and Root CA certificates are required.
    Note: For directories of type Active Directory over Integrated Windows Authentication, SASL Kerberos binding is used for encryption automatically. A certificate is not required.
  • For Active Directory over Integrated Windows Authentication, when you have multi-forest Active Directory configured and the Domain Local group contains members from domains in different forests, make sure that the Bind user is added to the Administrators group of the domain in which the Domain Local group resides. If this is not done, these members are missing from the Domain Local group.
  • For Active Directory over Integrated Windows Authentication:
    • For all domain controllers listed in SRV records and hidden RODCs, nslookup of hostname and IP address should work.
    • All the domain controllers must be reachable in terms of network connectivity.
  • If the Workspace ONE Access connector is running in FIPS mode, additional requirements and prerequisites apply. See Workspace ONE Access Connector and FIPS Mode for your version of the connector.

Procedure

  1. In the Workspace ONE Access console, select Integrations > Directories.
  2. Click Add Directory and select Active Directory.
  3. Enter a name for the Workspace ONE Access directory.
  4. Select the type of Active Directory you are integrating, Active Directory over LDAP or Active Directory over Integrated Windows Authentication.
  5. If you are integrating Active Directory over LDAP, follow these steps, otherwise proceed to step 6.
    1. In the Directory Sync and Authentication section, make the following selections.
      Option Description
      Directory Sync Hosts Select one or more Directory Sync service instances to use to sync this directory. All Directory Sync service instances that are registered with the tenant are listed. You can only select instances that are in Active state.

      If you select multiple instances, Workspace ONE Access uses the first selected instance in the list to sync the directory. If the first instance is unavailable, it uses the next selected instance, and so on. You can reorder the list from the directory's Sync Settings page after creating the directory.
      Authentication Select Yes if you want to authenticate users of this directory with the User Auth service. The User Auth service must already be installed. If you select Yes, the Password (cloud deployment) authentication method and an identity provider named IDP for directoryName of type Embedded are automatically created for the directory.

      Select No if you do not want to authenticate users of this directory with the User Auth service. If you decide to use the User Auth service later, you can create the Password (cloud deployment) authentication method and identity provider for the directory manually. When you do so, create a new identity provider for the directory by selecting Add Identity Provider > Create Built-in IDP in the Integrations > Identity Providers page. Using the pre-created identity provider named Built-in is not recommended.
      User Auth Hosts This option appears when Authentication is set to Yes. Select one or more User Auth service instances to use to authenticate users of this directory. All User Auth service instances that are registered with the tenant and that are in Active state are listed.

      If you select multiple instances, Workspace ONE Access sends authentication requests to the selected instances in round-robin order.
      User Name Select the account attribute that contains username.
      External ID

      The attribute that you want to use as the unique identifier for users in the Workspace ONE Access directory. The default value is objectGUID.

      You can set External ID to any of the following attributes:

      • Any string attribute such as sAMAccountName or distinguishedName
      • The binary attributes objectSid, objectGUID, or mS-DS-ConsistencyGuid

      The External ID setting only applies to users in Workspace ONE Access. For groups, External ID is always set to objectGUID and cannot be changed.

      Important: All users must have a unique and non-empty value defined for the attribute. The value must be unique across the Workspace ONE Access tenant. If any users do not have a value for the attribute, the directory will not be synced.
      Important: If you set External ID to the Active Directory attribute objectGUID or mS-DS-ConsistencyGuid, all users must have a non-empty value for the attribute that is exactly 16 bytes in length.

      Also, make sure that you specify the correct Active Directory attribute name, using the correct case, in the External ID text box. If the name does not match the attribute name in Active Directory, a null value is returned, and directory sync fails. For example, if you use the mS-DS-ConsistencyGuid attribute in Active Directory and you set External ID to ms-DS-ConsistencyGuid, directory sync cannot succeed.

      Keep the following considerations in mind while setting the External ID:

      • If you are integrating Workspace ONE Access with Workspace ONE UEM, make sure that you set the External ID to the same attribute in both products.
      • You can change the External ID after creating the directory. However, the best practice is to set the External ID before syncing users to Workspace ONE Access. When you change the External ID, users are recreated. As a result, all users will be logged out and will have to log in again. You will also have to reconfigure user entitlements for Web apps and ThinApps. Entitlements for Horizon, Horizon Cloud, and Citrix will be deleted and then recreated at the next entitlements sync.
      • The External ID option is available with Workspace ONE Access connector versions 20.10 and later, and 19.03.0.1. All connectors associated with the Workspace ONE Access service must be version 20.10 or later, or they must all be version 19.03.0.1. If different versions of the connector are associated with the service, the External ID option does not display.
    2. In the Server Location and Encryption sections, select from the following options.
      Option Description
      If you want to use DNS Service Location lookup for Active Directory With this option, Workspace ONE Access finds and uses optimal domain controllers. If you do not want to use optimized domain controller selection, do not select this option.
      1. In the Server Location section, select the This Directory supports DNS Service Location check box.
      2. If your Active Directory requires access over SSL/TLS, select the STARTTLS required for all connections check box in the Encryption section.
        Note: If the This Directory supports DNS Service Location option is selected, STARTTLS is used for encryption over port 389. If the This Directory supports DNS Service Location option is deselected, LDAPS is used for encryption over port 636.
      3. Copy and paste the domain controllers' Intermediate (if used) and Root CA certificates into the SSL Certificate(s) text box. Enter the Intermediate CA certificate first, then the Root CA certificate. Ensure that each certificate is in the PEM format and includes the BEGIN CERTIFICATE and END CERTIFICATE lines.

        If the domain controllers have certificates from multiple Intermediate and Root Certificate Authorities, enter all the Intermediate-Root CA certificate chains, one after another.

        For example:

        -----BEGIN CERTIFICATE-----
...
<Intermediate Certificate 1>
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
<Root Certificate 1>
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
<Intermediate Certificate 2>
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
<Root Certificate 2>
...
-----END CERTIFICATE-----
        Note: If your Active Directory requires access over SSL/TLS and you do not provide the certificates, you cannot create the directory.
      If you do not want to use DNS Service Location lookup for Active Directory
      1. In the Server Location section, verify that the This Directory supports DNS Service Location check box is not selected and enter the Active Directory server host name and port number.

        To configure the directory as a global catalog, see the Multi-Domain, Single Forest Active Directory Environment section in Integrating Active Directory with Workspace ONE Access.

      2. If your Active Directory requires access over SSL/TLS, select the LDAPS required for all connections check box in the Encryption section.
        Note: If the This Directory supports DNS Service Location option is selected, STARTTLS is used for encryption over port 389. If the This Directory supports DNS Service Location option is deselected, LDAPS is used for encryption over port 636.
      3. Copy and paste the domain controller's Intermediate (if used) and Root CA certificate into the SSL Certificate(s) text box. Enter the Intermediate CA certificate first, then the Root CA certificate. Ensure that the certificate is in the PEM format and includes the BEGIN CERTIFICATE and END CERTIFICATE lines.
        Note: If your Active Directory requires access over SSL/TLS and you do not provide the certificate, you cannot create the directory.
      If you are integrating the directory as a Global Catalog
      1. In the Server Location section, deselect the This directory supports DNS Service Location option.
      2. Select the This Directory has a Global Catalog option.
      3. In the Server Host text box, enter the Active Directory server host name.
      4. The Server Port is set to 3268. If you select SSL/TLS in the Encryption section, the port is set to 3269.
      5. If your Active Directory requires access over SSL/TLS, select the option LDAPS required for all connections in the Encryption section.
      6. Copy and paste the domain controller's Intermediate (if used) and Root CA certificate into the SSL Certificate(s) text box. Enter the Intermediate CA certificate first, then the Root CA certificate. Ensure that the certificate is in the PEM format and includes the BEGIN CERTIFICATE and END CERTIFICATE lines.
    3. In the Bind User Details section, enter the following information.
      Option Description
      Base DN Enter the DN from which to start account searches. For example, OU=myUnit,DC=myCorp,DC=com.
      Important: The Base DN will be used for authentication. Only users under the Base DN will be able to authenticate. Make sure that the group DNs and user DNs that you specify later for sync fall under this Base DN.
      Note: If you are adding the directory as a Global Catalog, the Base DN is not needed and the option does not appear.
      Bind User DN Enter the account that can search for users. For example, CN=binduser,OU=myUnit,DC=myCorp,DC=com.
      Note: Using a Bind user account with a non-expiring password is recommended.
      Bind User Password The bind user password.
  6. If you are integrating Active Directory over Integrated Windows Authentication, follow these steps.
    1. In the Directory Sync and Authentication section, make the following selections.
      Option Description
      Directory Sync Hosts Select one or more Directory Sync service instances to use to sync this directory. All Directory Sync service instances that are registered with the tenant and that are in Active state are listed.

      If you select multiple instances, Workspace ONE Access uses the first selected instance in the list to sync the directory. If the first instance is unavailable, it uses the next selected instance, and so on. You can reorder the list from the directory's Sync Settings page after creating the directory.
      Authentication Select Yes if you want to authenticate users of this directory with the User Auth service. The User Auth service must already be installed. If you select Yes, the Password (cloud deployment) authentication method and an identity provider named IDP for directory of type Embedded are automatically created for the directory.

      Select No if you do not want to authenticate users of this directory with the User Auth service. If you change your mind later, you can create the Password (cloud deployment) authentication method and identity provider for the directory manually. When you do so, create a new identity provider for the directory by selecting Add Identity Provider > Create Built-in IDP in the Integrations > Identity Providers page. Using the pre-created identity provider named Built-in is not recommended.
      User Auth Hosts This option appears when Authentication is set to Yes. Select one or more User Auth service instances to use to authenticate users of this directory. All User Auth service instances that are registered with the tenant and that are in Active state are listed.

      If you select multiple instances, Workspace ONE Access sends authentication requests to the selected instances in round-robin order.
      User Name Select the account attribute that contains username.
      External ID

      The attribute that you want to use as the unique identifier for users in the Workspace ONE Access directory. The default value is objectGUID.

      You can set External ID to any of the following attributes:

      • Any string attribute such as sAMAccountName or distinguishedName
      • The binary attributes objectSid, objectGUID, or mS-DS-ConsistencyGuid

      The External ID setting only applies to users in Workspace ONE Access. For groups, External ID is always set to objectGUID and cannot be changed.

      Important: All users must have a unique value defined for the attribute. The value must be unique across the Workspace ONE Access tenant.
      Important: If you set External ID to the Active Directory attribute objectGUID or mS-DS-ConsistencyGuid, all users must have a non-empty value that is exactly 16 bytes in length.

      Also, make sure that you specify the correct Active Directory attribute name, using the correct case, in the External ID text box. If the name does not match the attribute name in Active Directory, a null value is returned, and directory sync fails. For example, if you use the mS-DS-ConsistencyGuid attribute in Active Directory and you set External ID to ms-DS-ConsistencyGuid, directory sync cannot succeed.

      Keep the following considerations in mind while setting the External ID:

      • If you are integrating Workspace ONE Access with Workspace ONE UEM, make sure that you set the External ID to the same attribute in both products.
      • You can change the External ID after creating the directory. However, the best practice is to set the External ID before syncing users to Workspace ONE Access. When you change the External ID, users are recreated. As a result, all users will be logged out and will have to log in again. You will also have to reconfigure user entitlements for Web apps and ThinApps. Entitlements for Horizon, Horizon Cloud, and Citrix will be deleted and then recreated at the next entitlements sync.
      • The External ID option is available with Workspace ONE Access connector versions 20.10 and later, and 19.03.0.1. All connectors associated with the Workspace ONE Access service must be version 20.10 or later, or they must all be version 19.03.0.1. If different versions of the connector are associated with the service, the External ID option does not display.
    2. No action is required in the Encryption section. Directories of type Active Directory over Integrated Windows Authentication use SASL Kerberos binding automatically and do not require you to select LDAPS or STARTTLS.
    3. In the Bind User Details section, enter the user name and password of the bind user who has permission to query users and groups for the required domains. Enter the user name as sAMAccountName@domain, where domain is the fully-qualified domain name. For example, jdoe@example.com.
      Note: Using a Bind user account with a non-expiring password is recommended.
  7. Click Save & Next.
  8. In the Select the Domains page, select domains if applicable, then click Next.
    • For a directory of type Active Directory over LDAP, the domains are listed and already selected.
    • For a directory of type Active Directory over Integrated Windows Authentication, select the domains that should be associated with this Active Directory connection. All the domains with a two-way trust relationship with the base domain are listed.

      If domains with a two way trust relationship with the base domain are added to Active Directory after the Workspace ONE Access directory is created, you can add them from the directory's Sync Settings > Domains page by clicking the refresh icon to get the latest list.

      Tip: Choose trusted domains one by one instead of selecting all the domains at once. This ensures that domain save is not a long-running operation that can potentially time out. Choosing domains sequentially ensures that the Directory Sync service spends time trying to resolve a single domain only.
    • If you are creating an Active Directory over LDAP directory with the Global Catalog option selected, the Domains tab does not appear.
  9. In the Map User Attributes page, verify that the Workspace ONE Access directory attribute names are mapped to the correct Active Directory attributes and make changes, if necessary, then click Next.
    Important: If an attribute is marked required, its value must be set for all the users that you want to sync. User records that are missing values for the required attributes will not be synced.
  10. Follow the instructions in Selecting Users and Groups to Sync to Your Workspace ONE Access Directory to add groups in the Select the groups you want to sync page and users in the Select the users you would like to sync page.
  11. In the Sync Frequency page, set up a sync schedule to sync users and groups at regular intervals or select Manually in the Sync Frequency drop-down list if you do not want to set a schedule.
    The time is set in UTC.
    Tip: Schedule the sync intervals to be longer than the time to sync. If users and groups are being synced to the directory when the next sync is scheduled, the new sync starts immediately after the end of the previous sync.
    If you select Manually, you must click the Sync button on the directory page whenever you want to sync the directory.
  12. Click Save to create the directory or Sync Directory to create the directory and start syncing it.

Results

The connection to Active Directory is established. If you clicked Sync Directory, users, and group names, are synced from Active Directory to the Workspace ONE Access directory.

For more information about how groups are synced, see "Managing Users and Groups" in VMware Workspace ONE Access Administration.

What to do next

  • If you set the Authentication option to Yes, an identity provider named IDP for directoryname and a Password (cloud deployment) authentication method are automatically created for the directory. You can view these on the Integrations > Identity Providers and Integrations > Authentication Methods pages. You can also create more authentication methods for the directory from the Authentication Methods page. For information about creating authentication methods, see Managing User Authentication Methods in Workspace ONE Access.
  • Review the default access policy on the Resources > Policies page.
  • Review the default sync safeguards settings and make changes if required. See Setting up Directory Sync Safeguards in Workspace ONE Access for information.