14.5Resources and operations

The node offers nine resources. The tables below list every operation. The permission column names the permission the API key's role needs; Chapter 11, Users, roles and permissions, explains permissions.

User

Search by State accepts these states: Disabled, Enabled, Expired, Inactive, Locked Out, Password Expired, Password Must Change, Password Never Expires and Password Not Required. For Inactive, set Inactive Days to 15 or more: Active Directory updates the last-logon timestamp only about every 14 days, so a shorter period gives misleading results. Leave Base DN empty to search the whole domain.

For the operations that take several groups (Assign Groups, Unassign Groups), set Array Property to the name of the property in the input item that holds the array (default groups), and ID Key to the property inside each array element that holds the group's GUID (default id).

Note: The Reset Password operation shows a Must Change Password At Logon switch, but the gateway currently ignores it. To make the person choose a new password at their next sign-in, follow the reset with a User > Update that sets Account Policy > Change Password At Logon.

Group

Computer

Organizational Unit

The three account operations take an OU ID, Account Kinds (Users, Computers or All) and Scope (Only This OU, or Include Sub-OUs). The preview returns toChange, alreadyInState, excluded (each with a reasonCode and a reason) and exceedsLimit.

Some accounts are never changed with their unit: domain controller accounts, the Kerberos service account (krbtgt), the built-in Administrator, Guest and DefaultAccount, and system-critical objects. A disable also leaves out the account the connection signs in with and the gateway server's own computer account. The preview lists them under excluded.

Important: Enabling or disabling all the accounts in a unit waits for a person's approval unless the API key is set to Act without asking.

At most 100 accounts are changed in one run. A larger selection is refused as a whole with OrganizationUnitAccounts.TooMany; it is never split. Narrow the kinds or the scope, or run the preview first and check exceedsLimit.

A run is not transactional: if some accounts fail, the others still change. The node then emits one item whose top level carries success (true only when nothing failed), partialFailure, total, succeeded and failed, with the per-account outcomes under batch.items. Branch on {{ $json.partialFailure }}, or turn on Fail on Partial Failure to make the item fail instead. Accounts that changed before a failure stay changed either way.

Object

The Object resource works with any directory object, including types without their own resource such as contacts.

Move and Rename have an optional Expected Class (Computer, Group, Organizational Unit or User). When it is set, the gateway refuses the operation if the ID belongs to an object of another class, so a wrong ID cannot move or rename the wrong object. This is strongly recommended for moves, because a move changes the object's distinguished name. Renaming changes only the object's name in the directory tree; it does not change the logon name (sAMAccountName or userPrincipalName).

Saved searches are the shared saved LDAP filters described in Chapter 8, Saved LDAP filters. The drop-down lists the filters the API key can see, which needs savedfilters:list. For a filter that covers all object types, or one without a base DN, Run Saved Search automatically runs it on the server.

Security

Important: Apply a delegation to the narrowest container that covers the actual need. A password-reset delegation at the domain root reaches every account in the domain, including administrative ones. Writing an SPN makes the account a Kerberos service target.

Raw edits of individual access control entries, the owner and inheritance are deliberately not offered in the node. They are available only through the REST API (see Chapter 15).

Service Account

Additional Fields on Create are Description, DNS Host Name, Managed Password Interval (Days), Path, SAM Account Name and Service Principal Names. For a group managed account, the Managed Password Interval (Days) defaults to 30 and cannot be changed afterwards: Active Directory fixes it at creation. If Path is empty, the account is created in the domain's Managed Service Accounts container. SAM Account Name defaults to the name, with a trailing $ added. A group managed account needs a DNS Host Name to be usable. Service principal names are entered as a comma-separated list.

Directory Context

These operations only read. They return information about the directory the binding points to, and need ad:directory:read.

Operation

The Operation resource works with operations the gateway has queued for approval. It is how a workflow follows up a change that is waiting for a person.

All three need operations:waiting:list, and they only ever show operations made with the same API key's owner — never anybody else's.