The Foxpass Developer Hub

Welcome to the Foxpass developer hub. You'll find comprehensive guides and documentation to help you start working with Foxpass as quickly as possible, as well as support if you get stuck.

Get Started    API Reference

Mac OS X logins over LDAP

How to get network-based logins working on Mac OSX with Foxpass

📘

Note: each user that logs into a Mac OS X machine must be enabled as an Engineering UserEngineering User - A user that manages their SSH keys in Foxpass. Engineering users also gain access to POSIX based machines (e.g. CentOS). or Posix UserPosix User - A user needs access to POSIX based machines (e.g. CentOS). in Foxpass

1. Foxpass setup

  1. Note your Base DN on the dashboard page. Copy/paste it somewhere.
  2. Create an LDAP Binder account with the name 'osx' on the LDAP binders page. Copy/paste the generated password! It is only displayed once.

2. Enable Network Account server

Open System Preferences
Open Users & Groups
Click the lock to make changes
Click Login Options
Click "Join..." next to Network Account Server

3. Set up LDAP configuration

Click "Open Directory Utility..."
Click the lock to make changes
Choose LDAPv3
Click the tiny pencil icon
Click New...
Server Name or IP Address: ldap.foxpass.com
tick "Encrypt using SSL"
tick "Use for authentication"
tick "Use for contacts"
Click Manual
Set configuration name to "Foxpass"

4. Set up LDAP Mappings

LDAP Mappings should say "Custom"
Click "Edit..."

If you have MFA on, you might want to increase your "Open/Close times out in" value up from 10 seconds. 60 seconds should give your users enough time to respond to the MFA prompt.

Under "Connection":
Use custom port: 636

Under "Search & Mappings":
Click the '+' under "Record Types and Attributes"
Choose "users"
Drop down the arrow for "Users"
Highlight "Users"
Click the '+' and choose each of the following:

  • GeneratedUID
  • HomeDirectory
  • NFSHomeDirectory
  • PrimaryGroupID
  • RealName
  • RecordName
  • UniqueID
  • UserShell

Map each to the following in the right-side:

  • Users: posixAccount
  • GeneratedUID: apple-generateduid
  • HomeDirectory: #/Users/Shared
  • NFSHomeDirectory: #/Users/Shared (NOTE: This is necessary even if you’re not using NFS)
  • PrimaryGroupID: #20
  • RealName: cn
  • RecordName: uid
  • UniqueID: uidNumber
  • UserShell: #/bin/bash

Highlight "Users"
For "Search base" enter "ou=people,dc=example,dc=com" (replace with your domain)

Click the '+' under "Record Types and Attributes"
Choose "Groups"
Drop down the arrow for "Groups"
Highlight "Groups"
Click the '+' and choose each of the following:

  • GroupMembership
  • Member
  • PrimaryGroupID
  • RecordName

Map each to the following in the right-side:

  • Groups: posixGroup
  • GroupMembership: memberUid
  • Member: memberUid
  • PrimaryGroupID: gidNumber
  • RecordName: cn

Highlight "Groups"
For "Search base" enter "ou=groups,dc=example,dc=com" (replace with your domain)

Under "Security"
Tick "Use authentication when connecting"
Distinguished Name: "cn=osx,dc=example,dc=com"
Password:

Click OK
Click OK

5. Set up search policy

Click "Search Policy"
Switch "Automatic" to "Custom path"
Click '+'
Select "/LDAPv3/ldap.foxpass.com"
Click Add
Click Apply
Close the window

6. Let them log in

Tick 'Allow network users to log in at login window'

7. Caveats

Right now, all users share a common home directory (/Users/Shared). To have individual home directories, it becomes a lot more complicated.

In the LDAP mappings, make these changes:

  • HomeDirectory: #/Users/$uid$
  • NFSHomeDirectory: #/Users/$uid$ (NOTE: This is necessary even if you’re not using NFS)

In terminal, enter these commands:

sudo mkdir -p /Library/Management/
curl https://raw.githubusercontent.com/foxpass/foxpass-setup/master/macosx/elcapitan/FoxpassLoginHook.bash > FoxpassLoginHook.bash
sudo mv FoxpassLoginHook.bash /Library/Management/FoxpassLoginHook.bash
sudo chown root:wheel /Library/Management/FoxpassLoginHook.bash
sudo chmod 755 /Library/Management/FoxpassLoginHook.bash

And add the script as a login hook
(Note: you are only allowed one LoginHook. If you already have one, then have your existing hook call ours)

sudo defaults write com.apple.loginwindow LoginHook /Library/Management/FoxpassLoginHook.bash

8. Debug

Here are some handy debug commands

flush the cache:
dscacheutil -flushcache

look up a user
dscacheutil -q user -a name

9. Rollout

Rollout procedure varies, but here are some ways our customers have done it:

Follow instructions in steps 1 through 5, above. This will create the plist files needed.
Copy plist files from the following two locations. These files can be deployed to other macOS workstations.

/Library/Preferences/OpenDirectory/Configurations/LDAPv3/Foxpass.plist
/Library/Preferences/OpenDirectory/Configurations/Search.plist

The bind username and password set in the "Security -> Use authentication when connecting" step is stored in the macOS System Keychain.

To insert this into the System Keychain via command line on a new system use the following command.

sudo /usr/bin/security add-generic-password -a "cn=yourBindAccount,dc=yourDomainHere,dc=com" -w "yourPassword" -s "/LDAPv3/Foxpass" -l "/LDAPv3/Foxpass" -A /Library/Keychains/System.keychain

Be sure to restart opendirectoryd (or restart MacOS), otherwise the new config will not be visible in MacOS Directory Utility.

sudo /bin/launchctl stop com.apple.opendirectoryd

Updated about a year ago

Mac OS X logins over LDAP


How to get network-based logins working on Mac OSX with Foxpass

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.