In the Workspace ONE Access console, create a directory, 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. An 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 for the attribute 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 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.
  • 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. From the Add Directory drop-down menu, select Active Directory.
    The Add Directory drop-down choices are Active Directory, LDAP Directory, and Local User Directory.
  3. In the Directory Information section, enter the following information.
    Option Description
    Directory Name Enter a name for the Workspace ONE Access directory.
    Type Select the type of directory, Active Directory over LDAP or Active Directory over Integrated Windows Authentication.
  4. If you selected Active Directory over LDAP as the directory type, follow these steps for the Configure Directory section, otherwise proceed to the next step.
    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 tab after creating the directory.
      Authentication Select Set up password authentication for this directory 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 this option, the Password (cloud deployment) authentication method and an identity provider named IDP for directoryName of type Embedded are automatically created for the directory.

      Select Add authentication methods later 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 > Built-in IDP in the Integrations > Identity Providers page. Using the pre-created identity provider named Built-in is not recommended.
      User Authentication Hosts This option appears when Authentication is set to Set up password authentication for this directory. 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. All connectors associated with the Workspace ONE Access service must be version 20.10 or later. If different versions of the connector are associated with the service, the External ID option does not display.
    2. To configure the Server Location and Encryption options, select from the following choices.
      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. For Server Location, select the This directory supports DNS service location check box.
      2. If your Active Directory requires access over SSL/TLS, select the Require STARTTLS 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 in the Server Host and Server Port text boxes.

        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 Require LDAPS 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 Require LDAPS 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.
  5. If you selected Active Directory over Integrated Windows Authentication as the directory type, follow these steps for the Configure Directory section.
    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 tab after creating the directory.
      Authentication Select Set up password authentication for this directory 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 this option, the Password (cloud deployment) authentication method and an identity provider named IDP for directory of type Embedded are automatically created for the directory.

      Select Add authentication methods later 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 > Built-in IDP in the Integrations > Identity Providers page. Using the pre-created identity provider named Built-in is not recommended.
      User Authentication Hosts This option appears when Authentication is set to Set up password authentication for this directory. 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. All connectors associated with the Workspace ONE Access service must be version 20.10 or later. If different versions of the connector are associated with the service, the External ID option does not display.
    2. No action is required for the Encryption option. 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.
  6. Click Save.
  7. In the Select Domain(s) section, select the domains, then click Save.
    • For a directory of type Active Directory over LDAP, the domains are listed. Select the domains to associate with the Workspace ONE Access directory.
    • For a directory of type Active Directory over Integrated Windows Authentication, select the domains to associate with the Workspace ONE Access directory. 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 tab.

      Tip: Choose trusted domains one by one instead of selecting all the domains at once. This approach 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 Select Domain(s) section does not appear.
  8. In the Map User Attributes section, map the Workspace ONE Access directory attributes to Active Directory attributes, then click Save.

    You can add attributes and manage the list of required attributes from the Settings > User Attributes page.

    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 required attributes will not be synced.
  9. In the Sync groups section, add the groups that you want to sync. See Select Users and Groups to Sync to Your Workspace ONE Access Directory for information.
  10. In the Sync users section, add the users that you want to sync. See Select Users and Groups to Sync to Your Workspace ONE Access Directory for information.
  11. In the Sync Frequency section, set up a sync schedule to sync users and groups at regular intervals or select Manually from the Sync Frequency drop-down menu 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 it takes to sync the directory. 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 select Sync > Sync with safeguards or Sync > Sync without safeguards on the directory page whenever you want to sync the directory.
  12. Click Save to create the directory or Save & Sync to create the directory and start syncing it.

Results

The connection to Active Directory is established. If you clicked Save & Sync, 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 Set up password authentication for this directory, 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 Connector Authentication Methods and Authentication Methods pages. 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 Set up Directory Sync Safeguards in Workspace ONE Access for information.