Tuesday, May 20, 2008

How To: Integrate Gallery Server Pro with Active Directory

You can configure Gallery Server Pro to use your existing accounts in Active Directory. Woo HOO! Crack open the Skittle-brau and pretzels!

Gallery Server Pro uses the ASP.NET Membership Provider model to manage users and roles. By default, it is configured to store this data in a SQL Server database. However, you can take advantage of an entirely different data store through the use of alternate membership providers such as ActiveDirectoryMembershipProvider or even one you write yourself. In this article I'll describe how to modify a default installation of Gallery Server Pro to use Active Directory for user management.

Note: Due to differences in behavior between SqlMembershipProvider and ActiveDirectoryMembershipProvider, a few tweaks to the code behind for the Manage Users page is required. These changes will be included in the next release. Until then, you can replace the contents of manageusers.aspx.cs with this version (you'll need to recompile).


Step 1: Configure basic AD integration

The first step in Active Directory configuration is to modify the web.config file in the root of the Gallery Server Pro application. Add a connection string to AD:

    <add name="GalleryServerDbConnection" connectionString="Data Source=(local);Initial Catalog=GalleryServerPro2;Integrated Security=true;Application Name=Gallery Server Pro" />
    <add name="ADConnection" connectionString="LDAP://,DC=mydomain,DC=techinfosystems,DC=com"/>

The value is the IP address of the domain controller. You can also specify the Fully Qualified Domain Name (ex. mydomain.techinfosystems.com), the Relative Distinguished Name (ex. godzilla if that is the name of your DC); or for more redundancy you can specify just the domain name (ex. mydomain).  Which ever you choose just be sure you can ping it.

The next step is to comment out the existing membership configuration by adding <!-- to the beginning and --> to the end, like this:

<!--<membership defaultProvider="SqlMembershipProvider">
    <add applicationName="Gallery Server Pro" connectionStringName="GalleryServerDbConnection" minRequiredNonalphanumericCharacters="0" minRequiredPasswordLength="2" requiresQuestionAndAnswer="false" passwordFormat="Clear" enablePasswordReset="true" enablePasswordRetrieval="true" requiresUniqueEmail="false" maxInvalidPasswordAttempts="50" passwordAttemptWindow="10" name="SqlMembershipProvider" type="System.Web.Security.SqlMembershipProvider"/>

Now add the new membership info for Active Directory:

<membership defaultProvider="AspNetActiveDirectoryMembershipProvider">
    <add name="AspNetActiveDirectoryMembershipProvider"
          type="System.Web.Security.ActiveDirectoryMembershipProvider,System.Web, Version=,Culture=neutral,PublicKeyToken=b03f5f7f11d50a3a"

The version number must match the one installed on your web server, so update it as needed. Some examples I saw on the internet used 2.0.3600.0 instead of Make sure the connection string name matches the name you specified in the connection string definition. The enableSearchMethods attribute is required so that Gallery Server Pro can retrieve a list of all users on the user management page.

Now, at this point you should be able to log on to Gallery Server with your domain account, but you will receive the following message:


This is because your user account is not a member of any roles in Gallery Server Pro. Recall that when you installed Gallery Server Pro, a role named GlobalAdmin was created with administrative permission. Now you need to add one or more AD users to this role. But how do you do this when no one has authorization to perform this task?

If you are using IIS 7, the answer is easy. Open up IIS Manager, navigate to the Gallery Server Pro web app, and click .NET Users. A list of your AD users appears. Double click the one that you want to be the administrator, and add the user to the GlobalAdmin role in the dialog box. The next time you log on to Gallery Server Pro you will have administrative access.

For IIS 6 and earlier users, the task is a bit more difficult because those versions don't provide a means for accessing the users. However, all versions of Visual Studio 2005 and higher - including the free Express versions - provide the Web Site Administration Tool, which allows you to edit the roles for users. Using this tool is beyond the scope of this document, but online information can be found.

At this point you should be able to log on using your AD account. Use the syntax user@fully_qualified_domain_name, such as Roger@mydomain.techinfosystems.com. Later I'll show you how can get change it to just the username.


Step 2: Create, edit and delete AD accounts within Gallery Server Pro

Once you are logged on as an administrator, you can go to the Manage Users page and add the remaining AD accounts to appropriate roles. If the IIS user account does not have permission to make changes to AD, you may receive an error like this when you click Save changes:


You will get this error because the IIS worker process does not have permission to modify AD data. To get around this, you have two choices:

1. Specify a domain account in web.config that has the necessary permission. Open web.config and add connectionUsername and connectionPassword attributes to the provider definition, like this:

<membership defaultProvider="AspNetActiveDirectoryMembershipProvider">
    <add name="AspNetActiveDirectoryMembershipProvider"
      type="System.Web.Security.ActiveDirectoryMembershipProvider, System.Web,Version=,Culture=neutral,PublicKeyToken=b03f5f7f11d50a3a"

Note that putting an AD account name and password in a plain text file is a security risk. If you go this route, I HIGHLY recommend you encrypt the web.config file. Here are two links where you can learn more:

How To: Encrypt Configuration Sections in ASP.NET 2.0 Using DPAPI

Video: How Do I: Encrypt My Web.Config File?

2. Specify an account for the IIS worker process that has the necessary AD permission. I prefer this over the first solution.

Once the permissions are sorted out, you have the potential to create, edit and delete users. Remember that adding a user creates a new account in Active Directory and deleting an account removes it! Obviously this can be abused in a way that affects your entire domain, so use caution. For this reason, you may actually prefer to revert to read-only permissions and handle role membership via IIS 7 Manager (or the Web Site Administration Tool for IIS 5-6).



Log on with simple username instead of fully qualified name

Your users might not be thrilled with to have to log on with the syntax user@fully_qualified_domain_name, such as Roger@mydomain.techinfosystems.com. If you want to log on with just a username, add the attributeMapUsername to the membership configuration:

<membership defaultProvider="AspNetActiveDirectoryMembershipProvider">
    <add name="AspNetActiveDirectoryMembershipProvider"
      type="System.Web.Security.ActiveDirectoryMembershipProvider,System.Web, Version=,Culture=neutral,PublicKeyToken=b03f5f7f11d50a3a"

By setting attributeMapUsername to sAMAccountName, you can log on with just the username, such as 'Roger' in the previous example.

Additional provider options

The AspNetActiveDirectoryMembershipProvider provider includes several attributes I haven't mentioned. These attributes configure various logon and password options. Be sure to check them out if you want more control.



Can't use Windows groups

If you are using AD, you probably use Windows groups to control permissions. You may have a Marketing group whose members have read/write access to the marketing shared folder but read only access to the Development and Engineering folders. Wouldn't it be nice if you could map albums in Gallery Server to your groups, so that the Marketing users would have control over the Marketing album, Developers have the Dev album, and so on?

On the surface, it seems we can just use the WindowsTokenRoleProvider instead of the SqlRoleProvider. However, if one tries this, the following error occurs during application startup:

"The configured Role Provider (WindowsTokenRoleProvider) relies upon Windows authentication to determine the groups that the user is allowed to be a member of. ASP.NET Role Manager cannot be used to manage Windows users and groups. Please use the SQLRoleProvider if you would like to support custom user/role assignment."

This error is generated when Gallery Server Pro tries to get a list of all roles with the Roles.GetAllRoles() method, and the WindowsTokenRoleProvider does not support it. Unfortunately, Gallery Server cannot do its job unless it can get a list of the roles, so for the time being we cannot take advantage of the Windows groups. If anyone discovers a way around this, let us know.

Can't auto-logon users

Back in my classic ASP days I built an intranet app that automatically recognized the Windows account the user was logged on with. No separate logon inside the web app was required. For reasons I don't understand, I cannot accomplish the same thing with ASP.NET Membership. Sure, you can disable anonymous authentication, enable Windows authentication, and turn on impersonation in web.config. Doing this *does* allow Gallery Server Pro to automatically log on users, but it doesn't think the user is in any roles, and there doesn't seem to be any way to configure roles for the user. Let us know if you know a way around this.

Can't reset or change password on other accounts

I didn't spend much time investigating this, but it appears you can't use Gallery Server Pro to reset or change another user's password. I received error messages when I tried. You *can*, however, change your own password by clicking the My account link in the top right corner and then clicking Change password.

No comments: