CPS &amp; Active Directory Authentication<br/><br/>CPS &amp; Active Directory Authentication<br/>The steps to get CPS to authenticate portal users through Active Directory are described here. I am setting up CPS as an Intranet server for a school near home. The school is currently an all Windows environment and uses a Windows Server 2003, with Active Directory. As all user accounts are already on this server, I decided to use LDAP authorisation against the Active Directory. I think it may be a better alternative to use LDAP for authorisation only, and leave the group and role configuration inside Zope. For now I will go ahead with using the Active Directory for storage and setting of Groups and Roles within the site. This document explains the setup of LdapUserGroupsFolder and the necessary changes in Active Directory for Groups and Roles. I tried to get LDAPUserGroupsFolder to work under the PluggableUserFolder product but I had some problems. Active Directory users were authenticated, but their home folder wasn't created and some errors were displayed.<br/><br/>LDAPUserGroupsFolder Documentation<br/>Read the documentation provided with LDAPUserGroupsFolder. Most options of this program are explained. Look in the help folder for detailed explanations.<br/><br/>Active Directory Information<br/>For information about the Active Directory schema you can try this link to Research LDAP* Properties for the User object. This next tip was copied from this article. To discover more LDAP attributes, go to the command prompt, type: CSVDE -f Exportfile.csv. Then open Exportfile.csv with Excel.exe. Alternatively, use ADSI Edit and right click the container objects. The only problem with using CSVDE is that the amount of<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (1 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>information generated is enormous. Look at this article at Microsoft technet &quot; Browse the directory tree using Ldp.exe&quot; for a method of viewing the details of your Active directory in a GUI interface. If you use Ldp.exe, follow these steps to view your directory structure. 1. Start the command At a command prompt type ldp and then press enter. The GUI starts. 2. Pick on the Connection menu, then select Connect. Type in the server name and port (normally 389 or 3268) 3. Pick on the Connection menu, then select Bind. Enter an Administrator users login name and password. Check the Domain checkbox. 4. Pick on the View menu, select Tree. Leave the field empty to see the complete domain, otherwise enter a Base DN to restrict the information displayed.<br/><br/>What you need<br/>At a minimum you need this information from Active Directory. A user with a minimum of Account Operator permissions in Windows could do all Active Directory modifications needed to make this work. Users Base DN The deafult user folder in Active Directory is CN=Users,DC=yourdomain,DC=com,org,etc Any valid container is OK. Manager DN &amp; Password An Active Directory user and password. If using Read-write access this user must have the Account Operator permission (at least). Eg CN=ldapuser,OU=Management<br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (2 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>Staff,OU=Staff,DC=Manitacc,DC=com If you are going to use Active Directory for Role and Group storage then you will also need. Roles Base DN An Active Directory container below which Security Groups that will map to Zope Roles are found. Eg. OU=zoperoles,DC=Manitacc,DC=com Groups Base DN An Active Directory container below which Security Groups that will map to Zope Groups are found. Eg. OU=zopegroups,DC=Manitacc,DC=com<br/><br/>Ports to use<br/>Unless you want to set up other ports in Active Directory there are 2 choices. If you are going to use Read-only mode it is probably best to use the Global Catalog. The Global Catalog is a Read-only view of the Active Directory. StandardLDAPDirectoryPort 389 Windows Global CatalogPort 3268<br/><br/>Sequence<br/>It is probably best to setup the Active Directory before trying to configure the LdapUserGroupsFolder product for your CPS site. Testing won't work correctly if the entries don't exist in Active Directory. At the very least you need to decide on the Active Directory containers that will be used and the user who the Manager DN refers to.<br/><br/>Recommendation<br/>Use the LDAP authorisation from Zope in Read-only mode. I had problems with accounts being locked out after editing account details from within the CPS site. These problems may be fixable, but I<br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (3 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>won't look at this until I need it. Editing users from the acl_users folder in the ZMI seemed to work OK, but editing or adding Roles and Groups doesn't work.<br/><br/>Warning Make sure you test this thoroughly on a new test site before trying to install it on a live site.<br/><br/>Before changing the authentication on a real site, experiment and make sure you are not going to be surprised. Using LDAPUserGroupsFolder in Read-only mode seems to be stable, but there could be unexpected surprises. In my case using Read-write access causes some problems, which are serious enough to force the use of Read-only.<br/><br/>CPS Setup<br/>After creating a CPS Default Site do the following. The LdapUserGroupsFolder needs to be configured to suit the Active Directory environment. The images shown below work for the Manitacc.com domain; adjust the values shown to suit your Active Directory environment. The steps involved in the setup Delete the acl_users folder from your site. After deleting the acl_users folder, we must replace the it with an LdapUserGroupsFolder. Use the ZMI to add a LDAPUserGroupsFolder. The Configure tab shown in Figure 1 will appear. When first installing the LdapUserGroupsFolder product you can't fill out the Configure tab correctly. After creating the LdapUserGroupsFolder you can then go back and edit<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (4 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>the values that must be changed. The correct values can't be changed until after the Schema has been modified Modify settings on the Schema tab Pick on the Schema tab and modify the Schema to suit Active Directory. See below for details. Modify the Configure Tab This step must be completed after the Schema modifications. Details of the settings that work for me are shown below. Role Mapping If you are using Active Directory for Roles, you must select the Roles tab and modify the Add LDAP role to Zope role mapping section of the page. At the very least you must add two mappings. The LDAP role (the Active Directory Security Group) that is set for your site managers needs to be mapped to the sites Zope Manager role, and the LDAP role used for site members must be mapped to the Zope Member role. Test LDAP Communications The testing is just a matter of searching on the Users tab and checking to see if the correct Roles and Groups appear on their respective tabs.<br/><br/>The Configure Tab<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (5 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>Figure 1. A working configuration The Users Base DN is the Active Directory container below which all site users must reside. Users can be in other sub-containers beneath the Users container. The Manager DN value in Figure 1 is the same, except for the first container (CN=ldapuser) as shown in the example below. This CN value is the full name of the user, created from the values returned by the givenName and sn values from the Schema. The value of these names and all other fields in the Schema are looked up in the Active Directory. Examples of other values that will work with my network are:Users Base DN OU=Staff,DC=Manitacc,DC=com Manager DN<br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (6 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>CN=Steve Meaker,OU=Management Staff,OU=Staff,DC=Manitacc,DC=com Remember, when the LdapUserGroupsFolder is first created you can't complete it correctly. Complete as much as you can, then save the folder. As soon as you pick on it again you can create the Schema and then edit the Configure tab to the correct values.<br/><br/>The LDAP Schema Tab<br/><br/>Figure 2. The LDAP Schema tab The Schema is critically important and must be done exactly as shown. Case is important. The values in the &quot;LDAP Attribute Name&quot; column refer to the names from the Active Directory schema. The &quot;Mapped to Name&quot; column contains the names used within CPS.<br/><br/>E-mail address - either userPrincipalName or mail.<br/>In Figure 2 the userPrincipalName is mapped to the CPS site<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (7 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>members email address. The userPrincipalName is an email style address that is created for each user in an Active Directory domain. By default this address is made up of the users login name, a @ symbol, followed by the domain name. The users login name part of this address can be changed, but not the @domain-name section. When editing a user in Active Directory, the userPrincipalName is shown on the Account tab, labelled as the login name. On the tab labelled Address you can enter another email address. You can enter a complete email address in this area, and are not restricted to the Active Directory domain name for the address. If your users email address is not the userPrincipalName, replace userPrincipalName with mail.<br/><br/>userPrincipalName Problems<br/>Using the userPrincipalName for an email address may cause problems. An email address is essential for members of a CPS site, but is not always put in Active Directory. The userPrincipalName can be used for the member email address, but this can cause problems if there is no real email address, or if the site member attempts to change their email address. It is not possible for users to change their login details in Active Directory, but attempting to edit the email address (userPrincipalName) is really an attempt to edit the user login name and the domain name. Neither will work for a user, and attempts to do either will cause errors. An Active Directory Administrator can't change the domain name part of the userPrincipalName, although the user login name can be changed by an Account Operator or Administrator.<br/><br/>Active Directory Setup<br/>To use Active Directory for authentication all users need to be under a single container in Active Directory. They don't need to be in the<br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (8 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>same container, but they must all be below one container. This also applies to Roles and Groups. Active Directory can be used for authentication only, or for authentication plus the storage and management of Roles and/or Groups.<br/><br/>Read-only or not?<br/>If you are not using LDAPUserGroupsFolder in Read-only mode you can edit the user details from Active Directory while using the ZMI. You can add and change user details, although roles and groups can't be changed or added. However, if a CPS site user attempts to edit their own details (from the My preferences command) their account loses all roles that were assigned. The command seems to complete OK, but their changes have been lost and all their roles have also been removed. If using the Read-only mode, the user seems to be able to edit their preferences, but no changes are saved. There is no error either, and the users roles are not touched. If Read-only mode is not used you should modify the CPS My preferences screen to stop users modifying their own details. Removing the permission to &quot;Set own properties&quot; stops a member from logging in to the site, so this is not the way to do it. My own preference is to use the Global Catalogue on port 3268 in Read-only mode. This is by far the safest, and doesn't add any extra risk of someone managing to grant themselves extra rights, not just within your CPS site, but within the complete Active Directory network as well.<br/><br/>Manager DN - Permissions<br/>The Manager DN shown in Figure 1 identifies the user who will be authenticated against the Active Directory for all management tasks and Active Directory lookups. Read-only<br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%2...th%20Active%20Directory%20Authentication.htm (9 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>If you have set Read-only mode on the Configure tab (Figure 1) in your LDAPUserGroupsFolder, the Manager DN user must have at least the Domain User permission in Active Directory. Read-write If you haven't elected to use Read-only mode the Manager DN user must have, at least, the Account Operators permission in Active Directory. This user should not be, and does not need to be an Administrator in Active Directory, although Administrator will work too. In the example shown in Figure 1, the Manager DN (CN=ldapuser) places the LDAP user in a separate container than the Users Base DN (CN=Users), below which all other site users are located. All users can be in a single location if you prefer. The user (CN=ldapuser) was created, and is only used for this one purpose, although you could use any member of the Active Directory, it doesn't need to be a special user.<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (10 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>Roles and Groups<br/>If you are going to use Active Directory for Roles and Groups you could create Active Directory containers especially for the Groups and Roles needed in the CPS site. Figure 3 shows this type of setup, with an Active Directory Organizational Unit containing Security Groups. This is fine for a small site. If you already have appropriate Roles and Groups in Active Directory you can use those instead. Figure 3. Roles and Groups in Active Directory The Roles Base DN and the Groups Base DN shown in Figure 1 refer to the 2 containers shown here, zopegroups and zoperoles. Both containers were created as Organizational Units in Active Directory, and the Groups and Roles shown were created as Global Security Groups. Roles and Groups don't all need to in the same container as shown in Figure 3, you can have nested containers. Your Security Groups must be located beneath the path defined in the Roles Base DN and Groups Base DN fields of the Configure tab (Figure 1). Roles The names used for Roles in the Active Directory can be mapped to different names in the CPS site. It is possible, and sometimes preferable, to use existing Active Directory Groups and map them to Roles inside the LDAPUserGroupsFolder in the CPS site.<br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (11 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>For example, if you already have a WebAdministrators Group in Active Directory, you could map this Group to the Manager role, and the default Users Group in Active Directory could be mapped to the Member role. Roles that are assigned through Active Directory are applied globally, across the whole site. When using Roles and Groups in Active Directory you need to consider that you can't assign Roles to your Groups inside Active Directory. For example, using LDAPUserGroupsFolder you can map the zoperoles.manager Group (see Figure 3) to the Manager role in your CPS site. All members of the zoperoles.manager Group will then have the Manager role in your site. In Active Directory you then assign the group named zopegroups.managers membership in the zoperoles.manager group, Even though members of the zoperoles.manager group are granted the Manager role in the site, members of the zopegroups.managers Group won't inherit the membership (or permissions) of the zoperoles.manager Group in your site (they will in Active Directory). When using Active Directory for your site Roles, you should create some Roles (Active Directory Security Groups) with names that correspond to the standard CPS Roles, Member, Manager and perhaps Reviewer. In nearly all circumstances these Roles are all you will need to act globally, all others should be applied with Local Role Assignment within the site. Many other Roles exist in the CPS site, but these should not need to be duplicated in Active Directory, as they are not normally used globally across the whole site but applied to individual Sections and Workspaces. Groups There are no Groups created when you create a CPS default site. It is up to each site manager to determine the number and makep of<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (12 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>Groups, if any are used at all. The use of Groups in a CPS site is pretty much the same as using Groups in Active Directory. It allows you to assign extra permissions (or restrictions) on a large number of users at once. If you already have Groups made in the Active Directory you could use them, or you could create new Groups for your site members. No Groups are essential; you could assign permissions to individuals if the number of users is small enough. As a site grows it becomes easier to manage a small number of groups than managing hundreds or thousands of individuals.<br/><br/>Roles &amp; Groups outside Active Directory<br/>Depending on the complexity of the site it may be appropriate to have the Role and Group records stored in the Zope database. In that case, in Figure 1 you would set the Role Storage and Group Storage fields to &quot;......not stored on LDAP server&quot;. You would then use the Roles and Group tabs to set and edit these attributes for the site members authorised by the LDAP connection to Active Directory.<br/><br/>Active Directory User Data<br/>Make sure all your Active Directory users contain information in all fields that are shown in the Schema (Figure 2), otherwise problems may arise. At a minimum you really need to complete these 4 fields when creating your Windows users. givenName First name sn Last name sAMAccountName Login name and either userPrincipalName Domain Email address or mail Email address In Active Directory the cn, or Canonical Name is created by<br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (13 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>concatenating the givenName and sn fields.<br/><br/>Testing the LDAP Settings<br/>Testing of the basic operation of the settings supplied in Figure 1 could be done before making any changes for Groups and Roles in the Active Directory. If the Groups Base DN orRoles Base DN doesn't exist, you will see an error message similar to this ­ n/a Cannot find (|(objectClass=group)(objectClass=groupOfNames).... when you pick on the Groups or Roles tabs. If you are not storing your Role and Group data on the LDAP server, after completing the Schema tab and then editng the Configure tab you are ready to try out the settings and make sure everything works OK. You can create Groups and Roles easily on the appropriate tab. If you are using Active Directory for Roles and Groups you should complete the changes needed in Active Directory before testing the Roles or Groups.<br/><br/>User Tab<br/>The easiest way to test the configuration is to try out some user searches. Select the Users tab. Figure 4 below shows the top area of the screen that is shown when the Users tab is selected. Here you can search for individual or multiple users. Leaving the right-hand form field empty will return all users, based on the option selected from the left-hand side drop-down list box.<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (14 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>Figure 4 Options for User searching against the LDAP Schema defined earlier. Each of the different search options is shown in Figure 4. Note that these options are the Schema entries defined earlier. Try out each option in turn. If you leave the right side field empty, each search should return entries from your Active Directory. For example, searching by Canonical Name(cn) or Login name (sAMAccountName) should display all users in (and maybe below) the Users Base DN folder specified in the configuration tab earlier. Searching by Email address (userPrincipalName) will display all users who actually have an email address. Figure 5A typical search return. Figure 5 shows a list of<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (15 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>users based on the Schema defined earlier. The results shown here were based on a Canonical name (cn) search. With the search term blank all users within and below the container specified by the Users Base DN are shown. If you were to type a letter or word in the search form, the search would display only those users whose credentials matched the word or letters typed. Try a search using each of the selections from the drop-down list. Each search should return some users, provided you have users that match the search type. Searching on the givenName field won't return a user who doesn't have this field completed in Active Directory. The Administrator user doesn't have a givenName, so this user won't be seen by this search.<br/><br/>User Data<br/>When you select a user returned by a User search you should see a form displayed with all fields completed (see Figure 6 below), unless the selected user has blank entries, such as no surname or no email address.<br/><br/>Figure 6. User details after selecting a user from search results. If you know the selected user has the required data, but it doesn't display in the details displayed (see Figure 6) then this indicates there<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (16 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>is a problem with your Schema. Check the spelling carefully. If you can successfully search for users using each of the options shown in Figure 3 then your LDAP authorisation should work OK, provided your Role membership is at least at the Member level.<br/><br/>Groups Tab<br/>If you have set your Group Base DN correctly you can quickly check to see if your Group settings are correct. Pick on the Groups tab.<br/><br/>Figure 7. Groups displayed on the Groups tab. The Groups shown in Figure 7 are from the Active Directory (see Figure 3). If your Groups Base DN setting is not right you will see an error message. There is one option on the Groups tab that is not shown in Figure 7. There is a form where you can enter a name and create a new Group. When you attempt to create a Group using this method an error message is displayed. The same error displays when you attempt to create a new Role.<br/><br/>Roles Tab<br/>To chack that Roles are being read fromActive Directory correctly<br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (17 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>pick on it.<br/><br/>Figure 8. The Roles tab The top section of the Roles tab is similar to the Groups tab. A list of Roles found is shown, with below this being an area where new Roles can be created. Role Mapping This section of this page is important and needs to be modified. Figure 8 above shows the minimum two Role mappings that are necessary. The LDAP (or Active Directory in this case) role named member has been mapped to the Zope role Member. The LDAP<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (18 of 19) [18/07/2005 9:49:45 AM]<br/><br/><br/>CPS &amp; Active Directory Authentication<br/><br/>manager role has also been mapped to its counterpart in Zope. If you are using existing Active Directory group names, this is where they are mapped to the correct name for Zope and CPS. For example, the Administrators group in Active Directory could be mapped to the Manager role in Zope.<br/><br/>file:///D|/Zope%20CPS%20Manuals%20etc/Site%...h%20Active%20Directory%20Authentication.htm (19 of 19) [18/07/2005 9:49:45 AM]