Directory sync
Keep the people DarkStrata watches in step with the people who work for you
Overview
DarkStrata organises the people you care about into groups. When a stolen credential matches a member of a group, the finding is scored higher, and members of priority groups score highest. Keeping groups current means new starters are covered from day one and leavers stop taking up attention.
There are three ways to fill a group:
- Directory sync from Google Workspace or Microsoft Entra ID, refreshed every hour.
- CSV upload, from the dashboard or the API.
- The API, adding, updating and removing members one at a time or in batches.
You can mix them. Members you add by hand or by CSV stay in a synced group; the sync only manages the members it created.
- Google WorkspaceHourly, read-only
- Microsoft Entra IDHourly, read-only
- CSV uploadAdd or replace
- Groups APIFrom your own tooling
Your DarkStrata group
People matched on their email address
Staff findings prioritised
A stolen credential for a member scores higher. Priority groups score highest.
Directory sync
DarkStrata asks for read-only access and never writes to your directory. Connect once from Groups in the dashboard.
| Directory | Read-only access requested |
|---|---|
| Google Workspace | Read-only Admin SDK Directory access to groups, group members and users. Needs a Workspace administrator to approve. |
| Microsoft Entra ID | Microsoft Graph Group.Read.All, User.Read.All, Directory.Read.All and Organization.Read.All. Needs a tenant administrator to grant consent. |
Setting it up
Connect
An administrator approves read-only access in Google or Microsoft.
Choose
Link a group to one directory group, or to all users.
First sync
Members are imported as soon as the group is created.
Every hour
Joiners are added and leavers removed automatically.
What gets synced
- Direct user members are imported. Nested groups are not expanded.
- Each person is matched on their email address: the primary email in Google Workspace, and the mail attribute in Entra ID (falling back to the user principal name).
- Name, job title, department, office, manager and similar profile fields come across too, so findings carry context.
- The group's name and description follow the directory group's.
Running and pausing a sync
- Use Sync now on the group in the dashboard to refresh it straight away.
- Pause a group's sync at any time. Its members stay as they are until you resume it.
What one sync changes
Each sync compares the directory with the group, matching people on email address:
| Person | In directory | In group before | After the sync |
|---|---|---|---|
[email protected] | Yes | Yes | Kept, profile refreshed |
[email protected] | Yes | No | Added |
[email protected] | No | Yes | Removed |
[email protected] | No | Yes | Kept: added by CSV, so the sync leaves it alone |
A removed member's past findings stay on record; new findings for them are no longer prioritised.
If a sync fails because of a temporary error, it retries automatically with increasing gaps. If the directory connection needs re-approving, syncing stops until an administrator reconnects and runs a sync.
Directory sync is included on the Pro plan and above.
CSV upload
Upload a CSV to add members to a group, or to replace them all. A header row is required. The identifier column can be called identifier or email; every other column is optional.
| Column | Meaning |
|---|---|
identifier / email | The member's email address (or another identifier, if you set identifier_type). |
identifier_type | EMAIL (default), USERNAME, EMPLOYEE_ID, PHONE, HOSTNAME or CUSTOM. |
display_name | The member's name, as shown in the dashboard and on alerts. |
external_id | Your own reference for the member, such as an HR system ID. |
jobTitle, department, … | Profile fields, for example jobTitle, department, officeLocation, managerEmail. Header names are not case-sensitive. |
Example file:
email,display_name,department,jobTitle
[email protected],Jane Smith,Finance,Finance Director
[email protected],Sam Patel,Engineering,Platform EngineerUpload it through the API with PUT /groups/{id}/members, sending the file as text/csv or as a multipart file field:
curl -X PUT "https://api.darkstrata.io/v1/groups/<group_id>/members?mode=add" \
-H "X-Api-Key: your_api_key_here" \
-H "Content-Type: text/csv" \
--data-binary @staff.csvAdd or replace
mode=add(the default) adds new members and skips anyone already in the group.mode=replaceremoves every current member, including directory-synced ones, and then adds the file's members.
Up to 1,000 members per request and 10 MB per file. If any row is invalid, nothing is imported and the response lists the rows to fix.
Managing members through the API
With an API key you can manage groups and members from your own joiner and leaver process. Each request needs the matching permission on the key.
| Endpoint | Use |
|---|---|
GET /groupsgroups:read | List groups, filtered by sync source or status. |
PUT /groupsgroups:write | Create a group. |
PATCH /groups/{id}groups:write | Rename a group or pause its sync. |
PUT /groups/{id}/membersgroups:write | Add or replace members, as JSON or CSV. |
GET /groups/{id}/membersgroups:read | List a group's members. |
PATCH /groups/{id}/members/{member_id}groups:write | Update a member's details or status. |
DELETE /groups/{id}/members/{member_id}groups:delete | Remove a member. |
Connecting a directory and running an immediate sync are done from the dashboard, because they need an administrator to approve access in Google or Microsoft.
Sync events
Each directory sync sends a team.synced webhook when it finishes and team.sync_failed when it fails, so you can watch syncs from your own tooling. See webhook signatures for verifying deliveries.
Help
Questions about connecting your directory, or a sync that isn't behaving? Email [email protected].