Active Directory
Connect Insperity to Active Directory
Turn Insperity hires, changes and departures into account updates in Active Directory. Follow the setup steps, preview changes with a dry run, then go live.
Insperity record
08:02:14
Grace Oyelaran
9024
- Job title
- Software Engineer
- Department
- Engineering
- Work location
- Austin
- Supervisor
- D. Okafor
- Hire date
- Nov 10, 2026
- Employment status
- Active
Active Directory
eng-austin
- accountOU=Engineering,OU=Staff
- sAMAccountNamegrace.oyelaran
- mailgrace.oyelaran@northwind.com
- titleSoftware Engineer
- managerD. Okafor
- memberOfEng-All
- memberOfVPN-Austin
2.3s
- Insperity fields mapped
- 12
- Steps to go live
- 9
- Employee records stored in our cloud
- 0
Joiners, movers and leavers
How Insperity updates Active Directory
HR updates Insperity. ezOnboard updates accounts based on your rules.
Joiner
An account before day one
A new hire is entered in Insperity Premier with a hire date.
- Account created in the role’s OU, disabled until the start date
- Name, email and attributes set from Insperity
- Department and site groups added
- Account enabled on the start date; password change required at first sign-in
Mover
Access for the new role
A job title, department, work location or supervisor changes in Insperity Premier.
- Title, department, office and manager updated
- Account moved to the OU your rules specify
- Groups added and removed to match the new role
Leaver
Offboarding on schedule
A termination date is set in Insperity Premier.
- Account disabled on the termination date, never deleted
- Groups removed and the account moved to the disabled OU
- Mail forwarded and licenses recovered with connected Exchange and Microsoft 365 services
Before you start
What to have ready
Work with a Insperity admin and a directory admin to complete the setup.
- In Insperity
- Insperity Premier administrator access, and an officer who can sign Insperity’s API Terms of Use
- A work email or employee ID for each person in Insperity Premier to match them to their account
- In Active Directory
- A domain-joined server running Windows Server 2019 or later
- A group managed service account or service account to run the agent
- Outbound HTTPS to the HR system and ezOnboard; no inbound access required
- OUs for staff accounts, disabled accounts and the groups ezOnboard will manage
Step by step
Set up Insperity with Active Directory
Start in Insperity and on your server. Then finish in the ezOnboard portal with our implementation team.
01
Insperity
Request API access from Insperity
Insperity service team → integrationspecialists@insperity.com
Request API access from Insperity’s integration specialists. Each key is limited to the endpoints and IP addresses in your request.
Have an authorized officer sign Insperity’s API Terms of Use. Email the signed form to integrationspecialists@insperity.com. Request an API key for ezOnboard and include the endpoints below and your agent network’s public IP address. Request read access only.
- employeescompany: first name, last name and employee ID
- employeesposition: job title, department, work location and supervisor
- employeescommunication: work email
- employeesemployment: hire date, employment status and termination date
- departments: department names
API access request. Attach the signed Terms of Use and list the endpoints and your IP address.
02
Insperity
Save the Company ID and API key
Insperity Premier → Employee Directory
Find your Company ID beside the company name in Insperity Premier’s Employee Directory. Note each company ID ezOnboard should read.
Insperity sends the API key after approving your request and IP address. Store it securely. It can access only the endpoints you requested. You’ll need the Company ID and key in step 5.
Employee Directory. The Company ID is beside the company name.
03
Your server
Install the ezOnboard agent
The agent runs as a Windows service on a domain-joined server with Windows Server 2019 or later. It connects to Insperity and ezOnboard over outbound HTTPS. No inbound firewall rules are needed.
Download the signed MSI and enrollment bundle from the portal. Save the install code. The portal shows it only once. Run the MSI, enter the code and choose a service account, preferably a group managed service account. The installer checks the domain connection, LDAP access, outbound access and clock before making changes.
Installer screen with the setup requirements.
04
Active Directory
Delegate the OUs the agent will manage
Run the installer’s delegation script once as a domain administrator. It lets the agent’s service account create, update and disable accounts only in the OUs you choose. The agent doesn’t need Domain Admin rights.
Include the OUs for staff accounts, disabled accounts and managed groups. The agent blocks changes outside these OUs, even if a rule requests them.
PS C:\> & 'C:\ProgramData\ezOnboard\northwind\ou-delegation.ps1' Delegated NORTHWIND\svc-ezonboard$ on OU=Staff,DC=northwind,DC=com Delegated NORTHWIND\svc-ezonboard$ on OU=Disabled,DC=northwind,DC=com Delegated NORTHWIND\svc-ezonboard$ on OU=Groups,DC=northwind,DC=com DoneRun the installer’s delegation script once on a domain controller.
05
ezOnboard portal
Add Insperity as an HR source
In the portal, add Insperity as an HR source using the Company ID and API key. Your credentials are encrypted with your organization’s key and sent to your agent. The agent reads Insperity from your network. Nobody at ezOnboard can read the credentials.
Choose a field to match people across both systems, usually work email or employee ID. The agent checks Insperity every five minutes and catches up on any missed changes.
HR source. Your agent uses these credentials to read Insperity.
06
ezOnboard portal
Map Insperity fields to Active Directory attributes
Choose which Insperity fields update each directory attribute. Start with the defaults below, add custom fields or combine values. For example, build a display name from first and last names, format a job title or look up an office address by site.
Blank Insperity fields leave directory values unchanged unless you configure the mapping to clear them.
Field mapping. See the full list of defaults below.
07
ezOnboard portal
Set rules for accounts, OUs and groups
Rules define who gets an account, which OU it belongs in, how it’s named and which groups it joins. They also control offboarding. Use Insperity fields, such as department and site, to make those choices.
Our implementation team helps you write the rules. With approvals enabled, your team must approve each rule change before the agent uses it.
Rules page with the placement rule open.
08
ezOnboard portal
Preview changes with a dry run
Run a dry run for your whole workforce. The agent matches Insperity records to existing accounts by employee ID, then work email, and previews changes without applying them. If two accounts match one person, that action stops for review.
Review the planned changes and the rules behind them in the portal. Adjust your rules and repeat the dry run until the results match your expectations.
Dry run. No changes are applied while dry run is on.
09
ezOnboard portal
Go live
Turn off dry run to apply changes. If a run would disable or move more accounts than your safety limits allow, it stops and alerts your team before making changes. We review the first runs with you.
HR continues working in Insperity. Your rules handle new accounts, updates and offboarding on schedule. Get alerts by email, in the portal or by webhook when a run stops, the HR feed stops updating or the agent stops reporting. An inactive feed never triggers offboarding.
Reports with account activity, tickets avoided and agent uptime.
Field mapping
Insperity fields and Active Directory attributes
Start with these defaults and adjust any mapping. Dates and lifecycle status control when accounts are created, enabled or disabled.
| Insperity field | Active Directory attribute | How it’s used |
|---|---|---|
| First nameEmployee | givenName | Sets the first name at account creation and keeps it up to date. |
| Last nameEmployee | sn | Keeps the last name up to date. Also updates the logon name if your naming rule uses it. |
| Preferred nameEmployee | displayName | Uses the preferred name for the display name and email. Uses the first name if blank. |
| Work emailCommunication | mail, userPrincipalName | Sets the email address and sign-in name. A mail rule can also generate them from the person’s name. |
| Employee IDEmployee | employeeID | Added to new accounts and used first to match existing accounts. |
| Job titlePosition | title | Keeps the job title up to date and sets groups based on your rules. |
| DepartmentPosition | department | Keeps the department up to date. Rules can use it to choose account placement and groups. |
| Work locationPosition | physicalDeliveryOfficeName | Keeps the office up to date. A lookup table can also fill in the street, city and country. |
| SupervisorPosition | manager | Links to the supervisor’s account to keep approvals and org charts in sync with Insperity. |
| Hire dateEmployment | userAccountControl | Sets when the account is created and enabled. You choose how many days before the hire date to create it. |
| Employment statusEmployment | userAccountControl | Active keeps the account enabled. Terminated disables it when no other record keeps the person active. |
| Termination dateEmployment | userAccountControl | Sets the date for disabling the account and starting offboarding. Your rules set the time. |
Frequently asked questions
- Does ezOnboard write to Insperity Premier?
- No. ezOnboard only reads Insperity’s API, so request the read-only employee endpoints and nothing else. Make any corrections in Insperity Premier or through your Insperity service team.
- Which Insperity endpoints does the API key need?
- Request employeescompany, employeesposition, employeescommunication, employeesemployment and departments. No compensation or payroll access is needed. The key works only with the endpoints and IP addresses in your request.
- Do we need Insperity’s Entra ID integration or SCIM?
- No. ezOnboard reads Insperity’s API and uses your rules to manage accounts in Active Directory or Entra ID. Its agent runs on your network and can also manage Exchange.
- Do we need a server for the agent?
- Yes. Use a domain-joined Windows Server with LDAP access to a domain controller and outbound HTTPS to Insperity and ezOnboard. The agent needs no inbound firewall rules or Domain Admin rights. The delegation script grants access only to the OUs it manages.
- How quickly does a Insperity change reach Active Directory?
- The agent checks Insperity every five minutes and usually applies changes within seconds of finding them. Scheduled changes follow your rules: accounts are created before the start date, enabled on that date and disabled on the termination date at the time you choose.
- How does Insperity trigger offboarding in Active Directory?
- On the termination date, the account is disabled, removed from its groups and moved to your disabled-accounts OU. It is never deleted. With Exchange and Microsoft 365 connected, your rules also schedule mail forwarding and license recovery. Every step is recorded for audit.
- Where does our employee data go?
- The agent reads Insperity and updates Active Directory from your server. Names, emails and HR records stay on your network, where your team can view them on a local status page. The portal receives events with pseudonymous IDs, the rule used and the result.
- Can ezOnboard also connect Insperity to Entra ID?
- Yes. One agent and one set of rules can manage Active Directory, Entra ID and Exchange from Insperity. For accounts synced from Active Directory, the agent updates the on-premises account and assigns licenses and mailboxes in the cloud.
Get a demo
See Insperity connected to Active Directory
Get a demo for your Insperity and Active Directory setup. For questions, email sales@ezonboard.io.