Directory Provisioning Setup

This page walks through connecting a directory to a Hawzu workspace over SCIM 2.0. For what provisioning does once it is connected, see Security & Access.

Directory provisioning is available on Enterprise only. Single sign-on is available on every plan.

Single sign-on and provisioning are independent: you can run either without the other. Together they are the usual arrangement — the directory decides who is in the workspace, and single sign-on decides who someone is at the door.

---

Before you start

1. Confirm the workspace is on Enterprise. The SCIM card shows an upgrade prompt otherwise, and token creation is refused.

2. Verify your company’s email domain in Settings → Security & Access. A directory can only create, change or deactivate addresses on a domain this workspace has verified — everybody else is invisible to it.

3. Decide which role people receive when the directory creates them. It is chosen per token and cannot be the owner, a workspace manager, or a project role.

4. Check your identity provider can reach your Hawzu deployment over HTTPS. A directory calls Hawzu directly rather than through anyone’s browser, so a local or private-network install cannot be provisioned.

You need the workspace manager or owner role for everything below.

---

Create the token in Hawzu

1. Open Settings → Security & Access and expand Directory provisioning (SCIM).

2. Copy the SCIM base URL. It ends in /api/v1/scim/v2 and is what your provider calls the tenant URL or connector base URL.

3. Enter a Token name — name it after the directory that will use it, such as “Okta production” — and choose the Role for new people.

4. Choose Create token and copy the token. It is shown once, so copy it now. A lost token can’t be shown again; create a new one instead.

The token is the whole credential

A SCIM token can add and remove people in this workspace. It is not a member and holds no seat, and it reaches nothing but the SCIM endpoints — but treat it like any other administrative secret, and revoke it the moment a directory no longer needs it.

---

Okta

Okta needs SCIM turned on for the application before a Provisioning tab appears.

1. In the Okta Admin Console, open the app integration for Hawzu — the one you created for single sign-on, or a new one if you are provisioning without it.

2. On General, under App Settings, set Provisioning to SCIM and save.

3. Open the Provisioning tab, choose Integration → Edit, and fill in:

   • SCIM connector base URL — the SCIM base URL you copied from Hawzu.
   • Unique identifier field for users — userName.
   • Supported provisioning actions — push new users and push profile updates.
   • Authentication Mode — HTTP Header, with the Hawzu token as the bearer token.

4. Choose Test Connector Configuration, then save.

5. Choose To App → Edit and enable Create Users, Update User Attributes and Deactivate Users.

6. Assign the people or groups who should be in this workspace. Okta creates them in Hawzu as they are assigned.

Okta must send each person’s email address as userName. If your Okta usernames are not email addresses, map the primary email to userName in the app’s profile mappings — Hawzu identifies an account by its address, and refuses a userName that is not one.

---

Microsoft Entra ID

1. In the Entra admin center, open Enterprise applications and select the Hawzu application.

2. Open Provisioning, set the mode to Automatic, and fill in Admin Credentials: the SCIM base URL as Tenant URL, and the Hawzu token as Secret Token.

3. Choose Test Connection, then save.

4. Under Mappings, open Provision Microsoft Entra ID Users and remove attributes Hawzu does not store — it keeps the user name, the display name and whether the person is active. Leaving extra attributes mapped is harmless, but they are ignored.

5. Turn off group provisioning. Hawzu provisions people, not groups, and a group mapping left on reports failures for work that was never going to happen.

6. Set the Scope to the users assigned to the application, then start provisioning.

Entra deactivates a person before deleting them, usually about thirty days later. Both mean the same thing in Hawzu, so nothing happens twice.

---

What Hawzu supports

The service advertises its own capabilities at /ServiceProviderConfig, and the attributes it stores at /Schemas. In short:

Resources	Users only. There is no Groups endpoint.
Operations	GET, POST, PUT, PATCH, DELETE on users
Filtering	userName eq "someone@example.com", which is what provisioning sends. Any other filter answers an empty page rather than an error.
Paging	startIndex (1-based) and count, up to 200 per page
Not supported	groups, bulk operations, sorting, ETags, password changes
Attributes kept	userName, name, active, externalId

A password sent with a new user is ignored. People sign in with single sign-on or a Hawzu password they set themselves; a directory never sets one.

Only members on your verified domains are visible over SCIM. A guest on another domain is not listed, cannot be fetched by id, and is unaffected by anything the directory does.

---

What each change does in Hawzu

Create. Adds the person to the workspace with the token’s role and takes a seat. If they already have a Hawzu account, that account is used.

Update name. Changes the person’s name.

Change userName. Refused. A Hawzu account is identified by its email address; create the new address and deactivate the old one.

Deactivate, or delete. Removes the person’s workspace access — project access, group membership, pending invitations and connected AI clients. It is the same act either way. Signing in again does not undo it.

Reactivate. Adds them back with the token’s role. Project access is not restored; add them to projects again.

The workspace owner cannot be deactivated by a directory. Change the owner in Hawzu first.

Every one of these writes an audit entry, so a roster change is reviewable alongside everything else in Settings → Security & Access → Audit logs.

---

Troubleshooting

Test connection fails with 401. The token is wrong, was revoked, or is not being sent as Bearer <token>. Create a new token and paste it again.

Test connection fails with 403. The workspace is not on Enterprise, or the plan changed after the token was created.

”… is not on a domain this workspace has verified.” The directory is pushing an address Hawzu will not accept. Verify that domain, or narrow the assignment scope to people on a domain you have verified.

”… is already a member of this workspace.” Somebody invited them by hand before provisioning started. The directory adopts existing members on its next update rather than creating them twice.

A seat limit message. Enterprise has no seat caps; this means the workspace is on another plan and the token predates that change.

“userName cannot be changed.” Somebody renamed the account in the directory. Create the new address there and deactivate the old one.

Nothing arrives at all. Confirm the provider can reach your Hawzu deployment over HTTPS from the public internet, and that people are assigned to the application.

---

Next Steps

• Security & Access — verified domains, enforcement and the rest of the security section
• Single Sign-On Setup — connect the same provider for sign-in
• Roles Overview — what the role for new people can do