Active Directory Backend Users. Installation Guide

(1)

Active Directory

Backend Users

Installation Guide

John Ligtenberg

(2)

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

(4)

4

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.)

(5)

5 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.

(6)

6 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.

(7)

7

This means limiting access to the Content and Media sections, and setting the Umbraco type name of the group to “Editors”.

(8)

8

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.

(9)

9

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]

(10)

10

Undoing changes to the database

If you need to remove the tabla adGroups manually, you can run the following SQL statement:

Changes to ui.xml

The following code is added to /umbraco/config/create/UI.xml

Changes to web.config

Add keys to appSettings, and set values valid for your domain.

Add a connectionstring to connectionStrings.

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.

IF EXISTS (SELECT * FROM sys.objects WHERE object_id = OBJECT_ID(N'[dbo].[adGroups]') AND type in (N'U')) DROP TABLE [dbo].[adGroups]

GO

<nodeType alias="AdGroupTree"> <header>AD Groups</header>

<usercontrol>/create/simple.ascx</usercontrol> <tasks>

</nodeType>

<add name="ADConnectionString"

connectionString="LDAP:// myldapserver.mydomain.com/DC=MyDomain,DC=com" />

<add name="ADMembershipProvider"

type="AdContext.CustomUsersMembershipProvider"

connectionStringName="ADConnectionString"

connectionUsername="MyDomain\MyADSAdmin"

connectionPassword="MySecret"

(11)

11

Changes to umbracoSettings.config

Set the DefaultBackofficeProvider to UserMembershipProvider for Umbraco backoffice users, or to ADMembershipProvider for Windows (Active Directory) backoffice users.

Changes to trees.config

Add an entry to trees.config for the custom tree in the users section.

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. <providers> <users>

<DefaultBackofficeProvider>ADMembershipProvider</DefaultBackofficeProvider>

</users> </providers>

<add application="users" alias="AdGroupTree" title="AD Groups" assembly="AdGroupTree"

type="LoadAdGroupTree" iconClosed=".sprTreeFolder"

(12)

12

<users>

<DefaultBackofficeProvider>UsersMembershipProvider</DefaultBackofficeProvider>

</users> </providers>

Active Directory Backend Users. Installation Guide