Preparation Before Installation

• Verify macOS version compatibility (Sequoia, Sonoma, Ventura).
• Ensure Octopus Authentication Server v6.4.2+ with valid enterprise certificate.
• Confirm Active Directory integration and Kerberos configuration.
• Place octopus-desk.pkg and octopus-desk.xml in the same folder with identical names.
• Grant Full Disk Access and Accessibility permissions for Octopus components.

Troubleshooting Checklist  

Advanced Logging & Event Codes

Advanced Logging & Event Codes

If logs cannot be downloaded from the Octopus Preferences dialog, check /var/log for files starting with octopus*.log:

• octopus-audit.log (authentication events)
• octopus-log.log (general logs)

Common Event Codes:

• 5021 = Logon successful
• 5022 = Logon failed
• 5153 = FIDO setup failed
• 5413 = Offline authentication failed
  
  
• Verify prerequisites:
  • macOS version (Sequoia, Sonoma, Ventura).
  • Octopus Authentication Server v6.4.2+ with valid enterprise certificate.
  • Active Directory integration completed.
  • XML configuration file correctly paired with the installer (octopus-desk.pkg and octopus-desk.xml in the same folder, same name).
• Check logs:
  • If logs cannot be downloaded via the Octopus Preferences dialog, inspect files under /var/log:
    • octopus-audit.log (authentication events).
    • octopus-log.log (general logs).
    • Both files support detailed event codes for tracing issues.
• Permissions:
  • Ensure Full Disk Access for OctopusHelper and Accessibility permissions for Octopus.app (especially on older macOS versions like Monterey).

? Common Installation Issues & Fixes

1. Installer Fails to Launch

• Possible Causes:
  • Missing admin rights.
  • macOS Gatekeeper blocking unsigned apps.
• Fix:
  • Run octopus-desk.pkg as Administrator.
  • If blocked, go to System Preferences → Security & Privacy → Allow app.

2. Installation Completes but Octopus Icon Missing

• Possible Causes:
  • XML file misconfigured or missing mandatory parameters (server, domain, service, certificate).
• Fix:
  • Validate XML file syntax and mandatory fields.
  • Ensure both files are in the same folder and share the same name.

3. Active Directory Users Cannot Authenticate

• Possible Causes:
  • Mac not joined to AD.
  • Incorrect domain or kerberosrealm in XML.
• Fix:
  • Join Mac to AD: System Preferences → Users & Groups → Login Options → Network Account Server → Join.
  • Verify Kerberos ticket status in Octopus Preferences.

4. Local Users Cannot Authenticate

• Possible Causes:
  • Onboarding not completed.
  • Authentication methods missing in XML.
• Fix:
  • Use Welcome dialog → Enable Octopus Desk for Mac → Select Authentication Method.
  • Ensure authenticationMethods element includes Octopus Authenticator, FIDO, OTP if needed.

5. FileVault Login Issues

• Scenarios:
  • Server-managed password: Ensure filevaultlogin parameter = server.
  • Client-managed password: Ensure user sets password manually.
• Fix:
  • If uninstalling, disable FileVault first via Octopus Preferences → FileVault → Disable.
  • If password rotation fails, check Octopus Management Console for FileVault settings.

6. Password Sync Failures

• Possible Causes:
  • Jamf policy conflicts.
  • Multiple user accounts switching.
• Fix:
  • Disable Jamf password policies temporarily.
  • Lock/unlock machine to trigger sync.
  • Check autoPasswordSync and forcePasswordRotation parameters in XML.

7. Kerberos Ticket Not Renewing

• Possible Causes:
  • automatickerberossync set to false.
• Fix:
  • Renew manually via Octopus Preferences → Kerberos menu.
  • Ensure kerberosrealm parameter is correctly set.

8. SSO Portal Not Launching

• Possible Causes:
  • ssourl parameter missing or invalid.
• Fix:
  • Add valid URL in XML: <ssourl>https://sso.example.com/webportal</ssourl>.

9. Touch ID Not Working

• Possible Causes:
  • customUnlockScreen enabled (Touch ID unsupported).
• Fix:
  • Disable customUnlockScreen if Touch ID is required.

10. Shared Account Login Issues

• Possible Causes:
  • sharedaccounts or customUnlockScreen not set to true.
• Fix:
  • Enable both parameters in XML.
  • Configure account sharing in Octopus Management Console.

? Advanced Debugging

• Event Codes:
  • 5021 = Logon successful.
  • 5022 = Logon failed.
  • 5153 = FIDO setup failed.
  • 5413 = Offline authentication failed.
• Use these codes in /var/log/octopus-audit.log for root cause analysis.