Howtos/AD Integration
Scalix Wiki -> How-Tos -> Active Directory Integration
Contents
Extending the Schema
The schema is what describes the attributes that Active Directory can use. It contains information such as attribute name, attribute size or length, data type, and relationship to other attributes. The schema must be extended to also include Scalix attributes such as mailnode, account type (premium or standard), and so on.
Extending the Schema is documented in the Scalix Setup and Configuration Guide, Integrating with Active Directory, Installing the Schema Extensions.
Extending the GUI
The GUI is the user interface used to administer users in Active Directory. It is called "Active Directory Users and Computers," or ADUC. After the GUI is extended, you will have two new tabs in the User Properties or Group Properties window, where you can add or modify Scalix attributes.
Extending the Schema is documented in the Scalix Setup and Configuration Guide, Integrating with Active Directory, Installing the GUI Extensions.
When you get to step 2 on page 85, it says
Launch the Microsoft Management Console and using the Add/Remove Snap-in feature, add the Scalix Management Console snap-in.
But it does not say HOW to do this.
Once the extensions are installed, you will have some new files in C:\ProgramFiles\Scalix\Administration. One of these is ScalixForestPrep.exe which you ran as part of installing the schema extension. One of them is AdminMMC.dll.
Run
regsvr32 C:\Program Files\Scalix\Administration\AdminMMC.dll
Then
Start -> Run -> MMC
Now you can see the Scalix Mgt Console in the list of available snap-ins. Add the snap-in and save it wherever you like. Use the Scalix Management snap-in to identify the domains and mailnodes in your organization. Then when you use ADUC you will have drop-down lists of mailnodes and domains from which to choose.
Updating Existing Entries
Generally speaking, if you have made the decision to integrate Scalix with Active Directory, you already have Active Directory installed and you are already administering user and group records in AD. The existing AD entries must be modified so that Scalix will import them and have the necessary data to administer the Scalix accounts. The section #Updating Active Directory Entries explains how to do this.
Frequently, you will have Scalix in full production and you'll need to modify the Scalix user data so that Scalix knows the user entries are "owned" by Active Directory. The section #Updating Scalix Entries will explain how to do this.
Updating Active Directory Entries
There are three Scalix attributes which must be populated in order for Scalix to be able to import and use the record. These attributes are scalixScalixObject, scalixMailnode, and scalixMailboxClass.
- scalixAdministrator - set to 'TRUE' if the user will have administration privileges on the Scalix server.
- scalixHideUserEntry - set to 'TRUE' if the user's information will be hidden from the email clients' address books.
- scalixLimitMailboxSize - set to the maximum size, in MB, that the user account can be.
- scalixLimitOutboundMail - set to 'TRUE' if the user will not be allowed to send messages when over quota.
- scalixLimitInboundMail - set to 'TRUE' if the user will not be allowed to receive new messages when over quota.
- scalixLimitNotifyUser - set to 'TRUE' if the system should send the user an email letting him know when he's over quota.
- scalixMailboxAdministrator - set to 'TRUE' if the user will have mailbox administration privileges on the Scalix server.
- scalixMailboxClass - set to 'FULL' for a premium account or 'LIMITED' for a standard account.
- scalixMailnode - the mailnode with which the account will be associated. Usually this is the default mailnode (run 'omshowmn' on the Scalix server; default mailnode will have two asterisks beside it).
- scalixScalixObject - set to TRUE if the entry is to be imported into Scalix. You can set this to TRUE by modifying the contents of the AD entry, or by right-clicking the user name and then "Create Scalix Mailbox," or by checking the box "Create Scalix Mailbox" when you're first creating an ADUC user or group.
- scalixServerLanguage - defaults to 'C' but can be set to other values.
Updating AD Entries Manually
If you have only a few entries in Active Directory that correspond to Scalix accounts (either already created or to be created via omldapsync) you can edit the entries manually. Simply go into ADUC, right-click the user's name, select "Create Scalix Mailbox" and enter the relevant data in the wizard. The act of creating a Scalix mailbox will set scalixSalixObject to TRUE. The only other attributes you have to fill in are mailnode and mailbox class.
Updating AD Entries with a Script
If you have several hundred entries, you will find it more convenient to script the changes. Below is a sample script but it is provided simply as a guideline. It is not warranted in any way. It is meant to be saved and run on the AD domain controller. Use at your own risk.
ModUsers.swf:
<job>
<script language="VBScript">
Option Explicit
On Error Resume Next
Dim objConn, objComm, objRS, objUser
Dim strBase, strFilter, strAttrs, strScope
strBase = "<LDAP://dc=mydomain,dc=net>;"
strFilter = "(&(objectclass=user)(objectcategory=person));"
strAttrs = "ADsPath;"
strScope = "Subtree"
Set objConn = CreateObject("ADODB.Connection")
objConn.Provider = "ADsDSOObject"
objConn.Open
Set objComm = CreateObject("ADODB.Command")
Set objComm.ActiveConnection = objConn
objComm.CommandText = strBase & strFilter & strAttrs & strScope
objComm.Properties("Page Size") = 1000
Set objRS = objComm.Execute()
While not objRS.EOF
Set objUser = GetObject( objRS.Fields.Item("ADsPath").Value )
objUser.scalixScalixObject = "TRUE"
objUser.scalixMailboxClass = "FULL"
objuser.scalixMailnode = "sxlab"
objUser.SetInfo
if Err.Number <> 0 Then
Wscript.Echo objUser.Name & " error occurred"
Err.Clear
Else
Wscript.Echo objUser.Name & " modified"
End if
objRS.MoveNext
Wend
</script>
</job>
The above will turn all AD users in to Scalix users so you'll need to go back and manually undo some of the ADUC users like ISUR_EXLAB and IWAM_EXLAB. Or perhaps modify the script so it doesn't affect ADUC users with a description containing the string "Built-in account".
Updating Scalix Entries
Scalix user accounts that have already been created via SAC, but which you now want to administer from AD, need to be modified so that their Global-Unique-ID matches the objectGUID in Active Directory. You can do this via any method you like; below are a command to retrieve the users and their objectGUID values from AD, and then an awk script to build a series of ommodent commands for each of those users.
First, get a list of all Scalix users from Active Directory, along with their objectGUID values, in LDIF format:
# omldapsearch -D "cn=Administrator,cn=Users,dc=mydomain,dc=net" -w secret -h adhost.mydomain.net -b dc=mydomain,dc=net scalixScalixObject=TRUE -L "" cn objectGUID > /file.ldif
You will, of course, need to modify that command to reflect your own domain, AD user and password, search base, etc.
The following awk script will help you build a series of commands to modify the global-unique-id of all your Scalix users so they match the AD objectGUID. This isn't anything officially developed and supported by Scalix, it's just here as a convenience and to give you one way to do it. You have to change two entries: the default SYSTEM directory, which is used by many email clients as the "address book", and the hidden USERLIST directory which is vaguely similar to /etc/passwd in that it contains information about the user's account location, etc.
# changeuid.awk
# Used to change Scalix global-unique-id to same value as Active Directory
# objectGUID. Requires ldif input that contains at least cn and objectGUID
# values
# usage: awk -f changeuid.awk file.ldif | sed -e 's/cn= \" /cn=\"/; s/id=" /id="/g' > /tmp/update
BEGIN { FS = ":" }
/^cn:/ {
name=$2
next
}
/^objectGUID:/ {
UID=$3
if ( name != "" && UID != "" ) {
printf "ommodent -e cn= \"%s\" -n global-unique-id=\"%s\"\n", name, UID
printf "ommodent -e cn= \"%s\" -n global-unique-id=\"%s\" -d userlist -t h\n", name, UID
name=""
UID=""
}
}
After running the above script, you'll still need to edit the output file a bit. You'll need to escape special characters such as / and ==
vi /tmp/update :%s/==/\\=\\=/g :%s/\//\\\//g :wq
Run the script
# sh /tmp/update
Watch for errors. Users that are in AD but not in Scalix will give "entry not in the directory" errors; that's okay, they'll get imported later.
Also, if you see any GUIDs that are shorter than the others or that do not end in ==, then that GUID did not get retrieved correctly via the omldapsearch. Sometimes that happens; I'm not sure if the problem is in the way omldapsearch retrieves or displays the value, or in the way AD delivers the data in response to the search command. If you're bored you could play with it and find out :) At any rate, there won't be many and it's easy to correct later. When you run omldapsync you'll see errors in the sync.log file saying "Failed to locate or retrieve information in LDAP for id 0TWh88zLEkWmrRRtw9kyqA==" in the SOAP response. Look above the SOAP response to the SOAP Request and you'll see the user (or group) that is generating the error. Simply ommodent their global-unique-id in the SYSTEM and USERLIST directories to match what is shown in the error (remembering to escape == and / and put it all in quotes).
Building the omldapsync Agreement
For more information on the omldapsync utility and how it works, see the omldapsync HowTo.
Building an omldapsync agreement for Active Directory is documented in the Scalix Setup and Configuration Guide. Here are a couple of "gotchas" I've come across.
- (EX_LOGON) asks for the Active Directory administrator account name.
The Setup and Configuration guide suggests the format for your entry is:
cn=administrator,dc=organization,dc=com
I have found the above does not work; I had to use
cn=administrator,cn=users,dc=organization,dc=com
- (EX_PASS) asks for the related Active Directory Admin password.
The Setup and Configuration Guide says be sure to enter “1” (one), so that the synchronization can be fully automated. It really should read that if you want the synchronization to be fully automated (i.e. so you can run it unattended from cron), enter the administrator's password. If you prefer to be prompted for a password, leave this value unset. The password is stored in the sync.cfg file in plain text. It is protected by unix filesystem security (user/password, user and group perms) but some people do not find this acceptable and prefer to be prompted. In either case, you do not enter the number "1".
- EX_FILTER is set to EX_FILTER=(&(cn=*)(scalixScalixObject=TRUE))
This will import only entries with Scalix mailboxes. If you want to import Exchange users as well, you'll need a filter more like this: EX_FILTER=(&(cn=*)(objectclass=user))
Running omldapsync
If you do not have to reconcile users that were created in both Scalix and Active Directory, you only need run
omldapsync -u <agreement name>
For example:
omldapsync -u 11adlab
If you had users that were created both in Active Directory and Scalix, and you have edited the global-unique-id in the SYSTEM and USERLIST directories so that their value now matches the objectGUID value in AD, you will need to run omldapsync three times:
omldapsync -u 11adlab -L
This "reloads" the directory. You will get lots of errors saying the entry already exists, because we are trying to reload entries from AD that have also been created in Scalix. That is okay; what this step really accomplishes is to get all of the omldapsync working files up to date and loaded with all the AD data.
omldapsync -u 11adlab -A
This step accepts all the "entry already exists" errors. Now our working files have the complete data set in them, and we have instructed omldapsync that it is okay to move on. In other words, we've examined the errors, we know what's caused them, it is okay to ignore them.
omldapsync -u 11adlab -M
This final step modifies all the entries in the Scalix directory. It ensures that all entries are "owned" by Active Directory - that is, all entries have adiministered-by=ldapsync-11adlab or similar. It also ensures the authid is something that can be used by Active Directory/Kerberos for login purposes.
WARNING: - running the above omldapsync commands will change the authid to be name@DOMAIN.COM and it is case sensitive. If end users have been using authid to login, they will have to be told to use the new authid (SWA) and their profiles will have to be reconfigured (Outlook). Other clients that are configured to use the authid for login purposes will also need to be reconfigured.
From this point forward, all new user accounts should be created in AD, not in SAC.
Single Sign-On
Kerberos Configuration
Follow the instructions in the Scalix Setup and Configuration Guide, Single-Sign-On Kerberos Authentication. For Scalix 12.6, this section begins on page 56 and there are 32 steps.
NOTE that step 25 has a typo in it. It should read:
ktpass -princ scalix-ual/scalixserver.domain.com@DOMAIN.COM -mapuser scalix-ual -pass <password> -out scalix-ual.keytab -kvno3
People frequently make two mistakes at step 25:
- They fail to pay attention to case. This command is case sensitive. If the domain is shown in upper case in the example, you must use upper case when you run it on the AD domain controller.
- They fail to use the FQDN for the scalix server, and use only the short name. You must use the fully qualified host name.
Troubleshooting and Diagnostics
To test whether you have Kerberos (AD) authentication properly configured, the following two commands, run from the Scalix server, can prove helpful.
# kinit authid@DOMAIN.COM (Enter the password when prompted) # klist Ticket cache: FILE:/tmp/krb5cc_0 Default principal: authid@DOMAIN.COM Valid starting Expires Service principal 08/01/2016 08:14:54 08/01/2016 18:15:00 krbtgt/DOMAIN.COM@DOMAIN.COM renew until 03/13/201716:17:42
The output from the klist command shows that the user in question was able to connect to Active Directory and acquire a ticket-granting-ticket. This means that your Scalix server is configured to access the appropriate AD domain controller for DOMAIN.COM, that the user was found in Active Directory, and that the password was successfully matched.
If the above works but you still cannot login to a Scalix client, try the following:
# kinit -S scalix-ual/scalix.domain.com@DOMAIN.COM authid@DOMAIN.COM (Enter the password when prompted) # klist Ticket cache: FILE:/tmp/krb5cc_0 Default principal: authid@DOMAIN.COM Valid starting Expires Service principal 03/12/2016 16:17:42 03/13/2016 02:17:45 scalix-ual/scalix.domain.com@DOMAIN.COM renew until 03/13/2016 16:17:42
This means that in addition to successfully connecting to the AD domain controller and matching their password, the user was granted authorization to use the scalix-ual service; in other words, they've been granted permission to log in to Scalix.
PAM configuration
The following will cause your users to authenticate against AD if they have an entry in ADUC and against Scalix only if they are not found in Active Directory. All files are in /var/opt/scalix/??/s/sys/pam.d
ual.remote, omslapdeng:
auth required om_krb5 user_unknown=ignore auth optional om_auth nullok use_first_pass account required om_auth password required om_auth nullok
pop3:
auth sufficient om_krb5 use_first_pass auth required pam_deny account required om_auth password required om_auth
smtpd.auth (required for submitting messages from IMAP, POP3, SWA):
auth required om_krb5 user_unknown=ignore auth optional om_auth nullok use_first_pass account required om_auth
ual.local (required for omlist, omread):
auth required om_krb5 user_unknown=ignore auth optional om_auth nullok use_first_pass account required om_auth password required om_auth nopreauth nullok
