Monosign directories and user sources
What changed
Every content update is versioned. Select a version to compare it with the one before.
Version 2 → 3
Update3 lessons updated
Content update. Enrolled learners were notified.
Two Monosign components talk to directories, and they work in opposite directions. Picking the wrong one is the most common design mistake.
| Requirement | Component |
| --- | --- |
| Bring users and groups from a directory **into** Monosign, and let them sign in with the directory password | A **user source** (Directory → `Sources`) |
| Let a system that only speaks LDAP authenticate **against** Monosign identities | The **LDAP gateway** |
A user source imports. The LDAP gateway serves. The gateway never reads Active Directory on behalf of an application, and a source never answers LDAP binds.
::diagram dir-source-vs-gateway
::shot dir-sources-list
### Creating a source
`Add New` asks for the `User Provider` (`Active Directory or LDAP`, or another provider) and a `Title`. The provider is shown as read-only text after you save. A source created with the wrong provider cannot be corrected: you create a new source and remove the old one. Plan that swap for a window agreed with the affected users, because they cannot sign in through the old source once it is removed, and the new one must finish its first sync before they can use it.
### What `Remove` does
Removing a source is a soft removal. The source is kept with the status `Removed` and its history, all its users are set to `Removed` and its groups are removed. Users of the source lose their sign-in path, and the page offers no way to undo it.
### Saving settings
The provider settings page is saved as a whole, so every save replaces all stored settings.
- Encrypted fields, such as the bind password, are shown blank when you open the page. Leaving one blank **keeps** the stored secret; typing anything replaces it.
- Any other field that is blank when you save is **cleared**. If an optional field such as a filter looks empty but used to hold a value, enter it again before you save.
### Schedule
`Enable Auto Sync` turns scheduled sync on. `Full Sync Cron` defaults to midnight and `Sync Cron` to every minute. Switching `Full Sync Completed` off forces the next run to be a full sync. You cannot start, stop or cancel a run from the pages.
> Tip: Run `Test` on the settings page after every change. It walks through the connection steps one by one, so a wrong host or credential shows up before the next scheduled sync.
One connector, `Active Directory / LDAP User Provider`, serves Microsoft Active Directory and the other supported LDAP directories. A source of this kind does four things:
- **Syncs** users, groups and profiles. Groups that are members of other groups keep that relationship in Monosign.
- **Authenticates** users against the directory with the password they type.
- **Changes passwords** in the directory when the source allows it (`Allow Password Change`).
- Carries out **account unlock** requests in the directory.
This is why a requirement such as "import from AD, and let people change their AD password and unlock their account through Monosign" is answered by a user source and nothing else.
### Connection settings
- **`Domain IP or Host`**: one or more hosts, separated by commas or semicolons. `Find` discovers the remaining settings from the host.
- **`Use Secure Connection`**: turns on LDAPS and moves the port from 389 to 636.
- **`Domain UserName` and `Domain Password`**: the everyday bind account. `Use Privileged User` adds a second account for operations that need more rights, such as password resets.
::shot dir-source-settings
### Name domain controllers, not the domain
A domain name in `Domain IP or Host` is not one server. Every domain controller registers under that name, so each connection may land on a different controller. One unhealthy controller then fails a share of sign-ins with no visible pattern, and a retry succeeds. A single entry also switches host failover off, because failover needs at least two entries, in practice three. List explicit domain controllers.
::diagram dir-domain-controllers
### Certificates
When secure binds fail with TLS errors, for example after the domain controllers renewed their certificates, the production fix is to install the issuing CA or to update the pinned `SSL Certificate Thumbprint`. `Skip SSL Certificate Validation` set to `Yes` silences certificate errors for every sign-in on the source. Keep it for a short diagnosis only.
### Sync size
Two settings bound each run: `Limit` (default 500,000 objects) and `Page Size` (default 1,000). A directory larger than `Limit` syncs **partially and without any error**. If a full sync finishes cleanly but fewer users appear than the directory holds, check `Limit` first and raise it.
> Note: Monosign does not write profile attributes back to the directory. Profile data flows from the directory to Monosign only.
### Two records of a sync
Each source offers two views, and they answer different questions.
| View | What it is | Limits |
| --- | --- | --- |
| `Sync log` | A live tail of the running sync | Kept only while the page is open, at most 2,000 lines and 20 runs per source |
| `Sync history (stored)` | The durable record | Kept for 60 days |
The live `Sync log` is local to a data center. In a deployment with two data centers, a run executed by a service node at the other site never appears on your page, not even later, although the source's state still moves to `Finished`. Full syncs do write to the live log when the run is local. If you expect lines and see none, open `Sync history (stored)`, or open Management in the data center that ran the sync.
### Changing membership of a directory group
A group that comes from a directory source belongs to the directory. When you assign a user to such a group in Monosign:
1. Monosign writes no local membership. You see `Group membership queued for provisioning to the source directory.`
2. The provisioning queue writes the membership into the directory, normally within about 10 seconds.
3. The member appears under `Assigned Objects` on the group only after the **next inbound sync** imports it.
::diagram dir-directory-group-write
So a directory that already shows the member while `Assigned Objects` is still empty is the expected state between steps 2 and 3. Keep three things in mind:
- `queued` means the request was recorded, not that the directory accepted it.
- The `Provision` and `Deprovision` checkboxes of the source are not consulted on this path.
- Only membership of an existing group is written. Monosign does not create the group in the directory.
A failed write is retried. After the 20th failure the row is closed with `Maximum retry count (20) reached, no action taken!` and is never retried, so the assignment has to be made again once the directory is healthy.
### Usernames that exist in more than one source
After you connect a second directory, some usernames may exist in both. Directory → Users → `Duplicated Users` lists every username found in more than one source, with one column per source and a `Duplication` count. Only the exact username is compared, not email or profile values.
The page is a read-only report. It has no merge, remove or open action, so you resolve each duplicate on the user pages. It loads the whole result at once, which can take long on very large directories.
> Tip: Check `Duplicated Users` right after the first sync of a new source, before users start signing in.
::shot dir-duplicated-users