Active Directory Backend Users Installation Guide John Ligtenberg 22 September 2012
Table of Contents Introduction... 3 Revision History... 3 Installing and using the package... 4 Manual installation... 9 Installed files... 9 Changes to the database... 9 Undoing changes to the database... 10 Changes to ui.xml... 10 Changes to web.config... 10 Changes to umbracosettings.config... 11 Changes to trees.config... 11 Common (de)installation issues... 11 2
Introduction If your website is in a Windows domain and running Umbraco 4.8 or higher, this package will enable your users to log in to the Umbraco back office with their Windows (Active Directory) accounts, in stead of Umbraco accounts. Access will be limited to accounts which are members of certain Active Directory groups. The administrator is able to enter the names of these (pre-existing) groups into a custom tree in the Umbraco users section, which is created by the package. From this custom tree, the default Umbraco type (administrator, editor, writer etc.) can be set per Active Directory group, as well as the default access to the various sections of the back office (Content, Media etc.) These access rights are only assigned upon first login of the user account. Afterwards, access rights have to be changed on a per user basis from the Umbraco back office in the usual way. I.e. there is no group-based management of user rights after the first login. After installing the package, manual changes to configuration files are necessary, to change the default values to values specific for your domain. These changes are indicated in the instructions below. Configuration of this package requires access to these configuration files as well as the some information on LDAP paths and AD accounts specific to your domain. Revision History Version 1, 22 September 2012 - Initial install guide 3
Installing and using the package What are the prerequisites for installing this package? Which preparations should you make before installing the package? 1. Make sure you have Umbraco 4.8 or higher. Because the configuration of sections and trees has been moved from the database (in 4.7 and earlier) to configuration files in Umbraco 4.8, this package will not work with Umbraco 4.7, although most of the package has been developed using Umbraco 4.7. If you need the functionality of package in Umbraco 4.7, please contact me. 2. Make sure you have access to web.config, in the root of your umbraco site, and umbracosettings.config, in the config folder. 3. Make an Active Directory group for accounts which should be granted access to your Umbraco site, or get the name of such a group if it already exists. 4. Make sure the account with which you yourself are going to log in is a member of this group. 5. Find out the LDAP server name for your domain. 6. Find out the LDAP container for your domain. It could look like DC=mydomain,DC=com, with specific values for your domain. 7. Get the loginname and password for an account which has rights to read from to the Active Directory. This is the account with which an LDAP connection to the Active Directory will be established. 8. Find out the LDAP connectionstring for your domain. It could look something like LDAP://mydomaincontroller/DC=mydomain,DC=com If you don t have this information, don t install the package. If necessary, get help from the network administrator in your organisation (I did, anyway). What to do after installing the package? 1. Go to the users section. 2. Create a new node in the AD Groups tree, with the name of the Active Directory group which you want to grant access to your site. (You can add more groups later.) Give this group Administrator rights and access to all sections. (This is necessary because the first account which logs in should get Administrator priviliges, but you may change the priviliges of this group later.) 4
3. Log out of the site. 4. Edit the web.config file of your site. Change the values for the appsettings keys ldapname and ldapcontainer to values which are valid for your domain. Under connectionstrings, change the value of connectionstring for ADConnectionString to a value which is valid for your domain. Find the ADMembershipProvider under membership/providers, and change the values for connectionusername and connectionpassword to values which are valid for your domain. 5
5. Edit config/umbracosettings.config Change the value of providers/users/defaultbackofficeprovider to ADMembershipProvider If for some reason your connection with the Active Directory doesn t work, just restore the value of DefaultBackofficeProvider to UsersMembershipProvider, and you will be able to login with the normal Umbraco user accounts. In other words, as long as you haven t changed the value of DefaultBackofficeProvider to UsersMembershipProvider, you re still using the old Umbraco user accounts. 6. Log in to the site with your Active Directory account. This account should be a member of the group which you added under Users AD Groups in step 2, and should be assigned Administrator priviliges upon first login. 7. Go to the User section. 8. Check to see if the AD account with which you just logged in exists under the Users Users node, and if it has Administrator priviliges. 9. Change the rights of the group which you added under AD Group if necessary. In this example, want to change the group which was added in step 2 into an editor group. 6
This means limiting access to the Content and Media sections, and setting the Umbraco type name of the group to Editors. Users which log in after these changes have been made will receive editor rights. 7
Keep in mind that the Umbraco type and section access is assigned at the first log in of an account belonging to the group, and is not changed later by changing the settings of the group under the AD Groups node. This means that the account with which you logged in originally will remain administrator, unless you make changes to this user under the Users node. I.e. you cannot use the settings under AD Groups for changing the types and section access of users which already exist under the Users node. 10. Add more AD groups to AD Groups node if necessary. If an AD account is a member of more than one group, it will get the access rights corresponding to the first group found, whichever that may be. In that case you may need to change the rights of the user manually, through the node of the user under Users Users. 8
Manual installation This in an overview of changes made by the package, or changes you should make yourself in case you need to (de)install manually. Installed files 1. /bin/adgrouptree.dll 2. /bin/system.directoryservices.accountmanagement.dll 3. /bin/system.directoryservices.dll 4. /App_Code/AdGroup.cs 5. /App_Code/AdHelpers.cs 6. /App_Code/CreateUserHandler.cs 7. /App_Code/CustomUsersMembershipProvider.cs 8. /umbraco/plugins/editadgrouptree.aspx Changes to the database The package adds the table adgroups CREATE TABLE [adgroups]( [id] [int] IDENTITY(1,1) NOT NULL, [adgroupname] [nvarchar](100) NULL, [umbracotypename] [nvarchar](50) NULL, [sections] [nvarchar](max) NULL, CONSTRAINT [PK_adGroups] PRIMARY KEY CLUSTERED ( [id] ASC )WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY] ) ON [PRIMARY] 9
Undoing changes to the database If you need to remove the tabla adgroups manually, you can run the following SQL statement: IF EXISTS (SELECT * FROM sys.objects WHERE object_id = OBJECT_ID(N'[dbo].[adGroups]') AND type in (N'U')) DROP TABLE [dbo].[adgroups] GO Changes to ui.xml The following code is added to /umbraco/config/create/ui.xml <nodetype alias="adgrouptree"> <header>ad Groups</header> <usercontrol>/create/simple.ascx</usercontrol> <tasks> <create assembly="adgrouptree" type="adgrouptreetasks" /> <delete assembly="adgrouptree" type="adgrouptreetasks" /> </tasks> </nodetype> Changes to web.config Add keys to appsettings, and set values valid for your domain. <add key="ldapname" value=" myldapserver.mydomain.com" /> <add key="ldapcontainer" value=" DC=MyDomain,DC=com" /> Add a connectionstring to connectionstrings. <add name="adconnectionstring" connectionstring="ldap:// myldapserver.mydomain.com/dc=mydomain,dc=com" /> Add a membership provider in the membership section. Fill in the account name and password of a user which has the right to read from the Active Directory. <add name="admembershipprovider" type="adcontext.customusersmembershipprovider" connectionstringname="adconnectionstring" connectionusername="mydomain\myadsadmin" connectionpassword="mysecret" attributemapusername="samaccountname" /> 10
Changes to umbracosettings.config Set the DefaultBackofficeProvider to UserMembershipProvider for Umbraco backoffice users, or to ADMembershipProvider for Windows (Active Directory) backoffice users. <providers> <users> <!-- <DefaultBackofficeProvider>UsersMembershipProvider</DefaultBackofficeProvider> --> <DefaultBackofficeProvider>ADMembershipProvider</DefaultBackofficeProvider> </users> </providers> Changes to trees.config Add an entry to trees.config for the custom tree in the users section. <add application="users" alias="adgrouptree" title="ad Groups" assembly="adgrouptree" type="loadadgrouptree" iconclosed=".sprtreefolder" iconopen=".sprtreefolder_o" sortorder="3" /> From Umbraco 4.8 upwards section and trees are in configuration files in stead of in the database, this is what makes this package unsuitable for Umbraco 4.7 Common (de)installation issues After installing the package and configuring the site, you may want to uninstall the package for some reason. In that case you need to edit umbracosettings.config by hand, to re-enable the UsersMembershipProvider. 11
<providers> <users> <DefaultBackofficeProvider>UsersMembershipProvider</DefaultBackofficeProvider> </users> </providers> 12