Skip to main content

Directory sync

Directory sync has Waxell pull users and groups from your directory. It's the alternative to SCIM when your IdP can't push, and it's how Google Workspace users get roles and teams.

Open Identity → Directory → Connect directory.

Google Workspace​

  1. In Google Cloud (a project in your Workspace), enable the Admin SDK API and create an OAuth client ID (Web application) with this redirect URI: https://<workspace>.waxell.dev/api/v1/identity/directory/oauth/callback/
  2. In Waxell, choose Google Workspace, paste the client ID and secret, click Test discovery, then Authorize with Google Workspace, signed in as a Workspace admin.

Waxell asks only for read-only access: admin.directory.user.readonly and admin.directory.group.readonly.

Group membership includes nested groups: someone in eng-backend, which is a member of eng, counts as a member of eng.

Okta​

  1. Okta Admin Console → Security → API → Tokens → Create token. A token created by a read-only admin is enough.
  2. In Waxell, choose Okta, enter your org domain (for example acme.okta.com) and paste the token, then click Connect Okta.

Microsoft Entra​

  1. Entra → App registrations → New registration (for example "Waxell directory").
  2. API permissions → Add a permission → Microsoft Graph → Application permissions: User.Read.All and Group.Read.All. Then Grant admin consent.
  3. Certificates & secrets → New client secret. Copy the value.
  4. In Waxell, choose Microsoft Entra and paste this JSON, using your app's values:
{"client_id": "<Application (client) ID>", "client_secret": "<secret value>", "tenant": "<Directory (tenant) ID, or acme.onmicrosoft.com>"}
  1. Click Connect Microsoft Entra.

JumpCloud​

Choose JumpCloud and paste a read-only org API key (Settings → API in the JumpCloud admin console).

After connecting​

Click Sync on the connection to pull users and groups now.

Creating accounts​

Create org users from this directory controls what a sync does with people who aren't members yet:

ModeEffect
Off — link existing onlyMatches directory users to existing members; creates no one
On first sign-in (JIT)Creates their account when they first sign in
Full sync (mirror a group)Creates accounts for members of the groups in your group → role mappings

You can also set a default role and team for accounts it creates.

Removing people​

Turn on Offboard people removed from the directory on the connection. With it on, anyone who has disappeared from the directory since the last sync is offboarded by the next sync. It's off by default, so a newly connected directory never removes anyone until you choose to.

Device owners (MDM)​

Connecting Hexnode MDM stamps each enrolled device with its assigned person, so activity is attributed correctly. It never overrides an owner an admin set by hand.