Users

Vertex shows every user of the domain from its mirror and changes the users below the managed OUs. Each change is an operation that the connector runs on the domain controller; the user in the mirror is updated when it succeeds.

The web interface is in development

This page describes what you can do; the API calls are given in brackets (Vertex API).

Finding users

The user list (GET /tenants/{tenantID}/users) can be filtered by:

• text (q): part of the name, logon name, UPN, display name or e-mail;
• OU (ou): only users below an OU, given by its DN;
• enabled or disabled (enabled=true|false);
• locked out (locked=true);
• member of a group (member_of, the group's DN; direct members).

Lists are paged (page, page_size up to 500). Each user shows its logon name, UPN, display name, e-mail, whether it is enabled and locked, its groups, its last logon and when it last changed, and two flags:

Flag	Meaning
in_scope	Below a managed OU: Vertex may change it.
protected	Privileged or built-in (adminCount=1, isCriticalSystemObject, a relative ID below 1000): Vertex never changes it.

One user

A user's detail (GET …/objects/{objectID}) has every attribute the mirror holds. A live read (POST …/objects/{objectID}/refresh) asks the domain controller for all of the user's attributes, plus the computed ones (msDS-ResultantPSO, msDS-User-Account-Control-Computed, msDS-UserPasswordExpiryTimeComputed), and the list of attributes the AD account may write on it (writable). Use it before editing an attribute the sync does not read.

Values are strings: numbers in decimal, dates as yyyy-MM-ddTHH:mm:ssZ, SIDs and GUIDs in their usual text form, booleans as TRUE/FALSE, and binary values as b64: followed by base64.

Creating a user

A new user (POST …/users, Tenant admin) takes:

Field	Default
Logon name (sam_account_name, required)	At most 20 characters, none of " / \ [ ] : ; | = , + * ? < > @.
OU	The default user OU of the settings. Must be a managed OU or below one.
Name (the CN, at most 64 characters)	"first name last name", else the logon name.
UPN	<logon name>@<UPN suffix> when a suffix is set.
First name, last name, display name	Display name: "first name last name".
Password	Without one the account is created disabled.
Enabled	Yes (only with a password).
Must change password at next logon	Yes.
Password never expires, user cannot change password	No.
Attributes	Any other attributes, as below.
Groups	Up to 100 group DNs to add the user to.

If setting the password fails (for example it does not meet the domain's password policy, password_policy), the half-created account is deleted again, so a failed create leaves nothing behind.

Changing attributes

Any attribute that is not on the deny list can be changed (PATCH …/objects/{objectID}), with four kinds of change in one request:

Change	Effect
set	Replaces all values of the attribute.
add	Adds values to a multi-valued attribute.
remove	Removes values from a multi-valued attribute.
clear	Removes every value.

{
  "set": { "department": ["10A"], "title": ["Student"], "thumbnailPhoto": ["b64:/9j/4AAQSkZJRg…"] },
  "add": { "otherTelephone": ["+359 2 123 4567"] },
  "clear": ["description"]
}

• Attribute names are LDAP display names (physicalDeliveryOfficeName, extensionAttribute1, …); case does not matter.
• Values are the attribute's string form; binary attributes take b64:<base64> (for example thumbnailPhoto, jpegPhoto).
• At most 1,000 values per attribute and 64 KiB per value.
• The schema (GET …/directory/schema?class=user) lists every attribute of users, groups and OUs: syntax, single- or multi-valued, system-only, constructed, range, and denied for the deny list. POST …/directory/schema/refresh reads it from the domain again.
• To have a sync read an attribute for every user, add it to the settings' user attributes.

The helpdesk may change only these contact attributes of users: givenName, sn, initials, displayName, description, mail, telephoneNumber, mobile, homePhone, ipPhone, facsimileTelephoneNumber, physicalDeliveryOfficeName, department, title, company, streetAddress, l, st, postalCode, co, c, wWWHomePage, info.

Attributes Vertex never changes

These are refused in every attribute change, in a new user's attributes and in bulk imports (denied_attribute, or invalid_column in a CSV), both by Vertex and again by the script on the domain controller:

objectGUID, objectSid, sIDHistory, objectClass, objectCategory, distinguishedName, cn, name, ou, nTSecurityDescriptor, adminCount, isCriticalSystemObject, primaryGroupID, userAccountControl, unicodePwd, userPassword, dBCSPwd, supplementalCredentials, pwdLastSet, lockoutTime, member, memberOf, servicePrincipalName, msDS-AllowedToDelegateTo, msDS-AllowedToActOnBehalfOfOtherIdentity, msDS-KeyCredentialLink, altSecurityIdentities, userCertificate, groupType, sAMAccountType, msDS-PSOAppliesTo, gPLink, gPOptions, msDS-SupportedEncryptionTypes, scriptPath, msDS-ResultantPSO, isDeleted, instanceType, whenCreated, whenChanged, uSNCreated, uSNChanged, objectVersion, systemFlags, unixUserPassword, msSFU30Password, ms-Mcs-AdmPwd, msLAPS-Password, msLAPS-EncryptedPassword, msDS-ManagedPassword, msDS-HostServiceAccount.

Passwords, unlocking, enabling, group membership, renaming and moving have their own operations below.

Passwords, unlocking, enabling

Action	What it does
Reset password (POST …/users/{objectID}/password)	Sets a new password (at most 256 characters). By default the user must change it at next logon (must_change) and the account is unlocked (unlock). A password the domain refuses fails with password_policy.
Unlock (POST …/users/{objectID}/unlock)	Unlocks a locked-out account.
Enable / disable (PUT …/users/{objectID}/enabled)	Enables or disables the account.

The new password goes to the connector once, encrypted at rest until then, and is never shown in the operation, the API or the audit log.

Moving, renaming, deleting

Action	Rules
Move (POST …/objects/{objectID}/move)	To a managed OU or below one.
Rename (POST …/objects/{objectID}/rename)	Changes the CN (at most 64 characters); the logon name and UPN stay.
Delete (DELETE …/objects/{objectID})	Needs the deletes switch (in the settings and in the connector's guard) and a step-up (X-Step-Up-Token). Accidental-deletion protection on the user is removed by Vertex before deleting. There is no undo in Vertex; restore from the AD Recycle Bin if it is enabled.

Group membership

POST …/users/{objectID}/groups adds the user to groups and removes it from others (add, remove: up to 100 group DNs each); each group is one operation. The group must be below a managed OU and not protected (so nobody can add users to Domain Admins through Vertex). The helpdesk may do this too.

From the group's side, see Groups and OUs.

Actions on many users

POST …/users/bulk-actions runs one action for up to 500 users:

Action	Operations
enable, disable, unlock	One per user.
move (with target_ou)	One per user.
add_to_group, remove_from_group (with group_dn)	One membership change for all users.
delete	One per user; Tenant admin and a step-up.

The answer lists the operations that were queued; users that were refused (for example protected ones) are left out.

Following an operation

Every action answers 202 with the operation. Follow it with GET …/operations/{operationID}?wait=20 (answers as soon as the operation finishes, or after 20 seconds) or the vertex.operation event of the live stream. POST …/operations/{operationID}/cancel cancels one that has not finished (best effort once it runs). The list of operations (GET …/operations) can be filtered by object, status, class and changes only.