Skip to main content

Getting started

This page takes a tenant from nothing to its first change in Active Directory. You need:

  • an organization on Entrosity Hub with an Entrosity Axis tenant and a site connector installed on a domain controller (Setting up the domain controller);
  • the Tenant admin role in Vertex for that organization;
  • someone who is a local administrator of the domain controller (for the connector's local guard).
The web interface is in development

The steps below name what you do, not where you click: until the Vertex web interface is available, each step is one API call (Vertex API). The calls are given in brackets.

1. Enable Vertex for the organization​

While Vertex is in beta, only platform admins see it. A platform admin releases it to the organization on the Hub (Products in beta), and the organization's admins give Tenant admin or Helpdesk to their members (Roles).

2. Prepare the domain controller​

Install the Axis site connector on a domain controller, make sure Windows PowerShell remoting works, and create the AD account Vertex acts as, with rights on the OUs it will manage: Setting up the domain controller. Do this first; the settings below refer to it.

3. Configure the directory​

Choose, for the tenant (PUT /tenants/{tenantID}/directory/settings):

SettingWhat to enter
ConnectorThe Axis connector on the domain controller. Only connectors that can run Vertex jobs are offered (GET …/directory/connectors, supports_vertex).
Domain controller (optional)A specific domain controller's host name; empty uses the connector's own.
AD account and passwordThe account from step 2, as DOMAIN\name or name@domain. The password is stored encrypted and never shown again; leave it out of later changes to keep it.
Managed OUsThe distinguished names of the OUs Vertex may change, for example OU=Students,OU=School,DC=school,DC=local (up to 100). Everything below them is changeable; everything else is read-only.
Default user OUWhere new users go when no OU is given; one of the managed OUs or below one.
UPN suffixBuilds userPrincipalName (<logon name>@<suffix>) for new users without one, for example school.local.
User attributesExtra attributes a sync reads for every user (for example employeeType, extensionAttribute1), on top of the core set.
Sync intervalMinutes between syncs, 5 to 1,440 (default 30).
Write switchesUsers, groups, OUs, GPOs, password policies, deletes. Leave them off until the test and the first sync look right.

Saving needs a step-up: you confirm your password on the Hub (step_up_token). The change is in the audit log as directory.settings.update, without the password. A new connector, AD account or password starts a sync soon after.

4. Accept the local guard on the domain controller​

The connector refuses every change until a local administrator of the domain controller accepts the managed OUs. Accept them now, before Vertex sends any job: on the domain controller, open an elevated command prompt and run:

cd "C:\Program Files\RMM Connector"
rmm-connector vertex guard accept --ou "OU=Students,OU=School,DC=school,DC=local" --ou "OU=Staff,OU=School,DC=school,DC=local"
rmm-connector vertex guard set --gpo on --pso on --deletes on
  • Give one --ou per managed OU, exactly the list in Vertex's settings from step 3 (all of them, no others; case and spaces after commas do not matter). If the lists differ, changes are refused with guard_pending until you accept Vertex's list.
  • accept lists the OUs and asks you to type yes.
  • set switches on GPO changes, password policy changes and deletes, which are off in a new guard (users, groups and OUs are on). Leave off what Vertex should not do.
  • The default cap of 1,000 writes per minute fits a whole bulk import batch (up to 200 rows) and a membership change (up to 500 members added and 500 removed); you do not need to raise it.

If Vertex has already sent a change, the connector knows the managed OUs (the change was refused with guard_pending): vertex guard show lists them and vertex guard accept without --ou accepts them.

Details: The connector's local guard.

5. Test the connection​

Run the test (POST …/directory/test). It runs on the domain controller as the AD account and reports, in the settings' domain:

  • the domain (DNS and NetBIOS name, functional level), the domain controller that answered and the account the script ran as;
  • the PowerShell modules found (ActiveDirectory, GroupPolicy);
  • the password settings container;
  • which managed OUs exist (managed_ous_ok) and which do not (managed_ous_missing);
  • the UPN suffixes of the forest.

A failed test names the cause: logon_failed (wrong password), access_denied (often: the account is not in Remote Management Users), missing_module and the others in Troubleshooting.

6. Run the first sync​

Start a sync (POST …/directory/sync). It reads every user, group, OU, password policy and GPO of the domain into Vertex's mirror; a large domain takes a few minutes. Afterwards the lists and the overview (GET …/directory/overview) show the counts, and every object is marked as changeable (in_scope) or not, and protected or not.

Check that the objects you expect to manage are in_scope. If they are not, correct the managed OUs, and accept the corrected list on the domain controller (step 4).

7. Switch changes on​

Turn on the write switches you need in the settings (for example users and groups). Turn on deletes only if Vertex should delete objects. Each switch has a partner in the local guard (step 4).

8. Make the first change​

Make a first, harmless change, for example change the description of a test user. The operation goes from queued to running to succeeded, and the user in the mirror shows the new value. Follow an operation with GET …/operations/{operationID}?wait=20, which answers as soon as it finishes. If it fails with guard_pending, compare vertex guard show on the domain controller with the managed OUs in Vertex.

Next steps​