Manage The Contacts Service In macOS Server 5.4 High Sierra

Every Mac by default has an application called Contacts. Every macOS Server 5.4, running on High Sierra, has a service called Contacts. While the names might imply very different things that they do, you’ll be super-surprised that the two are designed to work with one another. The Contacts service is based on CardDAV, a protocol for storing contact information on the web, retrievable and digestible by client computers. However, there is a layer of database-driven obfuscation between the Contacts service and CardDAV. The Contacts service is also a conduit with which to read information from LDAP and display that information in the Contacts client, which is in a way similar to how the Global Address List (GAL) works in Microsoft Exchange.

I know I’ve said this about other services in macOS Server, but the Contacts service couldn’t be easier to configure. First, you should be running Open Directory and you should also have configured Apple Push Notifications. To setup Push Notifications, have an Apple ID handy and click on the Contacts entry in the SERVICES section of Server app.

Click the Edit Notifications button to configure the Apple Push Notification settings for the computer. When prompted, click on Enable Notifications.

If prompted, provide the username and password for the Apple ID and then click on Finish. To enable the Contacts service, open the Server app and then click on Contacts in the SERVICES section of the List Pane. From here, use the “Include directory contacts in search” checkbox to publish LDAP contacts through the service, or leave this option unchecked and click on the ON button to enable the service.

The Contacts service then starts and once complete, a green light appears beside the Contacts entry in the List Pane. To configure a client open the Contacts application on a client computer and use the Preferences entry in the Contacts menu to bring up the Preferences screen. From here, click the Accounts menu and then click on Add Accounts.

At the Add Account screen, scroll down and click Add Other Account… to bring up an expanded menu of account types. Click “CardDAV account”.

At the “Add a Contacts Account” screen, enter the email address and password of the user. Auto discovery doesn’t always work, so you might end up using the manual button to add the account using the server’s address. Alternatively, if you’ve mapped CardDAV to custom ports, you may use the advanced option to have paths and ports available.

When the account is finished creating, you can click on the account again to see the settings used. Otherwise, close the Preferences/Accounts screen and then view the list of Contacts. Click on View and then Show Groups. This will show you the name of the servers that you’re connected to in the sidebar. There won’t be any contacts yet, so click on the plus sign to verify you have write access to the server.
 
Next, let’s get access to the LDAP-based contacts. To do so, bring up the Add Account screen again and this time select LDAP Account from the Account Type field.

Provide the name or IP address of the server and then the port that LDAP contacts are available over (the defaults, 389 and 636 with SSL are more than likely the settings that you’ll use. Then click on the Continue button.

At the Account Settings screen, provide the name that will appear in the Contacts app for the account in the Description field and then enter the search base in the Search base field. To determine the search base, use the serveradmin command. The following command will output the search base:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings dirserv:LDAPSettings:LDAPSearchBase

Then set Authentication to simple and provide the username and password to access the server for the account you are configuring. The list then appears.

The default port for the Contacts service is 8443, as seen earlier in the configuration of the client. To customize the port, use the serveradmin command to set addressbook settings for BindSSLPorts to edit the initial array entry, as follows:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings addressbook:SSLPort = 8443

The default location for the files used by the Contacts service is in the /Library/Server/Calendar and Contacts directory. To change that to a folder called /Volumes/Pegasys/CardDAV, use the following command:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings addressbook:ServerRoot = "/Volumes/Pegasys/CardDAV"

When changing the ServerRoot, you’ll likely need to change the DataRoot, which is usually the Data directory immediately underneath the ServerRoot. To do so, run serveradmin and put the DataRoot entry under the addressbook settings:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings addressbook:DataRoot = "/Volumes/Pegasys/CardDAV/Data"

The service is then stopped with the serveradmin command:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin stop addressbook

And started with the serveradmin command:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin start addressbook

And whether the service is running, along with the paths to the logs can be obtained using the fullstatus command with serveradmin:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin fullstatus addressbook

The output of which should be as follows:

status addressbook
addressbook:state = “RUNNING”
addressbook:setStateVersion = 1
addressbook:readWriteSettingsVersion = 1

If you’re easily amused, run the serveradmin settings for calendar and compare them to the serveradmin settings for addressbook:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings calendar

By default, the Contacts server allows basic authentication. We’ll just turn that off real quick:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings addressbook:Authentication:Basic:Enabled = no

And then let’s see what it is in addressbook:

/Applications/Server.app/Contents/ServerRoot/usr/sbin/serveradmin settings addressbook:Authentication:Basic:Enabled

Configure The Contacts Service In Mavericks Server

Mavericks has an application called Contacts. Mavericks Server (OS X Server 3) has a service called Contacts. While the names might imply differently, surprisingly the two are designed to work with one another. The Contacts service is based on CardDAV, a protocol for storing contact information on the web, retrievable and digestible by client computers. However, there is a layer of Postgres-based obfuscation between the Contacts service and CalDAV. The Contacts service is also a conduit with which to read information from LDAP and display that information in the Contacts client, which is in a way similar to how the Global Address List (GAL) works in Microsoft Exchange. I know I’ve said this about other services in OS X Server, but the Contacts service couldn’t be easier to configure. First, you should be running Open Directory and you should also have configured Apple Push Notifications. To setup Push Notifications, have an Apple ID handy and click on the Contacts entry in the SERVICES section of Server app. Screen Shot 2013-10-05 at 10.30.27 PMClick the Edit button to configure the Apple Push Notification settings for the computer. When prompted, click on Enable Push Notifications. Screen Shot 2013-10-05 at 10.31.08 PMIf prompted, provide the username and password for the Apple ID and then click on Finish. To enable the Contacts service, open the Server app and then click on Contacts in the SERVICES section of the List Pane. From here, use the “Include directory contacts in search” checkbox to publish LDAP contacts through the service, or leave this option unchecked and click on the ON button to enable the service. Screen Shot 2013-10-05 at 11.03.35 PMThe Contacts service then starts and once complete, a green light appears beside the Contacts entry in the List Pane. To configure a client open the Contacts application on a client computer and use the Preferences entry in the Contacts menu to bring up the Preferences screen. From here, click the Accounts menu and then click on Add Accounts. Screen Shot 2013-10-05 at 10.49.18 PMAt the Add Account screen, click Other contacts account. Screen Shot 2013-10-05 at 11.05.03 PMAt the “Add a CardDAV Account” screen, select CardDAV from the Account type field and then provide a valid username from the users configured in Server app as well as the password for that user and the name or IP address of the server. Then click on the Create button. Screen Shot 2013-10-05 at 11.08.23 PMWhen the account is finished creating click on the Server Settings tab if a custom port is required. Otherwise, close the Preferences/Accounts screen and then view the list of Contacts. Click on the name of the server in the Contacts sidebar list. There won’t be any contacts yet, so click on the plus sign to verify you have write access to the server. Next, let’s get access to the LDAP-based contacts. To do so, bring up the Add Account screen again and this time select LDAP from the Account Type field. Screen Shot 2013-10-05 at 11.13.03 PM Provide the name or IP address of the server and then the port that LDAP contacts are available over (the defaults, 389 and 636 with SSL are more than likely the settings that you’ll use. Then click on the Continue button. Screen Shot 2013-10-05 at 11.13.43 PM At the Account Settings screen, provide the name that will appear in the Contacts app for the account in the Description field and then enter the search base in the Search base field. To determine the search base, use the serveradmin command. The following command will output the search base: sudo serveradmin settings dirserv:LDAPSettings:LDAPSearchBase Then set Authentication to simple and provide the username and password to access the server for the account you are configuring. The list then appears. The default port for the Contacts service is 8443, as seen earlier in the configuration of the client. To customize the port, use the serveradmin command to set addressbook settings for BindSSLPorts to edit the initial array entry, as follows: sudo serveradmin settings addressbook:BindSSLPorts:_array_index:0 = 8443 The default location for the files used by the Contacts service is in the /Library/Server/Calendar and Contacts directory. To change that to a folder called /Volumes/Pegasys/CardDAV, use the following command: sudo serveradmin settings addressbook:ServerRoot = "/Volumes/Pegasys/CardDAV" The service is then stopped with the serveradmin command: sudo serveradmin stop addressbook And started with the serveradmin command: sudo serveradmin start addressbook And whether the service is running, along with the paths to the logs can be obtained using the fullstatus command with serveradmin: sudo serveradmin fullstatus addressbook The output of which should be as follows: addressbook:setStateVersion = 1 addressbook:logPaths:LogFile = "/var/log/caldavd/access.log" addressbook:logPaths:ErrorLog = "/var/log/caldavd/error.log" addressbook:state = "RUNNING" addressbook:servicePortsAreRestricted = "NO" addressbook:servicePortsRestrictionInfo = _empty_array addressbook:readWriteSettingsVersion = 1 If you’re easily amused, run the serveradmin settings for calendar and compare them to the serveradmin settings for addressbook: sudo serveradmin settings calendar By default, the addressbook:MaxAllowedInstances is 3000. Let’s change it for calendar: sudo serveradmin serveradmin settings calendar:MaxAllowedInstances = 3001 And then let’s see what it is in addressbook: serveradmin settings addressbook:MaxAllowedInstances

Address Book Server "Groups"

I use the term “groups” loosely here. On my list of features that are needed in Lion Server (a much smaller since the advent of 10.7.3 btw) is the fact that Address Book Server doesn’t have groups, resources or whatever you want to call a logical structure that is a place for groups of users to keep contacts whose access can be limited to only certain users. The Address Book client fully understands such constructs, given that it separates the GAL from a user’s contacts and that user’s can themselves have groups of contacts. This area is a huge miss. The reason this annoys me is that you have the ability to do this stuff with iCal Server, which uses roughly the same technology (Twisted CalDAV vs. CardDAV). You can include LDAP contacts in an Address Book search, which just gives users access to users configured on the local server. Helpful if your user base is a walled garden. And don’t tell me that it kinda’ works the same in Exchange. Because a contact is not a user in Exchange… Anyway, one way to get a shared list of contacts is to create a user just to be the shared list. This user is going to have a password. That password is going to end up in the keychain for all users who we install this account for. Furthermore, all of those users can delete contacts. And those users will invariably delete an account and blame said deletion on the server. Given that servers don’t delete data on their own, the blame is basically poorly placed. If you need granular permissions control over shared contact lists, then Address Book server is not for you. But if you just need a “group” or two that is wide open permission-wise for all users, then consider this strategy. First, let’s enable Address Book services. To do so, first open the Server application from an Open Directory Master. Then, click on the Address Book entry in the Server application’s sidebar. Here, click on the ON button (by the way, I could have just used this paragraph as an article on Setting Up Address Book Server).  Now that the service is started, click on Users. Then click on New User. At the New User screen, let’s pick an arbitrary name that someone who gets access to this computer won’t think anything of, should they notice this account. Once created, to make sure that the user has access to the Address Book service. To do so, click on the account and then select Edit Access to Services… from the cog wheel icon and verify that the Address Book service is enabled for the user. Now, let’s check out how this looks on a client. These accounts can be deployed through profiles easily. But we like doing things the hard way. Therefore, let’s open the nifty Mail, Contacts & Calendars System Preference pane and then click on the Add Account… button. From the Choose an account type  field, click on the Add a CardDAV account button. Click on the Create… button. Provide the username and password recently created, as well as the name or IP of the server. Now open Address Book. Click on the red bookmark icon. You’ll then see your contact stash. Click on it and you can create, delete and otherwise do whatever you like here. If you create contacts and install this account on multiple machines then you’ll be able to edit or delete them from any of the stations they’re installed on. You can install the accounts on iOS devices as well, using the Mail, Contacts & Calendars option in the Settings app. Good luck. And may Billy Madison have mercy on your Address Book.

Snow Leopard & Directory.app

If you grew accustomed to using Directory.app in Leopard and you’re thinking about an upgrade to Snow Leopard then you might want to pause, if only for a moment. You see, there is no Directory.app in Snow Leopard. If you were using Directory.app to allow users to create Blogs and Wikis, then check out the new web interface and see if the specific functionality you seek is there; otherwise look into SACLs and consider pushing out Workgroup Manager. If you were using it to hook into LDAP and allow for looking up contact information then check out Address Book Server, included in 10.6 Server…