Last updated on November 17, 2026
Overview of MFA for macOS
Rublon MFA for macOS adds Multi-Factor Authentication (MFA) to local console logins on a Mac. The user first signs in with their macOS account name and password. After macOS validates the password, the Rublon Prompt asks the user to complete a second authentication step. The desktop session starts only after the authentication flow is successfully completed or the applicable bypass policy allows the login.
Adding MFA reduces the risk of unauthorized access when a macOS password has been stolen or compromised.
Rublon MFA for macOS integrates with the standard macOS login window. It does not replace the account picker or the password field. The connector adds a post-password Rublon MFA authentication step to the local console login flow.
Note
Rublon MFA for macOS protects local console logins. It does not protect FileVault preboot disk unlock, screen saver or lock-screen unlock, SSH, sudo, administrator elevation prompts, or authentication to remote-access services. If remote-control software displays the Mac’s local console login window, the console-login behavior depends on that software and must be validated separately.
Supported Systems
- macOS 14 Sonoma
- macOS 15 Sequoia
- macOS 26 Tahoe
- macOS 27 Golden Gate
We provide separate installation packages for Apple silicon (arm64) and Intel (x86_64). Download the package that matches the target Mac.
Note
Rosetta does not make the Intel (x86_64) package work on a Mac with Apple silicon. Use the arm64 package on these Macs.
Minimum Hardware Requirements
- Apple silicon or Intel processor
- Approximately 100 MB of free disk space
- An administrator account for installation
- Correct system date and time
- Network connectivity to the Rublon API over TCP port 443 for online MFA
How Rublon MFA for macOS Works
The connector adds an MFA step after the standard macOS password check.
- The user selects an account in the standard macOS login window.
- The user enters the account password.
- macOS validates the primary credentials.
- The connector sends the local macOS account username to the Rublon API.
- The Rublon Prompt displays the authentication methods available to the user under the applicable Rublon MFA policy.
- The user completes an authentication method.
- The connector validates the completed transaction with Rublon MFA.
- After a successful response, macOS starts the user’s desktop session.
If the user cancels the Rublon Prompt, the login is canceled, and macOS returns to account selection.
Network Diagram

Supported Authentication Methods
| Authentication Method | Supported | Comments |
| Mobile Push | ✔ | N/A |
| FIDO | – | N/A |
| Passcode | ✔ | N/A |
| SMS Passcode | ✔ | N/A |
| SMS Link | ✔ | N/A |
| Phone Call | ✔ | N/A |
| QR Code | ✔ | N/A |
| Email Link | ✔ | N/A |
| YubiKey OTP | ✔ | N/A |
| RFID | – | N/A |
Note
Rublon MFA for macOS does not provide local offline Passcode verification. When the Rublon API cannot be reached, access is allowed or denied according to the connector’s Bypass MFA when the API server is unreachable setting.
User Identification
Rublon MFA for macOS identifies a user by the short local macOS account name. For example, the connector sends bob for a local account whose short name is bob.
The username format is not configurable in the installer. Ensure that each protected macOS account can be matched to the correct Rublon MFA user. If your Rublon MFA users are synchronized or identified by an email address, UPN, or domain-qualified name, configure the appropriate identity alias in the Rublon Admin Console before enabling strict access policies.
Note
Incorrect identity mapping can cause a user to be bypassed or denied, depending on the configured fallback policy. Validate every account used for administration and recovery before broad deployment.
Known Limitations
- The connector protects local console login only.
- Screen saver and lock-screen unlock are not protected.
- SSH, sudo, administrator elevation prompts, and authentication to remote-access services are not protected yet.
- Offline MFA is not available yet. The offline setting controls bypass or denial when the API server is unreachable.
- The connector sends the short local macOS username. Username format cannot be changed in the installer.
- Connector-specific proxy settings are not available. The connector uses the HTTP and HTTPS proxy configured in the macOS network settings.
- Apple silicon and Intel use separate installation artifacts. Universal 2 is not provided.
- FileVault preboot authentication is outside the connector’s scope. Unlocking a FileVault volume does not constitute Rublon MFA authentication.
- With FileVault turned on, macOS by default automatically signs in the user who unlocked the disk after a restart, usually before the Mac is back on the network. The installer therefore sets DisableFDEAutoLogin to true: users enter their password again at the macOS login window and complete MFA. If a configuration profile or a local setting already sets DisableFDEAutoLogin, the installer keeps that value. When automatic login stays on, the Bypass MFA when the API Server is unreachable setting decides whether the user is signed in without MFA or sees the macOS login window.
Before You Start
Before installation:
- Confirm that the Mac meets the system requirements.
- Confirm that the system date and time are correct.
- Confirm that the Mac can reach the Rublon API over TCP port 443 (https://core.rublon.net).
- Keep at least one administrator session open during installation and the first login test.
- The connector must be installed on every Mac you want to protect. For larger fleets, use the command-line installation.
Pre-Installation Steps
1. Sign in to the Rublon Admin Console.
2. In the panel on the left, click Applications.
3. Select Add Application.
4. Enter a name for the application, for example, Rublon MFA for macOS.
5. In the Type dropdown, select macOS.
6. Decide if you want to enable username normalization and the Manage Authenticators view. For more information, look at How to add an application. If you are not sure whether to enable Username Normalization, especially in a multi-domain environment, refer to How to Choose the Username Format for Rublon MFA for Windows and Directory Sync.
7. Click Save to add your new application.
8. Note down the values of System Token and Secret Key. You are going to need these values later during installation.
9. Download the Rublon MFA for macOS installer:
Installation of MFA for macOS
Interactive Installation
Use this method to install Rublon MFA on a single Mac.
Keep an administrator session open until you have successfully tested a new login. An incorrect token, secret, identity mapping, firewall rule, or strict fallback policy can prevent users from signing in.
1. Open the architecture-specific DMG.
2. Run the installer.
3. The setup wizard scans the Mac for an existing connector bundle, preferences, and login authorization mechanism.
- If this is the first time you are installing the connector, click Continue.

- If an existing installation is detected, the wizard shows two options, with Clean installation selected by default. Select one of the following and click Continue:
- Clean installation – deletes the existing local Rublon MFA preferences and remembered-device data, then installs as on a new Mac. You enter all settings again, and every user completes MFA again at the next sign-in.
- Update current installation – reinstalls the connector. Settings already present on the Mac are kept and locked; Setup asks only for missing values and skips screens on which all settings are already present. Remembered devices are kept. To read the current settings, Setup asks for administrator authorization.
With either option, Setup adds Rublon MFA to the login flow again and sets enabled and rememberDeviceIPCheckEnabled to true.

4. On Set up credentials, enter the API server URL and then enter the API credentials (System Token and Secret Key) from your application of type macOS in the Applications tab of the Rublon Admin Console, and click Continue.

| Option | Description |
| API Server | Rublon API base URL. Keep the default value unless Rublon Support tells you to use another server. |
| System Token | System Token of your application in the Rublon Admin Console. Paste the value you noted down before. |
| Secret Key | Secret Key of your application in the Rublon Admin Console. Paste the value you noted down before. |
5. On Bypass configuration, configure the fallback behavior and click Continue. Refer to the following image and table.

| Option | Description |
| Bypass MFA when it cannot be performed | Allows login when the API Server is reachable but the transaction cannot be performed, for example because the user is not enrolled or the service returns an error. Clear this option to deny login in these cases. |
| Bypass MFA when the API Server is unreachable | Allows login when the connector cannot reach the API Server because of no network connection, DNS failure, connection failure, or timeout. Clear this option to deny login in these cases. |
Note
We recommend keeping both options enabled during the first installation and pilot. After validating network access, user enrollment, identity mapping, and a recovery procedure, you can switch to a stricter policy.
6. On Logging configuration, choose a logging level. Refer to the following image and table.

| Level | Description |
| Normal | High-level flow, errors, policy decisions, and final outcomes. |
| Debug | Adds support context, timings, state transitions, and non-sensitive identifiers. |
| Trace | Maximum local diagnostics. Sensitive values remain redacted unless separately enabled. |
7. Leave Log Rublon MFA request and response bodies and Allow sensitive data in support logs disabled unless Rublon Support asks you to enable them. Sensitive logging is available only at Trace level. The Secret Key is never included in connector logs.
8. On Ready to install (Ready to update when updating), review the summary and click Install (Update when updating).
During installation, Setup:
- backs up the current macOS console login authorization chain;
- installs the Rublon MFA for macOS connector;
- adds the Rublon MFA mechanism to the local console login flow;
- stores the connector configuration in protected system preferences;
- turns off FileVault automatic login (DisableFDEAutoLogin), unless a configuration profile or a local setting already sets it;
- installs support, recovery, and log-rotation helpers.

9. Approve the macOS administrator authorization prompt.
10. Wait until the wizard confirms that installation has completed.

11. After installation, use Fast User Switching to keep the administrator session open and complete a test login with an enrolled Rublon MFA user. Do not close the existing administrator session until this test succeeds.
Network Requirement
Ensure that outbound HTTPS traffic to core.rublon.net on TCP port 443 is allowed. See How should I configure my firewall for Rublon MFA? for general Rublon MFA firewall guidance.
Command-Line Installation
The setup application also supports unattended installation. Command-line mode must run as root. Select one of the following commands as your template and adjust them accordingly.
Note
For production automation, read the System Token and Secret Key from protected files or standard input. Avoid passing secrets as literal command-line values, because they can appear in shell history or process listings.
Multiline command with values provided directly:
sudo "/path/to/RublonMFA-Setup.app/Contents/MacOS/RublonMFASetup" \
--api-url "https://core.rublon.net/" \
--system-token "YOUR_SYSTEM_TOKEN" \
--secret-key "YOUR_SECRET_KEY" \
--quiet
Note: Replace “/path/to/” with the actual path to the folder containing the RublonMFA-Setup.app file.
Note: Passing credentials directly is convenient for testing, but they may be retained in shell history or visible in process listings.
Important
Do not create a single-line command by merely removing line breaks from the multiline example. The continuation backslashes (\) would remain and could turn indentation into part of an argument. Use the following dedicated single-line example.
Single-line command with values provided directly:
sudo "/path/to/RublonMFA-Setup.app/Contents/MacOS/RublonMFASetup" --api-url "https://core.rublon.net/" --system-token "YOUR_SYSTEM_TOKEN" --secret-key "YOUR_SECRET_KEY" --quiet
Note: Replace “/path/to/” with the actual path to the folder containing the RublonMFA-Setup.app file.
Note: Passing credentials directly is convenient for testing, but they may be retained in shell history or visible in process listings.
Multiline command that reads credentials from files:
sudo "/path/to/RublonMFA-Setup.app/Contents/MacOS/RublonMFASetup" \
--api-url "https://core.rublon.net/" \
--system-token "@/path/to/system-token.txt" \
--secret-key "@/path/to/secret-key.txt" \
--quiet
Note: Replace each “/path/to/” with the actual path to the folder containing the RublonMFA-Setup.app file or the credential file.
Note: Each file must contain one credential. Leading and trailing whitespace, including a final newline, is removed. Restrict access to these files and remove unnecessary copies after installation.
Command-Line Options
| Option | Description | Required |
--api-url URL | Rublon API base URL. | Yes |
--system-token VALUE | System Token of your application in the Rublon Admin Console. Use @PATH to read it from a file or – to read one line from standard input. | Yes |
--secret-key VALUE | Secret Key of your application in the Rublon Admin Console. Use @PATH to read it from a file or – to read one line from standard input. | Yes |
--fail-mode bypass|deny | Bypasses MFA or denies login when the API server is reachable but MFA cannot be performed. Default: bypass | No |
--offline-auth 0|1 | 1 allows login and 0 denies login when Rublon MFA is unreachable. Default: 1 Note: This option does not enable Offline Mode authentication. | No |
--request-timeout MS | The number of milliseconds after which Fail Mode or Offline Mode will be triggered if the Rublon API cannot be reached. Default: 20000 Allowed range: 1–300000 | No |
--log-level normal|debug|trace (1|2|3) | Connector logging level. normal(1) – High-level flow, errors, policy decisions, and final outcomes. debug(2) – Adds support context, timings, state transitions, and non-sensitive identifiers. trace(3) – Maximum local diagnostics. Sensitive values remain redacted unless separately enabled. Default: normal | No |
--debug-rublon-requests | Enables request and response body diagnostics. | No |
--enable-sensitive-data-logging | Allows sensitive diagnostic values. Takes effect only with --log-level trace. With a lower level, Setup writes false and reports it at the end of the installation. The Secret Key is never logged. | No |
--clean-reinstall* | Removes the local preferences file and remembered-device data before installation. Every user completes MFA again at the next sign-in. | No |
--no-clean-reinstall* | Keeps existing local preferences and remembered-device data. | No |
--log PATH | Sets the installer script log path. | No |
--quiet | Suppresses progress output. Errors and notes are still written to standard error. | No |
--version | Prints the setup and connector versions and exits. | No |
--help | Displays the full command-line help. | No |
* – If neither --clean-reinstall nor --no-clean-reinstall is given, Setup performs a clean reinstall when it detects an existing connector.
Configuration of MFA for macOS
In the following table, Required indicates whether the administrator must provide the value during initial installation. The API URL is required as a command-line argument, while interactive Setup supplies the release default. Values generated or defaulted by the installer are not required.
For each key, the description lists the defaults write flag that matches its property-list type.
| Key | Description |
apiBaseURL | Base URL of the Rublon API. defaults write flag: -stringSupported values: https://core.rublon.net/Fresh-install default: https://core.rublon.net/Required: Command line only |
callbackURL | Local callback used to complete the Rublon Prompt transaction. Do not change this value. defaults write flag: -stringSupported values: http://127.0.0.1:18181/rublon/callbackFresh-install default: http://127.0.0.1:18181/rublon/callbackRequired: No |
systemToken | System Token of the macOS application in the Rublon Admin Console. defaults write flag: -stringSupported values: Tenant-specific, non-empty value Fresh-install default: None Required: Yes |
secretKey | Secret Key of the Rublon macOS application in the Rublon Admin Console. defaults write flag: -stringSupported values: Tenant-specific, non-empty value Fresh-install default: None Required: Yes |
enabled | Enables or disables connector policy evaluation without removing the connector. defaults write flag: -boolSupported values: true or falseFresh-install default: true (Every installation and update resets this value to true)Required: No |
failMode | Controls login when the Rublon API is reachable, but MFA cannot be performed. defaults write flag: -stringSupported values: bypass or denyFresh-install default: bypassRequired: No |
offlineAuth | Allows login when the Rublon API is unreachable. This is an offline bypass setting, not offline MFA. defaults write flag: -boolSupported values: true or falseFresh-install default: trueRequired: No |
rememberDeviceIPCheckEnabled | When true, a remembered device is revoked after the Mac’s public IP address changes, and the user completes MFA again. When false, remembered devices are kept when the network changes. If the public IP address cannot be determined, the remembered device is kept. This setting is not available in Setup or the command line. Change it after installation with defaults write. defaults write flag: -boolSupported values: true or falseFresh-install default: trueRequired : No (Every installation and update resets it to true) |
requestTimeoutMs | Maximum wait time in milliseconds before failure policy is applied. defaults write flag: -intSupported values: 1–300000 millisecondsFresh-install default: 20000Required: No |
logLevel | Controls the amount of information written to logs. defaults write flag: -intSupported values: 1 Normal, 2 Debug, or 3 TraceFresh-install default: 1Required: No |
debugRublonRequests | Enables request and response body diagnostics. defaults write flag: -boolSupported values: true or falseFresh-install default: falseRequired: No |
enableSensitiveDataLogging | Allows sensitive values in diagnostics. The Secret Key is never logged. defaults write flag: -boolSupported values: true or false; true requires logLevel=3Fresh-install default: falseRequired: No |
preferencesSchemaVersion | Used by the installer for preference migrations. Do not change this value. defaults write flag: -intSupported values: Current schema: 1Fresh-install default: 1Required: No |
Viewing and Modifying Preferences
Administrative access is required because the preferences file contains tenant credentials.
Display the Complete Configuration
Use defaults to display the complete configuration:
sudo defaults read /Library/Preferences/com.rublon.macos.mfa.plist
Alternatively, display the underlying property-list representation:
sudo plutil -p /Library/Preferences/com.rublon.macos.mfa.plist
Warning
Both commands display the System Token and Secret Key. Do not paste their output into tickets, email, chat messages, or unredacted support logs.
Read a Single Value
sudo defaults read /Library/Preferences/com.rublon.macos.mfa.plist failMode
Replace failMode with another key from the preferences reference table.
Write or Replace a Value
Always provide the correct property-list type:
sudo defaults write /Library/Preferences/com.rublon.macos.mfa.plist failMode -string deny
sudo defaults write /Library/Preferences/com.rublon.macos.mfa.plist offlineAuth -bool false
sudo defaults write /Library/Preferences/com.rublon.macos.mfa.plist requestTimeoutMs -int 15000
sudo defaults write /Library/Preferences/com.rublon.macos.mfa.plist logLevel -int 2
To replace the System Token or Secret Key, run the command-line installation with --no-clean-reinstall and the new credentials read from protected files. Also pass your current policy and logging options, because omitted options are reset to their defaults. Clean installation in Setup also replaces the credentials, but it deletes remembered devices. Avoid placing credentials directly in a defaults write command because the command may be retained in shell history.
Delete a Value
Delete one optional runtime value by specifying its key:
sudo defaults delete /Library/Preferences/com.rublon.macos.mfa.plist requestTimeoutMs
Deleting an optional runtime value causes the connector to use its built-in fallback. Do not delete apiBaseURL, callbackURL, systemToken, secretKey, or preferencesSchemaVersion. Never run defaults delete without a key, because that would delete the complete connector configuration.
Restore Protection After Changes
A write or delete operation may cause macOS to replace the preferences file. After completing all changes, restore its ownership, permissions, and runtime ACL in this order:
sudo chown root:admin /Library/Preferences/com.rublon.macos.mfa.plist
sudo chmod -N /Library/Preferences/com.rublon.macos.mfa.plist
sudo chmod 660 /Library/Preferences/com.rublon.macos.mfa.plist
sudo chmod +a "_securityagent allow read,readattr,readextattr,readsecurity" /Library/Preferences/com.rublon.macos.mfa.plist
To check the result, run:
ls -le /Library/Preferences/com.rublon.macos.mfa.plist
The output must show root admin, the mode -rw-rw----+ and the entry user:_securityagent allow read,readattr,readextattr,readsecurity.
The local preferences file contains tenant credentials and is protected so standard local users cannot read it. Use sudo for administrative changes.
The installer applies the following access controls to the local preferences file:
| Account or context | Read | Modify connector settings |
root | Yes | Yes |
Local administrators (admin group) | Yes | Yes, using sudo |
Connector runtime (_securityagent) | Yes, through an explicit read-only ACL | No |
| Standard local users | No | No |
The file is owned by root:admin and uses permission mode 0660. An explicit ACL grants _securityagent read-only access so the connector can load its configuration while running in the macOS login context. Administrative changes should be made with sudo because the preferences are system-wide and may be rewritten atomically by macOS.
Policy Behavior
The two failure-policy settings cover different conditions:
| Rublon API state | Setting used | bypass / true | deny / false |
| Rublon API is reachable, but MFA cannot be performed | failMode | Allow login | Deny login |
| Rublon API cannot be reached | offlineAuth | Allow login | Deny login |
Examples of an unreachable service include DNS failure, no network connection, connection failure, and request timeout. API errors, invalid responses, missing user enrollment, and similar reachable-service failures are governed by failMode.
Warning
Setting failMode=deny and offlineAuth=false provides stricter enforcement but can lock users out if configuration, identity mapping, networking, or the Rublon MFA service is unavailable. Configure and test a recovery path first.
Sign in to macOS with Rublon MFA
This example depicts the process of signing in to macOS after Rublon MFA for macOS has been installed. This example shows how to sign in to a local machine.
1. Ensure the standard macOS login window is displayed by signing out or rebooting the Mac. On Macs with FileVault enabled, unlock the encrypted volume first.
2. Select your macOS account and enter the correct macOS password.
3. A Rublon Prompt appears with a selection of authentication methods.

4. Choose one of the authentication methods. Let’s choose Mobile Push.
5. You will be sent a push notification. Tap APPROVE.
6. After successful verification, macOS starts the desktop session.
Updating Rublon MFA for macOS
To update your Rublon MFA for macOS connector, download and install the new version on the machine where you have installed the old version before.
- Choose:
- Update current installation to reinstall the connector while keeping the current local settings and remembered devices; or
- Clean installation to delete the local preferences and remembered devices and configure the connector again. Every user completes MFA again at the next sign-in.
Note
When Setup detects an existing installation, it selects Clean installation by default.
Note
Every installation, including an update, sets enabled and rememberDeviceIPCheckEnabled to true and adds Rublon MFA to the login flow again.
For a command-line update that keeps remembered devices, run the current setup application with --no-clean-reinstall. Pass the System Token, the Secret Key, and every policy or logging value that differs from the default (--fail-mode, --offline-auth, --log-level, --debug-rublon-requests, --enable-sensitive-data-logging), because omitted options are reset to their defaults. To check the current values first, run, for example, sudo defaults read /Library/Preferences/com.rublon.macos.mfa.plist failMode.
Important
Before you update many Macs, update one Mac first and complete a test sign-in while an administrator session or another recovery path, such as SSH, stays available. The connector runs inside the macOS login window: if a new version fails to load, macOS can refuse every sign-in, and the bypass settings do not help, because the connector applies them itself.
If you install an update while the login window is displayed (for example remotely), the next sign-in may still use the previous connector version. Restart the Mac after the update to make sure the new version is active.
Temporarily Disable and Re-Enable Rublon MFA
The installer adds administrative helper scripts under:
/Library/Application Support/Rublon/Scripts/
To temporarily stop invoking Rublon MFA during console login while leaving the connector, preferences, and package receipt installed:
sudo "/Library/Application Support/Rublon/Scripts/disable-rublon.sh"
To enable it again:
sudo "/Library/Application Support/Rublon/Scripts/enable-rublon.sh"
Both operations back up the current macOS console login authorization chain before making a change. Running either helper more than once is safe. Any later installation or update adds Rublon MFA to the login flow again and sets enabled to true. To keep Rublon MFA disabled, run disable-rublon.sh again after the update.
Uninstalling Rublon MFA for macOS
To uninstall Rublon MFA, run:
sudo "/Library/Application Support/Rublon/Scripts/uninstall-rublon.sh"
The helper asks for confirmation. To uninstall without an interactive prompt, run:
sudo "/Library/Application Support/Rublon/Scripts/uninstall-rublon.sh" --yes
The uninstaller:
- removes the Rublon MFA mechanism from the local console login flow
- removes the connector bundle
- removes the local connector preferences
- removes the log-rotation service and installed helper scripts
- forgets the package receipt
- removes remembered-device data (Rublon Prompt website data)
- removes DisableFDEAutoLogin from com.apple.loginwindow if the installer set it and it is still true, so FileVault automatic login comes back
By default, the uninstaller keeps authorization-chain backups, connector runtime logs, and Setup logs for recovery and support. To remove them as well, add one or more of these options:
--remove-setup-logs— Setup and installer logs (/Library/Application Support/Rublon/Logs/, /private/tmp/rublonmfa-bootstrap-install.log, /private/tmp/rublonmfa-setup-<uid>.log)--remove-connector-logs— /private/var/tmp/RublonMFA.log and its archives--remove-backups— authorization-chain backups in /Library/Application Support/Rublon/Backups/--purge— all of the above
To preserve the DisableFDEAutoLogin setting (e.g., to keep the login window after unlocking FileVault), add --keep-disable-fde-auto-login:
sudo "/Library/Application Support/Rublon/Scripts/uninstall-rublon.sh" --yes --purge --keep-disable-fde-auto-login
Sign out or restart the Mac after uninstalling.
Logs and Support Diagnostics
Connector Runtime Log
The connector writes its runtime log to:
/private/var/tmp/RublonMFA.log
The installer rotates a non-empty active log every 24 hours or when it exceeds 4 MiB. Archives use UTC-timestamped names that include their logging-level retention class, for example:
/private/var/tmp/RublonMFA.log.20260904T120000Z.L1.123.0
At the Normal log level (logLevel=1), archives are retained for 90 days. At the Debug and Trace levels (logLevel=2 or 3), archives are retained for seven days. The retention class stored in each archive name prevents a later logging-level change from shortening the retention of existing Normal archives.
Installer Logs
The package installation log is normally written to:
/private/tmp/rublonmfa-bootstrap-install.log
Setup wrapper logs are moved, when installation reaches the package script, to:
/Library/Application Support/Rublon/Logs/
If Setup fails before the package script starts, an early wrapper log can remain under
/private/tmp/rublonmfa-setup-<uid>.log.
Create a Support Package
Run:
sudo "/Library/Application Support/Rublon/Scripts/collect-support-logs.sh"
By default, the helper creates a mode-0600 ZIP archive named RublonMFA-support-logs-<timestamp>.zip on the invoking user’s Desktop. If a Desktop directory is unavailable, it writes the archive to /Users/Shared.
The default support package includes public, redacted runtime records and sanitized connector, installer, preference, package, permission, and login-chain diagnostics.
The support package also records the FileVault state and DisableFDEAutoLogin.
Use the following option only when Rublon Support explicitly asks for sensitive diagnostics:
sudo "/Library/Application Support/Rublon/Scripts/collect-support-logs.sh" --include-sensitive
The resulting filename contains -SENSITIVE. Review and transfer it through an approved secure channel. The Secret Key is excluded in every mode.
Troubleshooting
The Rublon Prompt Does Not Appear
- Confirm that the connector is installed and enabled.
- Installed: Verify the bundle exists: ls /Library/Security/SecurityAgentPlugins/RublonMFA.bundle
- In the login flow: Confirm RublonMFA:authenticate is present in the console authorization database: sudo security authorizationdb read system.login.console | grep RublonMFA
- Enabled: Confirm that sudo defaults read /Library/Preferences/com.rublon.macos.mfa.plist enabled returns 1.
- Confirm that the correct architecture-specific package was used.
- Confirm that the System Token and Secret Key belong to the same macOS application defined in the Rublon Admin Console.
- Confirm that the protected macOS short username maps to the intended Rublon MFA user.
- Confirm outbound TCP port 443 access to the Rublon API.
- Review /private/var/tmp/RublonMFA.log.
- Create a support package if the cause is not clear.
Sign-in is Allowed Without MFA
Check the following settings:
- enabled — when false, the connector allows sign-ins without starting MFA.
- failMode — bypass allows login when the Rublon API is reachable, but MFA cannot be performed.
- offlineAuth — true allows login when the Rublon API is unreachable.
Also check whether the Rublon MFA user or policy is configured for bypass or whether a Remembered Devices policy applies.
If MFA is skipped on the first sign-in after restarting a Mac with FileVault, check whether FileVault automatic login is enabled. It is on if the following command returns 0 or reports that the key does not exist, or if a configuration profile sets DisableFDEAutoLogin to false:
defaults read /Library/Preferences/com.apple.loginwindow DisableFDEAutoLogin
Because automatic login typically executes before the network connection is established, the sign-in outcome is governed by the offlineAuth setting.
Users Are Denied When the Network is Unavailable
Set Bypass MFA when the API server is unreachable to enabled, or set the offlineAuth preference to true. This bypasses MFA during the outage; it does not perform offline mode authentication.
The Wrong Rublon MFA User is Matched
The connector sends the short local macOS account name. Verify the account’s short name and configure the correct Rublon MFA identity alias in the Rublon Admin Console. The username format cannot be changed in the installer.
The Setup Application Reports an Existing or Inconsistent Installation
Choose Update current installation when you want to keep the current local configuration. Choose Clean installation when you need to replace local credentials or recover from inconsistent local preference state.
A Strict Policy Has Locked Users Out
Use an existing administrator session or your approved remote-management path to run:
sudo "/Library/Application Support/Rublon/Scripts/disable-rublon.sh"
Correct the credentials, identity mapping, network policy, or Rublon MFA policy, then run enable-rublon.sh and test a new login.
Users Must Complete MFA Again After an Update
A clean installation deletes remembered devices. Choose Update current installation to keep them. A remembered device is also revoked when the Mac’s public IP address changes (rememberDeviceIPCheckEnabled).
Sign-In Takes About 20 Seconds and Completes Without MFA
The connector could not reach the Rublon API within requestTimeoutMs, and offlineAuth=true allowed the sign-in. Check network access to the Rublon API. To deny sign-in in this situation, set offlineAuth to false.
I have a different issue
If the issue persists:
- Create the default redacted support package.
- Record the connector version, Mac model, processor architecture, and macOS version.
- Record the approximate time and username of the failed login attempt. Do not send the account password or Secret Key.
- Contact Rublon Support.