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 version 20.01.0.0 or later. See Installing VMware Workspace ONE Access Connector 20.01 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 which user attributes are required and add additional attributes, if necessary, on the User Attributes page in the Workspace ONE Access console. See Managing User Attributes in Workspace ONE Access.
  • 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 enabled.

    Do not use the / or $ character in a group's name or distinguishedName attribute if you plan to sync the group to VMware Identity Manager 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.
  • 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.

Procedure

  1. In the Workspace ONE Access console, navigate to Identity & Access Management > Manage > Directories.
  2. Click Add Directory and select Add Active Directory over LDAP/IWA.
  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 Identity & Access Management > 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.

      Directory Search Attribute 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.

      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 20.10 and 19.03.0.1. All connectors associated with the Workspace ONE Access service must be version 20.10 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. If you want to use DNS Service Location lookup for Active Directory, make the following selections.
      • In the Server Location section, select the This Directory supports DNS Service Location check box.

        Workspace ONE Access finds and uses optimal domain controllers. If you don't want to use optimized domain controller selection, follow step c. instead.

      • If your Active Directory requires access over SSL/TLS, select the This Directory requires all connections to use STARTTLS check box in the Certificates section and copy and paste the domain controllers' Intermediate (if used) and Root CA certificates into the SSL Certificate 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.
    3. If you do not want to use DNS Service Location lookup for Active Directory, make the following selections.
      • 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 #GUID-0D2293FD-7634-40DD-A7ED-8F72401A3939.

      • If your Active Directory requires access over SSL/TLS, select the This Directory requires all connections to use SSL check box in the Certificates section and copy and paste the domain controller's Intermediate (if used) and Root CA certificate into the SSL Certificate field.

        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.
    4. 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.
      Note: 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.
      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 Identity & Access Management > 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.

      Directory Search Attribute 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.

      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 20.10 and 19.03.0.1. All connectors associated with the Workspace ONE Access service must be version 20.10 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. If your Active Directory requires access over SSL/TLS, select the This Directory requires all connections to use STARTTLS check box in the Certificates section and copy and paste the domain controllers' Intermediate (if used) and Root CA certificates into the SSL Certificate 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.
    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 Active Directory over LDAP the domains are listed and already selected.
    • For 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 Refresh 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.
  10. Select the groups you want to sync from Active Directory to the Workspace ONE Access directory.
    Keep the following considerations in mind while adding groups.
    • As a best practice, add and sync a small number of groups when you create a directory. After the initial setup, you can add more groups.
    • When groups are added and synced, group names are synced to the directory. Users that are members of the group are not synced to the directory until the group is entitled to an application or the group name is added to an access policy rule.
      Note: You can override this restriction by enabling the Sync Group Members to the Directory When Adding Group option in the Identity & Access Management > Setup > Preferences page.
    • When you sync a group, any users that do not have Domain Users as their primary group in Active Directory are not synced.
    To select groups, you specify one or more group DNs and select the groups under them.
    1. In the Specify the group DNs row, click + and specify the group DN. For example, CN=users,DC=example,DC=company,DC=com.
      Tip: Entering a high-level DN such as the Base DN to search under is not recommended, as search will take a long time. Try to enter a more specific DN to search under.
      Important: Specify group DNs that are under the Base DN that you entered in the Base DN text box in the Add Directory page. If a group DN is outside the Base DN, users from that DN will be synced but will not be able to log in.
    2. If you want to select all the groups under the group DN, click Select All.
      If groups are added or deleted to the group DN in Active Directory after the directory is created, the changes are reflected in subsequent syncs.
    3. If you want to select specific groups under the group DN instead of selecting all of them, click Select, make your selections, and click Save.
      When you click Select, all the groups found in the DN are listed. You can narrow the results or search for specific groups by entering a search term in the search box.
    4. Select or deselect the Sync nested group members option, as needed.
      The Sync nested group members option is enabled by default. When this option is enabled, all the users that belong directly to the group you select as well as all the users that belong to nested groups under it are synced when the group is entitled. Note that the nested groups are not synced; only the users that belong to the nested groups are synced. In the Workspace ONE Access directory, these users will be members of the parent group that you selected for sync.

      If the Sync nested group members option is disabled, when you specify a group to sync, all the users that belong directly to that group are synced. Users that belong to nested groups under it are not synced. Disabling this option is useful for large Active Directory configurations where traversing a group tree is resource and time intensive. If you disable this option, ensure that you select all the groups whose users you want to sync.

  11. Click Next.
  12. Select the users to sync.
    Keep the following considerations in mind while adding users:
    • Because members in groups do not sync to the directory until the group is entitled to applications or added to an access policy rule, add all users who need to authenticate before group entitlements are configured.
    • The Bind user that you specified in the Bind Details section is not synced to the Workspace ONE Access service by default. If you want to sync the Bind user, enter the user DN on this tab. After the directory is synced, you can set the role for the Bind User if required.
    1. In the Specify the user DNs row, click + and enter the user DNs. For example:

      CN=username,CN=Users,OU=Sales,DC=example,DC=com

      Important: Specify user DNs that are under the Base DN that you entered in the Base DN text box in the Add Directory page. If a user DN is outside the Base DN, users from that DN will be synced but will not be able to log in.
    2. Specify filters to include or exclude users from the DNs, if needed.
  13. Click Next.
  14. 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.
  15. 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 Identity & Access Management > Manage > Identity Providers and Enterprise Authentication Methods pages. You can also create more authentication methods for the directory from the Enterprise Authentication Methods tab. For information about creating authentication methods, see the <AuthGuide> guide.
  • Review the default access policy on the Identity & Access Management > Manage > Policies page.
  • Review the default sync safeguards settings and make changes if required. See Setting up Directory Sync Safeguards for information.