DocMoto
Server

Using Open Directory to authenticate access to DocMoto

Introduction

These instructions assume that you have already setup a Mac Server supporting Open Directory and Kerberos.

Granting trust between DocMoto and Open Directory is not trivial but the following notes should help. In the event of problems please contact CHL Software.

When running Server Admin on that server it is essential that Open Directory and Kerberos are running

In this example the Open Directory server will be referred to by its short name ODMaster (or its full name ODMaster.chlsoftware.com).

Every user wishing to connect to DocMoto via Open Directory will require their own account on this server. These are setup using WorkGroup manager.

In addition to this server you will need to install DocMotoServer on a dedicated computer and DocMotoClient on each computer you wish to access DocMoto through. These notes assume the DocMotoServer is a computer called DMServer.chlsoftware.com. You should replace this name with the name of your own computer in the notes that follow.

For the purposes of these notes it is assumed that these three layers are running on separate computers (or as virtual machines) though it is possible that a single computer shares any two (or all three) roles.

Only the ODMaster requires MacOS X Server, though the DocMoto server and client require Lion and above.

Overview

The ODMaster and DocMotoServer require configuring to permit Open Directory access:

1. Add a principal on ODMaster for host/DocMotoServer
2. Set the default realm on DocMotoServer to ODMaster
3. Copy the keytab entry from ODMaster to DocMotoServer
4. Before connecting to DocMoto
5. You will need to add the new user to the appropriate group in DocMoto.
   
   You can test by
6. Logging into your network as an Open Directory user
7. Then adding a server and connection on a DocMotoClient

Details

3.1 Add a principal

In a command window on ODMaster..

kadmin
addprinc -randkey host/DMServer.chlsoftware.com
ktadd host/DMServer.chlsoftware.com

3.2 Set the default realm

In a command window on DMServer, using your favourite editor (eg vi)
NB: Realms in Kerberos/Open Directory should be capitalised

sudo vi /Library/Preferences/edu.mit.Kerberos

a) Remove the Warning and two lines

b) Edit [libdefaults]

default_realm = ODMASTER.CHLSOFTWARE.COM

c) Edit [realms]

ODMASTER.CHLSOFTWARE.COM = {
kdc = odmaster.chlsoftware.com
admin_server = odmaster.chlsoftware.com
}

d) Edit [domain_realm]

.chlsoftware.com = ODMASTER.CHLSOFTWARE.COM
chlsoftware.com = ODMASTER.CHLSOFTWARE.COM

A complete file should look something like”¦

At the same time you are recommended to map the ip address in the hosts file

sudo vi /etc/hosts

add a line of the format ip fully-qualified-name short-name eg

192.168.2.115 ODMaster.chlsoftware.com ODMaster

3.3 Copy the keytab file from /etc on ODServer to DMServer

(This is not easily achieved purely in (eg) file manager”¦ you may find it easier in command windows.)

On OMServer

sudo tar cvf ~/krb5.keytab.tar /etc/krb5.keytab

On DMServer

Map to OMServer; copy krb5.keytab.tar to your home directory

sudo su
cd /etc
cp krb5.keytab krb5.keytab.bak
tar xvf ~/krm5.keytab.tar

3.4 Adding the user

Start a DocMoto client session and connect to DMServer with an admin user (the first time you do this you won't have any Open Directory users and you'll need to login to a user with a password normally "administrator").

Admin menu: Option Users and Groups: select a group and click Add User

The default Authentication ("Either") allows the Login account to be used outside Open Directory by specifying a password”¦

If you only wish to allow the user to login via Open Directory then chose "Open Directory Only".

Every DocMoto allows a mixed set of authentication”¦ even if all your users login via Open Directory you are strongly recommended to have an Administrator account which will work even if the Open Directory Server is down (though this may just be a account with "Either" authentication)

3.5 Login to Your Network

One of the advantages of Open Directory is that it allows single sign-on. The user and password entered at login can be used to authenticate access to DocMoto

Before logging into the Network it will be necessary to set the Login Options and Network Account Server (this is normal Open Directory usage)

3.6 Connect To DocMoto

Add a server”¦ and simply press connect (the authentication is assumed to be Open Directory as you haven't entered a Login Name or Password)

NB: Depending on the network the server may be known as DMServer.local

Others

1. Log onto computer locally

   DocMoto allows you to connect via Open Directory even if you have logged in to your computer locally. In this case it will request your Kerberos account and password before logging you into DocMoto.

   If you subsequently wish to log in as a different user you can terminate the Open Directory session. Restarting your PC will do it or you may find it easier through the command window using

   kdestroy

2. Bulk User Import

   It is possible to extract user details (id, name, etc) from the Open Directory Database and DocMoto will import a suitably formatted comma-separated values (CSV) file. We can supply scripts to be used as the basis for automating this. These scripts can add all users or can recognise the changes since the last extract and suggest new users to be added or existing users to be amended or deleted.

Testing

In case of problems the first thing to do is to go over these steps.

If you are unable to connect to Open Directory then the problem is outside DocMoto and you should refer to your System Administrator.

We can supply a pair of test applications which test Open Directory authentication outside DocMoto and can suggest where the problem lies.

There is a DocMotoClient preference setting for the Principal. This should normally be left unset but you may try

host/ODMASTER.CHLSOFTWARE.COM (again entering your own domain)