Delivering Monofor implementations
What changed
Every content update is versioned. Select a version to compare it with the one before.
Version 8 → 9
UpdateFour new lessons close the gaps against the MCIP exam: change control inside the products, design constraints to find in discovery, safeguards for the first production changes, and acceptance evidence with operational duties. Each knowledge check has two new questions. Diagrams were added to the new lessons.
4 lessons updated
Content update. Enrolled learners were notified.
A change plan is only as good as its picture of what the product does when someone presses `Save`. Several product behaviours decide whether a careful plan holds in practice. This lesson collects the ones that matter most during delivery, each with the working agreement it calls for.
### Go or no-go is a check, not a mood
Before each wave, write down exit criteria that can be measured: enrollment rate, sign-in failure rate, helpdesk tickets per hundred users. Agree the thresholds before the wave starts, and test the rollback before the meeting. The steering group then compares numbers with thresholds instead of trading impressions, and a wrong call stays cheap because the way back is already proven.
### Monosync: the change history is a record, not an undo
Every save of an integration is a commit with a comment and a ticket number. `Show Commits` lists who changed what and shows the difference. It has no restore control.
| Product behaviour | Working agreement |
| --- | --- |
| Two people edit the same integration. The second save shows `Integration Is Changed` and, after `Overwrite`, replaces the first person's work | One editor per integration at a time, a ticket number on every commit, review with `Show Commits` |
| An earlier version cannot be restored with a click | The change plan records the earlier values so that they can be entered again by hand |
| Values already written to a target system stay there | The rollback names who repairs the target data, and how |
### Schedules and maintenance windows
Schedules are cron expressions in **UTC**. A new or edited schedule on an active integration usually fires once right after the save, because its next run time is already in the past. "Preparing" a schedule on Friday for a Saturday window therefore starts a run on Friday. Save schedule changes inside the window. One integration never runs two jobs at the same moment.
When a target system goes down for maintenance, `Start Maintenance` pauses the integrations. Three details belong in the runbook:
- It does not wait for running jobs. Open `Integration Jobs` and confirm that nothing is running before the target goes down, or choose `Start Maintenance with stopping tasks.` to abort them.
- `Run Once` still works on a paused integration. Tell operators not to use it during the window.
- After the window, schedules resume from the stop time. Runs missed during the window are not caught up.
### Monosign: three changes that cannot be piloted
**Upgrades.** Read the release notes for the exact path. The upgrade from v2026.07 to v2026.09 needs a full stop of every app node and identical migrator versions, because a mixed fleet duplicates work and misses cache invalidations. A node-by-node rolling upgrade is not available on that path, so agree a downtime window early.
**Customized texts.** An edited content item, such as an e-mail template text, or an edited translation survives an upgrade only while the shipped version of that item is unchanged. When a release raises the version, the shipped default replaces the edit on every tenant. The release note carries a warning for such items. Keep a copy of every customization and plan time to re-apply it.
**API Security.** The switch belongs to the application and gates every key of that application at once. It cannot be piloted on a single key. List the endpoints each key calls, grant those permissions on the key's `Permissions` tab, then turn the switch on in a change window. "It works with the master key" is not evidence: a master application passes checks that an ordinary key must hold a permission for.
::diagram del-change-control
### Worked example
A partner will change a mapping and move the schedule of a production integration on Saturday at 22:00. A plan that respects the product reads like this:
1. One named editor. Nobody else opens the integration that evening.
2. The earlier mapping values and the earlier cron are pasted into the ticket.
3. The schedule is saved at 22:05, inside the window, and one immediate run is expected.
4. Go criterion: no failed objects in that first run. Otherwise the earlier values are entered again by hand.
5. A named owner on the target system repairs any value that was already written.
Sizing answers the question "how big". Some discovery findings answer a different one: "will it work at all". They cost nothing to ask about in a workshop and a great deal to find out after go-live. Add these five to your discovery template.
### 1. Can the Monosign servers reach the license service?
Monosign contacts the Monofor license service regularly, by default at `services.monofor.com`. With the online check on, login is refused once the last successful contact is more than 7 days old. A customer network without an outbound route therefore needs a license issued with the online check disabled. Expiry and host validation still apply to such a license. A license cannot be imported in the UI, so settle this with your Monofor contact before the design is signed, not on installation day.
### 2. How large is the directory?
An Active Directory or LDAP source reads at most `Limit` objects per run (500000 by default) in pages of `Page Size` (1000 by default). A larger directory syncs **partially and without an error**. Ask for the object count of every directory. If a count is near or above the default, record in the design that `Limit` must be raised and that the first sync is compared with the directory's own count.
### 3. What sits between the users and Monopam?
Monopam has no local passwords. Users sign in at the identity provider, normally Monosign, and Monopam keeps the result in a cookie that carries the user's groups and permissions. This makes the sign-in response large. Every reverse proxy and load balancer on the path must accept large response headers. One hop with default buffers is enough to break sign-in for users with many groups, typically with `502 Bad Gateway`. List every hop and its owner.
### 4. How will Monosync run under load?
Monosync ships as one container image. Two environment variables decide the role of a node:
| Node role | Setting |
| --- | --- |
| UI only | `MONOSYNC_DISABLE_SERVICE=true` |
| Service node (integration runner) only | `MONOSYNC_DISABLE_UI=true` |
| Both roles | Neither variable set |
All nodes share **one** database and **one** authenticated Redis, which holds the job state and the master election. When many integrations must run in parallel while operators work in the UI, split the roles and add service nodes. Do not give the nodes separate Redis instances, because they would stop coordinating.
### 5. Where do session recordings live?
A Monopam Gateway records a session only when both of its capture paths are configured. Without them it still opens sessions, unrecorded. The paths belong to the Gateway host: its configuration file or, for a container, the environment variables `MONOPAM_GW_CAPTURE_TEMP_PATH` and `MONOPAM_GW_CAPTURE_VIDEO_PATH`. Without a CDN configured for the tenant, recordings stay on the Gateway. A container Gateway therefore needs persistent volumes on both paths, sized for the expected recordings. Otherwise the recordings disappear with the container.
::diagram del-design-constraints
### Scenario
A bank wants every privileged session recorded, runs its gateways as containers and blocks outbound internet access. Three design lines follow before any sizing starts:
| Finding | Design line |
| --- | --- |
| No route to the license service | A license with the online check disabled, requested from the Monofor contact |
| Container gateways, recording is mandatory | Persistent volumes on both capture paths of every Gateway |
| Two proxies in front of Monopam | Large response header buffers on both, with a named owner |
None of these lines changes the number of servers. Each one would stop the project in its first week of production.
The riskiest hours of a project are the first changes on a live tenant: the first enforced policy, the first directory sync, the first certificate and the first key change. Each of them has a simple safeguard. Put all four into the commissioning plan.
### A way back in before MFA is enforced
A misconfigured authentication policy can lock out everyone, administrators included. Before a policy applies to all users, make sure that an emergency administrator account exists that the policy cannot lock out, and prove it: sign in with it on the day, from the network you would use in an incident. This is general good practice for such an account:
- It is a named account, documented in the runbook and owned by the customer.
- Its credentials are kept sealed, for example in a vault that records every checkout.
- Every use is reviewed afterwards.
Leaving all administrators out of MFA is not the same thing. It weakens the most powerful accounts every day in order to cover one bad day.
### First sync of a large directory: start narrow
A mapping mistake spreads to every user the sync touches. So keep the first run small:
1. Point `User Base DN` at a pilot OU and press `Test`.
2. Run the sync and check a handful of users by hand: attributes, group memberships, status.
3. Correct mappings and filters while only the pilot group is affected.
4. Widen the base DN to the full scope and compare the synced count with the directory's own count.
Do not connect any automation that disables or removes accounts until step 4 has passed.
### Replacing the certificate with `monofor cert install`
| Behaviour | What it means for your plan |
| --- | --- |
| It checks that certificate and key form a valid pair before it changes anything | A wrong pair of files is rejected and the running system is untouched |
| It restores the previous certificate and configuration when a later step fails | A failed attempt needs no reinstallation |
| An expired certificate needs `--allow-expired` installs a certificate that has already expired | Use the flag only on purpose, for example in a test environment |
| `monofor status` warns 30 days before expiry | Put the expiry date and the renewal owner into the handover |
### Monopam vault key: the order matters
The vault key ring is read from the environment when a process starts. A running process does not notice a changed variable. The safe order is:
1. Set the same `MONOPAM_VAULT_KEY` and version on **every** process that reads secrets: Web, Gateway with its proxies, Automator and RemoteSession.
2. Restart all of them.
3. Only then run the re-encryption job.
If the job runs while the Gateway still holds the old key ring, Web rewrites rows that the Gateway cannot decrypt, and every connection through it fails. There is also no recovery for a lost key, so record where it is kept and who owns it, never the key itself.
::diagram del-commissioning-day
### Scenario
A commissioning day plan built on these safeguards:
| Time | Step | Proof |
| --- | --- | --- |
| 09:00 | Emergency administrator sign-in tested | Named tester, result noted |
| 09:30 | AD source limited to the pilot OU, synced | 40 users checked by hand |
| 11:00 | Customer certificate installed | `monofor status` shows the Certificate row without a warning |
| 13:00 | Vault key set on five processes, all restarted, job run | One RDP and one SSH session opened through the Gateway |
Every line has a name and a time. The same list is your first piece of acceptance evidence.
Acceptance is the moment the customer agrees that the agreed scope works. Handover is the moment the customer's operators become responsible for keeping it working. Both depend on reading the product's own records correctly.
### A UAT that proves something
A walkthrough shows activity. A test proves coverage. For sign-off, three things must be true:
- Every test case traces to a requirement in the agreed scope, and every requirement has at least one test case.
- The customer's people run the cases, or run them together with you. Testing by the partner alone proves only that the partner is satisfied.
- Every result is logged with date, tester, outcome and evidence, such as a report row or a screenshot.
| Requirement | Test case | Evidence |
| --- | --- | --- |
| Assigning a group in Monosign adds the user to the AD group | Assign a pilot user and wait for the write-back | The row in Reports → `Provisions` and its `View Logs` history |
::diagram del-uat-evidence
### Read the provisioning report to the end
Reports → `Provisions` lists directory group write-backs and resource provisions, each with its **latest** attempt. A row in state `Provisioned` may have failed several times before it succeeded. The row menu `View Logs` opens every attempt with date, state and message. Use it whenever a customer asks whether a provision had errors on the way. Know the limit as well: the state of SCIM pushes is not part of this report.
### Things that fail silently
`Dead Letters` under Management → System → Services collects notifications, provisioning jobs and webhooks that stopped short of delivery. **Nothing raises an alert for them.** Someone has to open the page. The runbook therefore names an owner and a review rhythm, and gives criteria for the two actions:
| Action | Effect | Use it when |
| --- | --- | --- |
| `Requeue` | Returns the item to its ready state. It can fail again and come back to the list | The cause has been fixed, for example the mail server is reachable again |
| `Discard` | Clears the row from the list and sends nothing. The row and its error stay in the database | The item is no longer worth sending |
### The license banner
With the online check on, Management shows a banner once the license server has been unreachable for 3 hours. Login is refused when the last successful contact is more than 7 days old. Teach operators to treat the banner as urgent. The 7 days are the time they have to restore outbound access, not a reason to wait.
### Retention is a signed decision
| Product | Behaviour | Decision to record |
| --- | --- | --- |
| Monosign | Enabling the `Audit` rule in `Data Retention` deletes older audit rows permanently, with no archive before deletion | The number of days, and where older records are kept if compliance needs them longer |
| Monosync | Log purges have no archive either, and incremental runs rely on the record of the last successful run | Day values above the longest gap you expect between successful runs |
Have the customer's compliance owner sign both lines in the handover pack. A retention value that nobody chose is the kind of finding that surfaces in an audit a year later.
### Handover checklist for these points
- UAT log with requirement, case, tester, result and evidence for every line
- `Dead Letters` owner and review rhythm written into the runbook
- License banner explained, with the contact who restores outbound access
- Retention values signed by the compliance owner