Skip to main content

Auth Hooks and directory sync

Auth Hooks and directory sync are advanced controls. Use them after the basic sign-in path works and after the organization model is clear.

Switera Auth Hooks page with add hook action
Auth Hooks let your backend participate in selected Auth decisions.
Switera Directory Sync page for enterprise lifecycle setup
Directory sync keeps enterprise people, groups, and memberships aligned over time.

When to use Auth Hooks​

Use Auth Hooks when Switera needs to call your backend during sensitive flows, such as:

  • checking whether a sign-up should be allowed
  • adding custom claims
  • enforcing tenant-specific rules
  • blocking access when an external account state is not valid
  • enriching a session with product-specific data

Do not use a hook for work that can happen asynchronously through webhooks. Hooks should be fast and reliable because they affect the user-facing Auth flow.

Configure an Auth Hook​

  1. Open Authentication > Auth Hooks.
  2. Select Add Hook.
  3. Choose the flow the hook should run on.
  4. Enter the HTTPS endpoint.
  5. Configure the signing or verification method if required.
  6. Save.
  7. Test with a non-production user.
  8. Confirm failure behavior is acceptable.

Hook design guidelines​

  • Keep responses fast.
  • Return clear allow or deny decisions.
  • Make the endpoint highly available.
  • Log the hook decision in your backend.
  • Do not return private implementation details in user-facing errors.
  • Prefer webhooks for post-event processing.

When to use directory sync​

Use directory sync when an enterprise customer expects their identity provider to manage users, groups, and memberships.

Common reasons:

  • automatic user provisioning
  • automatic deprovisioning
  • group-to-role mapping
  • organization membership alignment
  • enterprise audit expectations

Directory sync rollout​

  1. Configure SSO first.
  2. Confirm the organization and domain mapping.
  3. Connect the directory provider.
  4. Map user identifiers and groups.
  5. Run a small test sync.
  6. Review created, updated, and deprovisioned users.
  7. Enable regular sync after the mapping is correct.

Safety checklist​

  • SSO works before sync is enabled.
  • Test users are used before real customer data.
  • Group mapping is reviewed by the customer owner.
  • Deprovision behavior is agreed.
  • Support knows where to inspect sync state.

Related pages: