Coming soon. The Wiki is in active development, so features and these docs may still change. Early adopters: contact us for access.

Users & Directories

Where user accounts come from, how people sign in, and how accounts are protected

1. Overview

Every user account belongs to a directory: the place the account comes from and that decides how the person signs in. Every installation starts with one directory, Local, created by the setup wizard; the first administrator is in it.

DirectoryAccountsSign-inLicense
LocalCreated and edited in the WikiEmail and passwordStandard or higher
DelegatedCreated and edited in the Wiki (or on first sign-in), without passwordsSingle sign-on through your identity providerStandard or higher
LDAPRead from an LDAP server (OpenLDAP, 389 Directory Server, FreeIPA…) on a schedule; not editable hereDirectory password (LDAP bind), or single sign-onPro or higher
Active DirectoryRead from Microsoft Active Directory on a schedule; not editable hereDirectory password (LDAP bind), or single sign-onPro or higher
SCIMPushed by your identity provider (Okta, Microsoft Entra ID, OneLogin, JumpCloud…) as people join, change and leave; not editable hereSingle sign-onEnterprise
Microsoft Entra IDRead from Microsoft Entra ID (Azure AD) through Microsoft Graph on a schedule; not editable hereSingle sign-onEnterprise
Google WorkspaceRead from Google Workspace through the Admin SDK on a schedule; not editable hereSingle sign-onEnterprise

Which one? If your identity provider supports SCIM provisioning (Okta, Entra ID and most others do), a SCIM directory updates the Wiki within seconds of a change. Pick Microsoft Entra ID or Google Workspace when you'd rather have the Wiki read the directory on a schedule, or LDAP/Active Directory for on-premises directories.

2. Directory order

Directories are kept in order, highest first. When the same person has an account in more than one directory, matched by email or username regardless of upper and lower case, only the account in the highest directory is used. The others are *shadowed*: they can't sign in, don't use a license seat, and show a Shadowed badge on the Users screen.

Settings → Directories: where accounts come from, in order
Settings → Directories: where accounts come from, in order
  • If the account in the highest directory is disabled or locked, the person can't sign in. The Wiki does not try the next directory.
  • A disabled directory is skipped entirely, so accounts in the next directory take over.
  • Changing the order can switch which account (and so which role) a person signs in with. Their current sessions continue until they sign in again.

3. Managing directories

Settings → Directories lists every directory in order with its type, how many of its users are active, when a synced directory last synced, and its status: On, Off, or for a synced directory whose last sync didn't go through, Blocked or Failing with the reason underneath. Your account marks the directory your own account is in. Anyone with the directories:read permission can view it; changing it needs directories:write (super admins).

Select a directory's name to open its page: its status and on/off switch at the top, then its settings one row each (name, connection, sign-in, schedule) and, for a synced directory, its sync controls and History. Changes wait in a bar at the bottom of the page until you select Save (or Discard).

TaskHow
Change the orderUse the up and down arrows next to a directory in the list. The new order applies to the next sign-in.
RenameOn the directory's page, change Name and select Save.
Turn offOn the directory's page, switch it off and confirm. Users in the directory are signed out on their next request and can't sign in until you turn it on again. The directory that holds your own account can't be turned off by you.
Turn onSwitch it on; it applies at once.
See its accountsFor Local and Delegated directories, Open its accounts shows Settings → Users filtered to that directory.
DeleteDelete… at the bottom of the directory's page, for an empty directory other than Local.

To keep your organization from being locked out, the Wiki refuses to:

  • disable the last enabled directory;
  • disable the directory your own account is in;
  • disable a directory if no active super admin could sign in afterwards.

4. Setting up the Local directory

There is nothing to configure: the setup wizard creates the Local directory and your first administrator in it. People in the Local directory sign in with their email address, which is their username. Email addresses are unique within a directory regardless of case: Ann@example.com and ann@example.com are the same account.

5. Managing users

Settings → Users lists everyone in your organization: profile picture, name, email, directory, role, status and last sign-in. Search by email, name or username, and filter by directory or status (Active, Disabled, Locked, Invited, Anonymized). Select a user to see their details, account status and sign-in history. Seeing users needs users:read and profiles:view (see Profile pictures and finding people). Other people's sign-in details need users:security as well, which organization admins hold: without it the list has no last sign-in column or Locked filter, and a user's page shows their profile and groups only. Everyone sees their own.

Settings → Users: everyone who can sign in, their directory, role, status and last sign-in
Settings → Users: everyone who can sign in, their directory, role, status and last sign-in
BadgeMeaning
ActiveCan sign in
DisabledCan't sign in. The details page says why: disabled by an administrator, disabled or removed in the user's directory, or over the license's user limit
LockedToo many wrong passwords; locked until the time shown, or until an administrator unlocks it
ShadowedThe same person has an account in a higher directory; this one can't sign in
Directory offThe user's directory is disabled

6. Creating a user

  1. Open Settings → Users — Select New user.
  2. Enter the details — Email (the person signs in with it), name and a password. Passwords must be at least 12 characters and can't contain the email address; long passphrases are best.
  3. Choose a role — Member, Organization admin or Super admin. You can only grant a role up to your own.
  4. Decide about the password — Leave Ask for a new password at first sign-in on when you'll share a temporary password. The person then has to choose their own before they can do anything else.
  5. Create — Share the email and password with the person through a secure channel.

New users go into the Local directory. Creating a user needs the users:write permission and a free license seat; seats count active users who aren't shadowed.

7. A user's page

Select a user in Settings → Users to open their page. The header shows their name, email, username, status, role and directory. Below it, a banner explains any state that keeps them from signing in normally (locked, disabled, invitation not accepted, shadowed, must choose a new password), with the fix beside it: Unlock, Enable or Resend invitation.

A user's page: profile, sign-in and security, and groups
A user's page: profile, sign-in and security, and groups
  • Overview: their profile and groups, and a Sign-in & security card with their last sign-in, failed attempts, password state and latest sign-ins (users:security, or your own page).
  • Sign-in history: every sign-in, newest first, with the address and browser. Filter it to Signed in or Refused; refused ones say why. Shown with users:security, or on your own page.
  • Privacy: download their personal data or anonymize them (see below). Shown to people with users:export or users:anonymize.

8. Actions on a user

Reset password and Change role are buttons in the page header; Sign out everywhere, Disable user and Enable user are in the ⋯ menu next to them.

ActionWhat it doesPermission
EditChange the email or name. Only for Local users (and later Delegated ones): details of users from an external directory are changed thereusers:write
DisableSigns the user out on every device and stops them signing in. You can't disable yourself or the last super admin who can sign inusers:delete
EnableLets a disabled user sign in again (needs a free license seat). Users disabled by their external directory are enabled thereusers:delete
UnlockClears a lockout after failed sign-ins right awayusers:write
Reset passwordSets a new password for a Local user and signs them out everywhere. Optionally asks them for a new one at next sign-inusers:write
Change roleMember, Organization admin or Super admin. Not your own role, and not above your ownroles:write
Sign out everywhereEnds every session on every device; the user can sign in againusers:write

Organization admins can't act on super admins. Every action is recorded in the audit log.

9. Profile pictures and finding people

Wherever the Wiki lists people, it shows each person's profile picture, or their initials when they haven't chosen one: Settings → Users and a user's page, a group's members and Add members, a space's members and the search for people to add, and the audit log. People choose their picture under Profile (a built-in picture or an upload of up to 2 MB).

Looking people up needs the profiles:view permission. Every signed-in role holds it by default; super admins hold every permission. It covers:

  • Searching people: the Settings → Users list and the people pickers of groups and spaces.
  • Opening a user's page.
  • Seeing who is in a group or a space. Every space role, Viewer included, also gives it for that space, so a space's members always see each other. Someone who can only read a space (an internal or public one) without a role there sees that it has members, not who they are.
  • Seeing other people's profile pictures, only those of people in your organization (super admins: every organization). Your own picture never needs it.

Someone without profiles:view sees initials instead of other people's pictures, no search box for adding people, and a note instead of member lists they may not see. An API token that lists or opens users, or lists members, needs profiles:view among its permissions, even where a space role gives it to its owner; tokens created before it existed must be re-created with it.

10. Groups

Settings → Groups lists your organization's groups with their member counts and where they come from. A group's page shows its members, how each one got there (Added by hand, or From a directory) and the directories that sync into it. Viewing needs groups:read, and seeing its members also profiles:view; creating, editing, deleting and managing members needs groups:write.

A group: its directories and members
A group: its directories and members

11. Creating a group

  1. Open Settings → Groups — Select New group.
  2. Name it — Enter a name and, optionally, a description. Names are unique in your organization regardless of upper and lower case: Engineering and engineering are the same group.
  3. Add members — On the group's page select Add members, search for people from any directory, tick them and select Add.

How groups and directories fit together:

  • One group per name. When a directory that syncs or provisions groups (LDAP, Active Directory, SCIM, Entra ID, Google Workspace) has a group whose name matches an existing group, its members are added to that group instead of creating a second one. Every such merge is recorded in the audit log.
  • Manual members are never touched by sync. People you add by hand stay until you remove them, even if they're also in the group through a directory.
  • Directory members are managed in the directory. When someone leaves the group in the directory, or leaves the directory, the next sync removes that membership. You can't remove them here; the Remove button appears only for members added by hand.
  • Groups are never deleted automatically. If a group disappears from a directory, the members that directory added are removed and the group is marked as removed from that directory; the group and its manual members stay.
  • A group that a directory still syncs into can't be deleted here. Renaming it is fine: the directory keeps finding it by its ID.

Groups don't change anyone's system role (Member, Organization admin, Super admin). They carry space roles: give a group a role on a space's Members page, and everyone in it gets that access. See How access fits together.

12. Privacy requests (GDPR)

On a user's page, the Privacy tab downloads everything the Wiki stores about a person, or anonymizes them for good. Both need permissions super admins hold (users:export, users:anonymize). What each one covers, and what the Wiki's pages, Q&A, calendar and analytics do with it, is in Personal data.

13. Forgotten passwords

When email is set up, the sign-in page shows Forgot password?. Local users enter their email address and get a link to choose a new password. The link works once and expires after 30 minutes (AUTH_PASSWORD_RESET_TTL); choosing a new password signs them out everywhere and unlocks a locked account.

  • The page always gives the same answer, whether or not the address belongs to an account, so it can't be used to find out who has one.
  • Only active Local accounts get a link. Disabled users, invited users, and users from Delegated, LDAP or Active Directory directories (who reset their password in their own directory) get nothing.
  • At most 3 links per account per hour and 10 per network address per 15 minutes are sent; further requests are silently ignored.
  • A new link makes older ones stop working.

14. Inviting users

With email set up, New user offers Email an invitation instead of setting a password for the Local directory. The person gets a link to choose their own password; until then they show as Invited and can't sign in. The link expires after 7 days (AUTH_INVITATION_TTL); Resend invitation on their page sends a new one and stops the old link. Accepting needs a free license seat. Enable never accepts an invitation for someone: an invited person you disabled and enabled again is Invited again and their link works again; they become active only by choosing a password.

15. Your password

Open the profile menu, choose Edit Profile → Security, enter your current password and the new one twice, then Change password. Your other devices are signed out; this one stays signed in. Users from directories that sign in another way (for example single sign-on) don't have a password here.

If an administrator set a temporary password for you, you'll see Set a new password right after signing in. Choose your own to continue. Your API tokens are refused until you have.

16. Setting up a Delegated directory

A Delegated directory holds people whose passwords live somewhere else: they sign in through your identity provider with single sign-on. You manage their accounts here: name, email, role, groups, enabled or disabled. Typical uses: contractors or partners from another company's identity provider, or staff who should only ever use single sign-on. Accounts can also be created automatically the first time someone signs in (see Single sign-on → Accounts).

After adding the directory, add an identity provider for it under Settings → Single sign-on (Enterprise). Without one, its people can't sign in.

Before you start: you need the directories:write permission (super admins) to add the directory, and users:write to add people. Each active, non-shadowed Delegated user uses a license seat.

  1. Open Settings → Directories — Select Add directory: a page lists the types, grouped by where the accounts come from.
  2. Choose the type — Pick Delegated under Made in the Wiki.
  3. Name it — Use a name people will recognize in the Users list and filters, for example Partners or Contoso SSO. You can rename it later.
  4. Add it — Select Add directory in the bar at the bottom. The new directory is added last in the order, is on, and its page opens.
  5. Decide its place in the order — If the same people also have Local accounts, the higher directory wins at sign-in. Leave Delegated below Local while people still sign in with passwords; move it above Local (up arrow) when you want those people to use single sign-on instead. The Users screen marks the losing accounts as Shadowed.
  6. Add people — Open Settings → Users, select New user, choose the Delegated directory under Directory, and enter email, name and role. There is no password field. The email must match the email your identity provider will send for that person.
  7. Put them in groups — Add them to groups from the group's page or check their groups on their user page, as for any other user.

Fields

FieldWhat to enter
TypeDelegated
NameUp to 200 characters; shown in the Users list, filters and user pages

What you can do with Delegated users: edit their email and name, change their role, disable and enable them, sign them out everywhere, add them to groups, and see their sign-in history. Reset password isn't offered: they have no password here.

Removing a Delegated directory: only a directory with no users in it can be deleted (for example one you added by mistake), and the Local directory can never be deleted. Users can't be deleted, so for a directory you no longer need, Disable it: its users can't sign in and nothing is lost.

Troubleshooting

SymptomCause and fix
A Delegated user can't sign in with a passwordExpected: Delegated users have no password here. They use the Sign in with … button of the directory's identity provider.
The user shows ShadowedAn account with the same email or username exists in a higher directory, and that one is used at sign-in. Move the directories into the order you want, or remove the other account.
"A user with that email already exists in this directory"Emails are unique within a directory regardless of case. Find the existing account with the search box.
"Your license allows N active users"Every active, non-shadowed user uses a seat. Disable someone or upgrade the license.
Delete says the directory isn't emptyDirectories with users can't be deleted. Disable the directory instead.

17. How directory sync works

LDAP, Active Directory, Microsoft Entra ID and Google Workspace directories are read, never written: The Wiki copies users and groups from the directory on a schedule. Each sync reads every user and group the filters match (a full sync) and then:

In the directoryIn the Wiki
New userAn account is created in this directory (disabled if the license has no free seat)
User's email, name or username changedUpdated here. Details of directory users can't be edited in the Wiki
User disabled (Active Directory)Disabled here and signed out everywhere
User enabled again, or back in the directoryEnabled again here, unless an administrator disabled them in the Wiki
User deleted or no longer matches the filterDisabled here (Removed from the directory) and signed out; never deleted. Their memberships from this directory are removed
User re-created with a new ID but the same emailLinked to the existing account
GroupLinked to the Wiki group with the same name (any case), or created. Only this directory's members of that group are changed; members added by hand or by other directories stay
Group deletedThe members this directory added are removed; the group itself stays

People are matched between syncs by the directory's immutable ID (entryUUID, or objectGUID in Active Directory), so renaming or moving someone in the directory keeps their Wiki account, roles and history.

Safety checks. A sync changes nothing and is marked Blocked when:

  • the directory returns no users while some are active here (typically a wrong base DN or filter), or
  • it would disable more than the deprovisioning limit (10% of active users by default, once there are at least 5). An expired service account or a wrong filter otherwise looks like everyone leaving.

Check the settings, then use Run anyway… in the banner at the top of the directory's page if the change is real (for example a department really left). That lets one sync go past the limit.

Skipped items. Users without an ID or email address, with an invalid email, or with the same email or username as another user in the same directory are skipped and listed under the run; the rest of the sync still happens (Succeeded, some items skipped).

Signing in. With Directory password, the Wiki checks the password against the directory at every sign-in (LDAP bind), so password changes and lockouts in the directory apply immediately. The Wiki's own lockout and per-address limits also apply. If the directory can't be reached, sign-in fails for that directory's users (Local users are unaffected). With Single sign-on only, directory users don't sign in with a password here.

Schedule. Each directory syncs at its own interval (every 60 minutes by default). A new directory doesn't sync until you start it: run a Dry run first, then Sync now. After that it runs on schedule. The directory-sync scheduled job checks every minute which directories are due; in a cluster each sync runs on exactly one server. A sync whose server stops in the middle has no result; the nightly cleanup marks it Failed with "The sync stopped before it finished" once it is two hours old, and the next scheduled sync runs as usual.

18. Setting up an LDAP directory

Use this for OpenLDAP, 389 Directory Server, Red Hat Directory Server, FreeIPA, Oracle Unified Directory and other LDAPv3 servers. For Microsoft Active Directory use the next section.

Before you start

  • A Pro license or higher, and the directories:write permission (super admins).
  • Network access from every Wiki server to the LDAP server: port 636 for LDAPS, or 389 for StartTLS.
  • A service account that can read users and groups (read-only is enough), and its password.
  • The base DN under which your users live (for example ou=people,dc=example,dc=com) and, to sync groups, the base DN of your groups.
  • If the server's certificate comes from a private certificate authority: that CA's certificate in PEM format.
  1. Open Settings → Directories — Select Add directory and choose LDAP under Directory servers.
  2. Name the directory — For example Corporate LDAP. It appears in the Users list and filters.
  3. Connection — Enter the Server URL, for example ldaps://ldap.example.com:636. Under Security choose TLS for ldaps://, or StartTLS for ldap://…:389. Paste the CA certificate if your certificate authority is private. Use None only in an isolated test lab.
  4. Service account — Enter the Bind DN (for example cn=wiki,ou=services,dc=example,dc=com) and its Bind password. The password is stored encrypted and never shown again.
  5. Users — Enter the User base DN. The default User filter (objectClass=inetOrgPerson) fits most servers; narrow it to sync only some people, for example (&(objectClass=inetOrgPerson)(memberOf=cn=wiki-users,ou=groups,dc=example,dc=com)).
  6. Groups (optional) — Enter the Group base DN to sync groups; leave it empty to sync users only. The default filter covers groupOfNames and groupOfUniqueNames. For groupOfUniqueNames, set Group member to uniqueMember under Attribute mapping.
  7. Attribute mapping (optional) — Defaults: ID entryUUID, username uid, email mail, display name cn, group name cn, member member. Change them only if your schema differs. Every user needs an email address.
  8. Sign-in — Choose With their directory password (most common) or Single sign-on only.
  9. Sync — Set how often to sync and the deprovisioning limit. Keep the limit low (10% default) unless many people leave at once.
  10. Test and add — Select Test connection: it should report the users and groups it can see. Then select Add directory in the bar at the bottom.
  11. Dry run — On the directory's page select Dry run, then open the run on the History tab: it shows users to create, change and disable, groups to create or merge, and anything it skipped. Adjust filters if needed.
  12. First sync — Select Sync now. Afterwards the directory syncs on its schedule.
  13. Choose the order — On Settings → Directories, move the directory above or below Local. If the same person has a Local account and a directory account, the higher one is used at sign-in.

Fields

FieldWhat to enterExample
Server URLldaps://host:636 or ldap://host:389ldaps://ldap.example.com:636
SecurityTLS, StartTLS or None (test labs only)TLS
Don't check the server certificateLeave off. Turn on only in a test laboff
CA certificatePEM of your private CA-----BEGIN CERTIFICATE-----…
Bind DN / passwordRead-only service accountcn=wiki,ou=services,dc=example,dc=com
User base DN / filterWhere users are and which to syncou=people,dc=example,dc=com / (objectClass=inetOrgPerson)
Group base DN / filterWhere groups are; empty = no groupsou=groups,dc=example,dc=com
Unique IDImmutable ID attributeentryUUID (OpenLDAP), nsUniqueId (389 DS), ipaUniqueID (FreeIPA)
Username / Email / Display nameAttributesuid / mail / cn
Group name / member / descriptionAttributescn / member / description
Sync everyMinutes, 5 to 1008060
Deprovisioning limitPercent of active users, 1 to 10010

19. Setting up an Active Directory directory

Before you start

  • A Pro license or higher, and the directories:write permission (super admins).
  • Network access from every Wiki server to a domain controller: port 636 (LDAPS) or 389 with StartTLS. The domain controller needs a certificate for LDAPS; your AD Certificate Services CA certificate goes in CA certificate if the Wiki doesn't already trust it.
  • A domain service account (a normal user in *Domain Users* is enough to read users and groups). Set its password not to expire, or plan to update it here: an expired password stops syncing and, with directory-password sign-in, stops sign-in for directory users.
  • The distinguished name of the OU with your users (for example OU=Staff,DC=corp,DC=example,DC=com) and, to sync groups, of the OU with your groups.
  1. Open Settings → Directories — Select Add directory and choose Active Directory under Directory servers.
  2. Name the directory — For example Corp AD.
  3. Connection — Enter the Server URL of a domain controller, for example ldaps://dc01.corp.example.com:636, or the domain name if your DNS load-balances domain controllers. Choose TLS (recommended) or StartTLS. Paste your AD CA certificate if needed.
  4. Service account — Enter its full distinguished name as Bind DN, for example CN=svc-wiki,OU=Service Accounts,DC=corp,DC=example,DC=com, and its password. (A user@corp.example.com UPN also works as bind DN on Active Directory.)
  5. Users — Enter the User base DN. The default filter (&(objectCategory=person)(objectClass=user)) reads all people accounts under it. To sync only members of an AD group, use (&(objectCategory=person)(objectClass=user)(memberOf:1.2.840.113556.1.4.1941:=CN=Wiki Users,OU=Groups,DC=corp,DC=example,DC=com)).
  6. Groups (optional) — Enter the Group base DN. Include members of nested groups is on by default: members of groups inside a group count as its members.
  7. Attribute mapping (optional) — Defaults: ID objectGUID, username sAMAccountName, email mail, display name displayName. Users without mail are skipped; if your users have no mail, set Email to userPrincipalName.
  8. Sign-in, sync, test, dry run, first sync and order — As for LDAP above: choose the sign-in mode, test the connection, add the directory, run a dry run, then Sync now, and place the directory in the order.

Accounts disabled in Active Directory (the *account is disabled* flag) are disabled in the Wiki at the next sync, and can't sign in with their password even before that.

20. Setting up a Microsoft Entra ID directory

The Wiki reads users and, optionally, groups from Microsoft Entra ID (Azure AD) through Microsoft Graph, on the schedule you choose, with the same dry run, safety checks and group merging as other synced directories. People sign in with single sign-on; set that up too.

Before you start: an Enterprise license, the directories:write permission, and a Microsoft Entra administrator who can grant admin consent.

  1. Register an app in Entra — In the Microsoft Entra admin center, Identity → Applications → App registrations → New registration, name it Wiki directory sync, single tenant. No redirect URI is needed. (You can reuse the single sign-on app registration.)
  2. Give it read access — Open API permissions → Add a permission → Microsoft Graph → Application permissions and add User.Read.All and GroupMember.Read.All. Select Grant admin consent for <your organization>; the status must show a green check.
  3. Create a secret — Certificates & secrets → New client secret. Copy the Value right away, and note when it expires: sync stops until you enter a new one.
  4. Copy the IDs — From Overview: the Directory (tenant) ID and Application (client) ID.
  5. Add the directory in the Wiki — Settings → Directories → Add directory → Microsoft Entra ID. Enter a name, the tenant ID, client ID and client secret.
  6. Choose users and groups — Optionally narrow users with a User filter. For groups, enter a Group filter (for example only groups whose names start with Wiki) or tick Sync every group in the tenant; with neither, no groups are synced.
  7. Test, create, dry run — Select Test connection (it reports how many users and groups it can see), then Add directory, then Dry run on the directory page and check the preview before Sync now.
FieldWhat to enter
Directory (tenant) IDA GUID, or a verified domain such as contoso.onmicrosoft.com
Application (client) IDFrom the app registration's Overview
Client secret valueStored encrypted, never shown again; leave empty later to keep it
User filterOptional Microsoft Graph $filter on users, for example endswith(mail,'@contoso.com') or accountEnabled eq true. Empty reads every user
Group filterMicrosoft Graph $filter on groups, for example startswith(displayName,'Wiki')
Sync every group in the tenantReads all groups instead of filtering
Sync interval, Deprovisioning limitAs for LDAP (see How directory sync works)

How Entra data maps: the email is the user's mail, or their user principal name when mail is empty (guest accounts without mail are skipped, as they have no usable email); the username is the user principal name; users with Account enabled off are disabled in the Wiki. Group members include members of nested groups.

MessageCause and fix
The service account was refusedWrong tenant ID, client ID or secret, or the secret expired. Create a new secret and enter it
The server refused the searchThe app lacks User.Read.All / GroupMember.Read.All application permissions or admin consent, or a filter is invalid
Items skipped: No email addressThose users have neither mail nor a usable user principal name

21. Setting up a Google Workspace directory

The Wiki reads users and, optionally, groups from Google Workspace through the Admin SDK Directory API, using a service account with domain-wide delegation. People sign in with single sign-on.

Before you start: an Enterprise license, the directories:write permission, a Google Cloud project, and a Google Workspace super administrator.

  1. Enable the API — In the Google Cloud console, open APIs & Services → Library and enable the Admin SDK API.
  2. Create a service account — IAM & Admin → Service accounts → Create service account, name wiki-directory-sync. It needs no project roles.
  3. Create a key — Open the service account, Keys → Add key → Create new key → JSON. A file downloads; keep it safe. Copy the service account's Unique ID (client ID) from its details.
  4. Allow domain-wide delegation — In the Google Admin console, Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new. Client ID: the service account's unique ID. OAuth scopes (comma-separated): https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.group.member.readonly.
  5. Add the directory in the Wiki — Settings → Directories → Add directory → Google Workspace. Enter a name, paste the whole JSON key file, and enter an administrator's email address for the service account to act as.
  6. Choose users and groups — Optionally narrow users with a User query; tick or untick Sync groups and their members.
  7. Test, create, dry run — Test connection, Add directory, then Dry run and Sync now.
FieldWhat to enter
JSON keyThe whole key file. Stored encrypted, never shown again; leave empty later to keep it
Administrator to act asA Google Workspace administrator's email; the service account reads the directory with their access. If that person leaves, enter another administrator
User queryOptional Directory API query, for example orgUnitPath='/Engineering' or isSuspended=false. Empty reads every user
Customer IDEmpty (your own account, my_customer) unless Google support tells you otherwise
Sync groups and their membersOn by default; members of nested groups are included

How Google data maps: email and username are the primary email; suspended or archived users are disabled in the Wiki.

MessageCause and fix
The JSON key isn't a service account keyPaste the whole downloaded key file, not the service account email or an OAuth client file
The service account was refusedDomain-wide delegation isn't set up for that client ID and those exact scopes, the administrator email is wrong, or the key was deleted
The server refused the searchThe administrator to act as isn't an administrator, or the Admin SDK API isn't enabled in the project

22. Setting up a SCIM directory

With SCIM, your identity provider pushes changes to the Wiki as they happen: new people get an account, changes to name and email are copied, and people who are unassigned or deactivated are disabled within seconds. Groups pushed by the identity provider merge with the Wiki groups of the same name. People sign in with single sign-on.

Before you start: an Enterprise license, the directories:write permission, the Wiki address set under Settings → General, and the Wiki reachable over HTTPS from your identity provider (for cloud providers like Okta and Entra ID, from the internet).

  1. Add the directory — Settings → Directories → Add directory → SCIM, name it (for example Okta) and select Add directory.
  2. Copy the address and token — The directory's page shows the SCIM base URL (https://<your Wiki address>/api/scim/v2/<id>) and a Token. Copy both now: the token is shown only once. If you lose it, select Rotate token on the directory's page (the old one stops working at once).
  3. Set up provisioning at your identity provider — See Okta or Microsoft Entra ID below; other providers ask for the same two values (base URL and bearer token).
  4. Set up single sign-on — Add an identity provider for this directory under Settings → Single sign-on so people can sign in.

Okta

  1. Turn on SCIM — In the Okta Admin Console, open your Wiki app (the SAML or OIDC app integration from single sign-on). On General, under App Settings, set Provisioning to SCIM and save.
  2. Connect — On the new Provisioning → Integration tab: SCIM connector base URL = the Wiki's SCIM base URL; Unique identifier field for users = userName; tick Push New Users, Push Profile Updates and Push Groups; Authentication Mode = HTTP Header, and paste the token as the bearer token. Test Connector Configuration, then save.
  3. Choose actions — On Provisioning → To App, enable Create Users, Update User Attributes and Deactivate Users.
  4. Assign people — Assign users or groups on Assignments; they are created in the Wiki. To send groups, add them on Push Groups.

Microsoft Entra ID

  1. Open provisioning — In the Microsoft Entra admin center, Enterprise applications → your Wiki app (or New application → Create your own application → Non-gallery) → Provisioning → Get started, mode Automatic.
  2. Connect — Tenant URL = the Wiki's SCIM base URL; Secret Token = the token. Test Connection, then Save.
  3. Check mappings — Under Mappings → Provision Microsoft Entra ID Users, userPrincipalName → userName, mail → emails[type eq "work"].value, Switch([IsSoftDeleted]…) → active are the defaults the Wiki expects. Keep Provision Microsoft Entra ID Groups on to send groups.
  4. Assign and start — Assign users and groups under Users and groups, then set Provisioning Status to On. Entra provisions every 40 minutes; use Provision on demand to test one person.

What SCIM changes in the Wiki

At the identity providerIn the Wiki
Person assignedAccount created in the SCIM directory (disabled if the license has no free seat)
Name, email or username changedCopied to the account
Person deactivated (active = false)Account disabled and signed out everywhere
Person reactivatedAccount enabled again, unless an administrator disabled it in the Wiki
Person unassigned or deletedAccount disabled (removed from the directory) and removed from the groups SCIM gave it; never deleted. If assigned again later, the same account comes back
Group pushedMerged into the Wiki group with the same name, or a new group
Group members changedOnly memberships this directory added change; people added by hand or by other directories stay
Group removedNo longer linked; the Wiki group stays with its other members
ProblemCause and fix
The identity provider reports 401Wrong or rotated token. Rotate the token in the Wiki and enter the new one
403The SCIM directory is disabled in the Wiki, or the license isn't Enterprise
409 uniquenessAnother account in this directory already has that userName or email
The base URL starts with /apiThe Wiki address isn't set. Set it under Settings → General

23. Troubleshooting directory sync

MessageCause and fix
Couldn't reach the serverWrong host or port, a firewall, or DNS. Check from each Wiki server that the port is open (nc -vz host 636).
The secure connection failedThe certificate isn't trusted or doesn't match the host name. Use the host name on the certificate and paste your CA certificate.
The service account was refusedWrong bind DN or password, or the account is locked, disabled or its password expired.
A base DN doesn't exist on the serverTypo in the user or group base DN. Copy it from your directory tool.
The server refused the searchInvalid filter, or the service account can't read that part of the directory.
Blocked: returned no usersThe filter or base DN matches nobody, or the service account can't see the users. Nothing was changed.
Blocked: more users than the deprovisioning limitCheck whether those people really left. If yes, Run anyway; if not, fix the filter or base DN.
Items skipped: No email addressThose users have no value in the email attribute. Fill it in the directory or map another attribute.
Items skipped: Another group of this directory already uses this nameTwo directory groups have the same name (for example in different OUs). Only the first one is synced; rename one in the directory.
Directory users can't sign inCheck the sign-in mode is With their directory password, the user is Active (not Shadowed or Disabled) on the Users screen, and the directory is reachable from the server.

24. Signing in

Enter your email address (or, for directories that have usernames, your username) and your password. Upper and lower case in the email or username don't matter.

For security, a refused sign-in always says the email or password is wrong. It doesn't tell you whether the account exists, is disabled, or belongs to a directory that signs in another way.

25. Sessions and timeouts

How long people stay signed in is set under Settings → Security → Sessions (super admins: the settings:write permission). It applies to every server of a cluster within about 10 seconds. The Security page has a tab for each kind of setting (Sign-in, Sessions, CAPTCHA, Anonymous access, Rate limits, then the Wiki's own Search engines, Video sites and Imports) and one Save bar that saves whatever you changed on any of them; people see only the tabs they may change. Available on every license tier.

SettingWhat it doesDefault
Sign out after inactivityEnds a session when the person hasn't typed, clicked, touched or scrolled for this long (15 minutes to 24 hours, or Never). Pages that refresh on their own don't count. Two minutes before, the Wiki asks "Still there?" with Stay signed in. Activity in any tab counts for all tabsNever
Maximum session lengthEnds every session this many hours after sign-in, however active the person is (1 to 720). Also applies to single sign-on sessions. A warning shows two minutes before24 hours
Offer "Remember me"Shows the Remember me box on the sign-in page. Untick it to make everyone sign in again after the maximum session lengthOn
Remembered sessions lastMaximum length for sessions with Remember me ticked (1 to 90 days). The inactivity limit still applies7 days
Sessions per personHow many browsers or devices one person can be signed in on; signing in once more ends their oldest session (1 to 100)5

Tighter settings apply at once: a shorter inactivity limit or maximum length signs out existing sessions that are past it on their next request. Looser settings apply to new sign-ins. After an automatic sign-out the sign-in page says why (inactivity, or the time limit).

API tokens aren't sessions: these settings don't affect them. Until you save the page, the defaults come from the AUTH_SESSION_LIFETIME, AUTH_REMEMBER_SESSION_LIFETIME and AUTH_MAX_SESSIONS environment variables.

26. CAPTCHA

The Wiki can ask people to prove they're human where automated attacks happen. Under Settings → Security → CAPTCHA (settings:write, every license tier), switch each on separately and save with the page's Save:

SwitchWhen it asks
Sign-in after failed attemptsOnce an email address or a network address has the chosen number of failed sign-ins (default 3) within 30 minutes; also for addresses that have no account, so it never reveals which accounts exist. A successful sign-in clears the count for that email address
Creating and rotating API tokensIn the browser, on Create token and Rotate. Programs that create tokens with an existing API token aren't asked
Requesting a password resetOn the Forgot password? page, before any email is sent

Providers

ProviderSetupNotes
Built in (default)Nothing to set up. Choose the puzzle size (how long a browser works on it)The browser solves a small computing puzzle automatically; nothing to click and nothing sent to a third party, so it works without internet access. Needs https (or localhost)
Cloudflare TurnstileIn the Cloudflare dashboard, Turnstile → Add widget with your Wiki domain; copy the site key and secret keyBrowsers load the widget from Cloudflare
hCaptchaIn the hCaptcha dashboard, add a site with your domain; copy the site key and the account secretBrowsers load the widget from hCaptcha
Google reCAPTCHA v2In the reCAPTCHA admin console, register a v2 “I’m not a robot” site for your domain; copy the site key and secret keyBrowsers load the widget from Google

The secret key is stored encrypted and never shown again; leave it empty later to keep it. If the provider can't be reached, or rejects the secret key, the request is refused rather than let through; check Settings → Advanced → System check and the server log. Browsers must be able to reach the provider (the built-in one needs nothing).

Turning on the sign-in CAPTCHA with a third-party provider makes sign-in depend on that provider after failed attempts. The built-in provider has no such dependency.

27. Anonymous access

Settings → Security → Anonymous access (settings:write, every license tier) lets people who aren't signed in read public spaces and public questions. It is off by default. What anonymous readers can and can't see, and how search engines are kept out, is in Anonymous access and Search engines and robots.txt.

28. Failed attempts and lockout

The Wiki protects accounts against password guessing in two ways:

ProtectionWhat happensDefault
Account lockoutAfter too many wrong passwords within a time window, the account is locked for a while, even with the right password. The sign-in page says how many minutes are left.5 failures within 15 minutes lock the account for 15 minutes
Per-address limitToo many failed sign-ins from one network address blocks further attempts from that address for a while, whichever accounts they target.20 failures within 15 minutes
  • A successful sign-in resets the account's failure count.
  • Failures are counted across every server of a cluster, so spreading attempts over several nodes doesn't help an attacker.
  • A correct password on a disabled account is refused but doesn't count towards lockout.
  • API and OAuth tokens that were never issued count as failed attempts for the address that sent them.
  • If Redis is unavailable in a cluster, sign-in keeps working and each server counts failed attempts from an address on its own until Redis is back.
  • Administrators can change the per-address limit in Settings → Security → Rate limits (see Rate limits).

Anyone who knows an email address can lock that account by entering wrong passwords, but only for the lockout duration, and only a few accounts per network address because of the per-address limit. To unlock an account right away, an administrator selects Unlock on the user's page.

29. Login history

Every sign-in to an existing account, successful or refused, is recorded with the time, network address, browser and reason (wrong password, locked, disabled). Attempts with an email or username that matches no account aren't stored. The history is kept for 90 days and removed by the auth-session-cleanup scheduled job.

30. Configuration

Set these environment variables on every server (the same values on every node of a cluster):

VariableDefaultWhat it does
AUTH_LOCKOUT_THRESHOLD5Wrong passwords that lock an account
AUTH_LOCKOUT_WINDOW15mHow long failures keep counting; older ones are forgotten
AUTH_LOCKOUT_DURATION15mHow long an account stays locked
AUTH_IP_RATE_LIMIT20Failed sign-ins and unknown tokens from one network address before it is blocked (default until saved in Settings → Security → Rate limits)
AUTH_IP_RATE_WINDOW15mHow long the per-address block and count last
AUTH_LOGIN_HISTORY_RETENTION_DAYS90Days of login history to keep
DIRECTORY_SYNC_CHECK_INTERVAL1mHow often the directory-sync job looks for directories that are due
DIRECTORY_SYNC_RUN_CLEANUP_SCHEDULE40 4 * * *When sync history older than 90 days is removed
AUTH_SESSION_LIFETIME24hDefault maximum session length until Settings → Security → Sessions is saved
AUTH_REMEMBER_SESSION_LIFETIME168hDefault maximum length of remembered sessions, same
AUTH_MAX_SESSIONS5Default sessions per person, same
SSO_ENFORCEMENT_OVERRIDEfalseEmergency only: true makes this server ignore Require single sign-on, so an administrator can sign in with a password when the identity provider is down. See Requiring single sign-on
AUTH_PASSWORD_MIN_LENGTH12Shortest password accepted for new and changed passwords (8 to 64). The setup wizard's first administrator password still needs only 8

31. Events

Changing the session settings raises auth.session_policy.update, which can be blocked by subscribers and used in automation. Every refused sign-in raises auth.login.failed with a reason: invalid_credentials, account_locked, account_not_active, password_not_allowed (the account's directory doesn't sign in with a password here), captcha_required (a CAPTCHA was needed and missing or wrong), sso_required (single sign-on is required) or ip_rate_limited. Use it in automation rules, for example to alert on repeated lockouts.

User and directory changes raise events too: user.create, user.update, user.disable, user.enable, user.role.change and user.password.reset can be restricted by organization policies (for example, only allow emails from your company's domain, or require a new password at first sign-in); directory.sync reports every finished, failed or blocked sync with its counts (for example, an automation rule can alert on status == 'blocked'). user.password.change, user.unlock, directory.create, directory.update, directory.delete and directory.reorder can drive automation. Changes pushed through SCIM raise user.create, user.update, user.disable and user.enable after the fact (they can drive automation but not be blocked: the identity provider is the source of truth). Group changes raise group.create, group.update, group.delete, group.member.add and group.member.remove, all of which organization policies can restrict. Policy compliance scans check existing users and groups against user.create and group.create policies. See Events.