Introduction

K2 blackpearl supports the use of multiple domains. However, there can be only one label for an AD (Active Directory) Provider with K2 blackpearl.

Important: The steps in this document refer to K2 blackpearl with Service Pack 1 or greater. Do not use these steps with pre-SP1 installations. K2 recommends upgrading to the latest service pack.

This document refers to older versions of K2 blackpearl, for information relevant to the the current version see the topic in the K2 blackpearl Installation and Configuration Guide: "Getting Started - Installation and Configuration > Installation > Post installation common tasks > K2 Environment > Adding Multiple Active Directory Domains". 

Implementation Discussion

Domain registration is performed by inserting the domain name and associated label into the SecurityLabels table in the HostServer database. The label has two components: Authentication Provider and Role Provider.

Note: This document assumes some programming knowledge and familiarity with SQL Server 2005

If you have subdomains or domains in a different forest, you will have to add those domains to the same security label by modifying the AuthInit and RoleInit fields in the SecurityLabels table in the HostServer database.

The following two placeholders are used in the examples below.
NETBIOS Name
LDAP String
[PARENTNETBIOSNAME] LDAP://DC=ParentDomain,DC=COM
[CHILDNETBIOSNAME] LDAP:// DC=ParentDomain,DC=ChildDomain1,DC=COM
Note: While the examples use a parent-child domain relationship, this is not required. If using domains in different forests, a one- or two-way trust relationship must be established. The type of relationship required depends on your environment.
The AuthInit field for the security label being modified should contain both domain NETBIOS names.
<AuthInit>
                      <Domain>[PARENTNETBIOSNAME]</Domain>
                      <Domain>[CHILDNETBIOSNAME]</Domain>
</AuthInit>
The RoleInit field for the same security label should be modified as follows:
  1. Set the "MultiDomain" property to "True"
  2. Edit the DataSources property by following the example below:
DataSources=<DataSources><DataSource Path="LDAP://DC= ParentDomain,DC=COM" NetBiosName="[PARENTNETBIOSNAME]"/><DataSource Path="LDAP://DC=ParentDomain,DC=ChildDomain1,DC=com" NetBiosName="[CHILDNETBIOSNAME]"/>
</DataSources>
Important: The escape characters "<" and ">" must be used as specified in the example above. Be careful to replace only the DataSources substring of the RoleInit string.
Important: The K2 Server needs to be restarted after the modifications have been made in order for the changes to be affected.

Implementation Script

The following query can be run to modify the security label to be updated. Note the placeholder values in the script are the same as those used above. Additionally, the [LABELNAME] placeholder at the end of the script should be replaced with an actual value. This value is typically "K2" when using the security label for the default Active Directory provider.

Use K2HostServer
Update SecurityLabels
Set AuthInit = '<AuthInit><Domain>[PARENTDOMAIN]</Domain><Domain>
[CHILDDOMAIN]</Domain></AuthInit>',
Roleinit ='<roleprovider>
<init>ADCache=10;ResolveNestedGroups=False;IgnoreForeignPrincipals=False;
IgnoreUserGroups=False;MultiDomain=True;DataSources=<DataSources>
<DataSource Path="LDAP://DC=[PARENTDOMAIN],DC=[PARENTDC]"
NetBiosName="[PARENTNETBIOSNAME]"/>
<DataSource Path="LDAP://DC=[CHILDDOMAIN],DC=[PARENTDOMAIN],DC=
[PARENTDC]" NetBiosName="[CHILDNETBIOSNAME]"/>
</DataSources>
</init>
<login />
<implementation assembly="ADUM, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=16a2c5aaaa1b130d" type="ADUM.K2UserManager2" />
<properties><user><property name="Name" type="System.String" /><property
name="Description" type="System.String" /><property name="Email"
type="System.String" /><property name="Manager" type="System.String" />
<property name="SipAccount" type="System.String" /><property
name="ObjectSID" type="System.String" /><property name="DisplayName"
type="System.String" /><property name="CommonName" type="System.String"
/><property name="UserPrinsipalName" type="System.String" /></user>
<group><property name="Name" type="System.String" /><property
name="Description" type="System.String" /><property name="Email"
type="System.String" /></group>
</properties>
</roleprovider>'
where SecurityLabelName='[LABELNAME]'

 

Additional Details

The following details about the database structure may or may not be useful, depending on modifications made to your database. Do not update database values beyond what is specified in this article unless instructed to do so by a support representative.

  • SecurityLabelID is related to the SecurityLabelID field in the SecurityCredentialCache table. It is first generated in the SecurityLabels table so you can generate this manually if necessary.
  • SecurityLabelName is the name of the particular SecurityLabel. It should be unique.
  • AuthSecurityProviderID and RoleSec are the provider GUIDs found in SecurityProviders table.

 

Modifying the Workspace Web Site

When using multiple domains it is also important to modify the Workspace Web site to authenticate for each domain. To do this, follow these steps:

  1. Open web.config file corresponding to the Workspace Web site, typically located at C:\Program Files\K2 blackpearl\Workspace\Site
  2. Add a new AD Connection String in the connectionString section. For example:

     <add name="ADConnectionString2" connectionString="LDAP://Domain2.com" />
  3. In the membership section add a new provider pointing to the newly added connection string. The name of the string needs to be unique and match the other example in Step 2. For example:
    <add connectionStringName="ADConnectionString2" connectionProtection="Secure"
        enablePasswordReset="false" enableSearchMethods="true" requiresQuestionAndAnswer="false"
        applicationName="/" description="Default AD connection" requiresUniqueEmail="false"
        clientSearchTimeout="30" serverSearchTimeout="30" attributeMapUsername="sAMAccountName"
        name="AspNetActiveDirectoryMembershipProvider_Domain2" type="System.Web.Security.ActiveDirectoryMembershipProvider,System.Web,
        Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>  
  4. Perform an IIS reset

Upgrading from K2 blackpearl 0807 (4.8210.3.0) Release

Note: The following applies to upgrading from K2 blackpearl SP1 to K2 blackpearl 0807 (4.8210.3.0) or K2 blackpearl 0803 (4.8075.1.0) to K2 blackpearl 0807 (4.8210.3.0).

Logic has been added to the K2 installer to preserve multi domain settings. This means that when upgrading from K2 blackpearl SP1 to K2 blackpearl 0807 (4.8210.3.0) or K2 blackpearl 0803 (4.8075.1.0) to K2 blackpearl 0807 (4.8210.3.0), the multi domain settings will be preserved.

The multi domain settings will be preserved only if the configuration Manager is completed right after the upgrade. If however the configuration is cancelled and later the configuration utility is executed, it will then assume full reconfiguration and overwrite/reset the multi domain settings. If the configuration was accidentally cancelled and the multi domain settings are to be preserved pass the flag –l to the executable on the command line when running the next configuration. This indicates limited UI mode for the configuration tool.

Important: If the Configuration Manager is run after the upgrade to K2 blackpearl 0807 (4.810.31.0) the domain settings will be reset and the steps in this article will need to be applied.

Update

An update has been made with the installation of Update KB000575 and later the multi domain settings will always be preserved.