Help

Integration

macOS Troubleshooting

Updated 16 Nov 2026 8 min read

Problems seen with Monofor Identity Client for macOS 2.4.25 and how to fix them. Run all commands as an administrator (they need sudo). See also macOS.

Tools

Status

Prints a summary without any secret: configuration, linked accounts, sudo hook state, cached texts and logo, audit queue size, Touch ID state. From 2.4.20, --status, --configure and --check-offline run through the daemon, so the daemon must be running.

sudo /usr/local/bin/Identity-Daemon --status

Example output of --status (identifiers hidden here)

What to look at:

Field

Healthy value

configured

true

loginMode / authMode

monofor / monofor (or default when administrator prompts use the macOS password)

sudoHook

on. blocked means Full Disk Access is missing; off when administrator prompts use the macOS password.

users[]

One entry per linked account with hasPassword, hasDeviceSecret, hasOfflineSecret = true. Also hasSession and touchIdOn (true when the user turned on Touch ID).

loginActive

Whether the Monofor login window is active.

passwordLogin / passwordScreen

From 2.4.25. true / monofor by default. false hides the password link on the Monofor screen; macos makes it open the macOS sign-in screen.

touchIdCheck

Why Touch ID is or is not offered, for example setup: can be turned on or not offered: the session helper is not connected.

cachedTexts / cachedLogo

Texts counted per language, logo true when branding is on

auditQueueBytes

0 or small. A growing number means audit events are not accepted.

Offline code check

Tells whether a code fits this Mac's offline secret, without using up an attempt:

sudo /usr/local/bin/Identity-Daemon --check-offline <local user> <code>

Logs

log stream --level debug --predicate 'subsystem == "com.monofor.identity"'
log show --last 30m --predicate 'subsystem == "com.monofor.identity"'

Categories: daemon, plugin, prompt, helper.

Problems

Symptom

Cause

Fix

The lock screen shows the macOS password field instead of Monofor.

The Mac is not configured, the daemon is not running, or the session helper is old (right after an upgrade).

Check --status (configured true). Check sudo launchctl print system/com.monofor.identity-daemon. If it is not loaded: sudo launchctl bootstrap system /Library/LaunchDaemons/com.monofor.identity-daemon.plist. Log out and in once after an upgrade. If macOS fails to switch to the Monofor login window on lock, the helper tries once more after 40 seconds and logs the failure (category helper).

--configure or --status prints The Monofor Identity daemon is not running.

From 2.4.20 these commands run through the daemon, which is not loaded.

Start it: sudo launchctl bootstrap system /Library/LaunchDaemons/com.monofor.identity-daemon.plist, then run the command again.

Configurator: Service not running.

The daemon did not start after installation.

Bootstrap it with the command above.

Configurator: Needs Full Disk Access; sudo still asks for the macOS password.

macOS protects /etc/pam.d; Identity-Daemon may not write sudo_local.

Use Open Full Disk Access, add /usr/local/bin/Identity-Daemon (or deploy the PPPC profile), then save the Configurator again. If an entry already exists from an older version, remove it and add it again: the permission is bound to the code signature.

sudo approval is not active (sudo does not open the Monofor approval window).

Identity-Daemon has no Full Disk Access (sudoHook is blocked in --status).

Give Identity-Daemon Full Disk Access, or deploy the Monofor PPPC profile com.monofor.identity-pppc.mobileconfig.

The Touch ID tab is missing in the approval window.

One of the conditions is not met: the console account is linked, Monosign can be reached, Touch ID is allowed in the Configurator, the Mac has Touch ID with enrolled fingers.

Run sudo /usr/local/bin/Identity-Daemon --status and read touchIdCheck; it says why Touch ID is or is not offered.

Touch ID stopped working after a fingerprint was added or removed.

The Touch ID key is bound to the set of fingerprints and is no longer valid.

Turn Touch ID on again in the approval window (one QR or push approval).

Touch ID is refused.

Monosign cannot be reached, or the account is not active, the session expired or the device is locked. Each use is checked with Monosign.

Approve with QR, push or the offline code. For the other cases the message tells the reason.

macosuser is not in the sudoers file

The user is a standard user.

Expected: sudo is only for administrators. Add the user to the policy's administrator group, or make the account an administrator.

Offline code is rejected.

Code from another Mac's entry in the app, or the clock is off.

Run --check-offline. It reports whether the code matches and at what clock offset (accepted window is -60 to +60 s).

Too many failed offline attempts

Offline sign-in locked after wrong codes.

Connect to the network and sign in with the QR code; this resets the counter.

The screen does not switch to the offline code.

The client still reaches Monosign (the check is /api/ping within 2 s every 5 s).

Wait a few seconds; if Monosign is reachable but sign-in fails, the problem is on the server side.

No mobile authenticator is registered for this account.

The user has no Monofor Identity authenticator.

Register the mobile app for the user in Monosign.

Wait a few seconds before sending another notification.

Push was sent less than 15 s ago for that account.

Wait for the countdown.

A Mac account is not created on first sign-in (the user is asked for a Mac password instead).

No Identity Client policy matches this user and Mac, or the matching policy does not allow local accounts.

Enable Local Accounts (macOS) in the policy that matches the device. The daemon log says which case it was: first sign-in: no device policy applies to this device or the device policy does not allow creating Mac accounts.

The created account is not an administrator, or keeps administrator rights after removal from the group.

The user is not in the policy's administrator group, the group name differs, or the change has not been checked yet.

The group is matched by name or title, nested groups included. Changes apply within about a minute while the user is signed in, and at every sign-in. The daemon log shows admin rights granted to or admin rights removed from; the Monosign audit log shows CP_LOCAL_ADMIN_CHANGED. Accounts that existed before linking are not changed.

Your account is not assigned to this application in Monosign. after scanning the QR code.

The user is not assigned to the Identity Client application.

Assign the user (or a group) to the application in Monosign, then scan the new QR code.

This approval has expired. during account creation.

The sign-in took longer than the approval lifetime (for example the client was reinstalled meanwhile).

Start the sign-in again.

No audit records in Monosign.

Missing permissions, or events are still in the queue.

Events arrive in batches every 30 s. Check auditQueueBytes and the daemon log for audit: sent or audit batch rejected. The key needs System.API.Audits.Create and System.API.AuditTypes.List.

Texts are not in the tenant's language.

Missing System.API.Languages.List, or not fetched yet.

Check cachedTexts in --status. Texts refresh daily and when the server version changes.

No company logo.

Branding off, no QR watermark in the tenant branding, or missing System.API.Policies.View (the permission of the branding endpoint).

Enable Show the company logo in the Configurator; check cachedLogo.

Keychain asks for the old password after a password sync.

The login keychain keeps the previous password.

Known limitation: when macOS asks to update the keychain password, enter the previous password once.

The display of an idle Mac lights up for a few seconds after it went dark.

From 2.4.23 the client opens the Monofor sign-in screen right after an idle lock, and macOS turns the display on for that.

Expected. The display goes dark again by itself. It does not happen with the lid closed.

After a wake, the macOS lock screen shows for a second or two before the Monofor screen.

A version before 2.4.23, or the client was updated while the screen was locked (the lock in progress stays on the macOS screen).

Update to 2.4.23 or later. After an update that ran while the screen was locked, unlock once; the next lock shows the Monofor screen.

Go back to the default Sign-in window is missing on the Monofor screen.

From 2.4.25: password sign-in is turned off (passwordLogin is false in --status).

Expected. Sign in with the QR code, push or the offline code. An administrator can turn it on again with sudo /usr/local/bin/Identity-Daemon --configure password-login=true or in the Configurator.

The macOS sign-in screen is shown with a Passwordless Login button.

From 2.4.25: somebody chose Go back to the default Sign-in window and the administrator set the macOS sign-in screen for password sign-in.

Press Passwordless Login to return to the Monofor screen, or sign in with the password. The Monofor screen returns by itself after the next sign-in.

A remote lock from Monosign does not lock the Mac, or only after the next sign-in.

The Mac's Monosign session ran out (older Monosign server), so the Mac could not ask for pending locks. The daemon log shows lock-status refused the session.

Update the Monosign server; from November 2026 the session of a signed-in computer is kept alive. Until then, a sign-in or unlock with Monofor on the Mac brings a new session.

Sign-in is broken and nobody can log in.

From SSH or Recovery run sudo monofor-identity-reset to put macOS sign-in back to stock. It keeps the client installed and stops it. sudo monofor-identity-reset --uninstall also removes the client and its data.

Permanent link