Adding Multiple Active Directory Domains

If your network includes multiple Active Directory domains or a new domain is added to your Active Directory infrastructure, the additional domains will not automatically be discovered by K2 or appear in K2 Workspace. K2 adds the default domain based on the domain of the account used to install K2; additional domains must be added, edited and deleted manually, preferably using K2 Workspace.

There are two options to adding additional domains to K2:

In addition to these changes, it is also necessary to modify the Workspace web.config file so that the workspace can authenticate against the additional domains: see the section Modifying the Workspace Web Site for instructions.

Whenever domains are added, removed or edited, the K2 blackpearl service must be restarted.
Parent-child domains are supported. 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.

  1. Launch K2 Workspace and navigate to the following section: Management > [server] > User Managers > K2 > Domains. The default domain is displayed.

  2. Click the Add.
  3. Provide the NETBIOS and LDAP paths for the additional domain.

    FieldDescription
    NetBIOS NameThis is the NETBIOS name of the domain. You can locate this name by querying the general properties of the domain using the Active Directory Domains and Trusts tool:

    LDAP PathThis is the LDAP path of the target domain. This is usually in the format of LDAP://[distinguishedName] For example: LDAP://DC=denallix,DC=com. The exact value will depend on your AD configuration; check with your AD administrator to determine the LDAP path for the target domain.
  4. Restart the K2 blackpearl service (if you have multiple machines in the same farm, you need to restart the service on each server).

Editing Domains

  1. Highlight the domain in the list and click Edit.
  2. When the user dialog opens, enter the changes.
  3. Click OK.

Removing Domains

  1. Highlight the domain in the list and click Remove.
  2. Confirm the removal.
  3. Click OK.

    4. The default domain cannot be removed using K2 Workspace.

Registration of additional domains can also be performed by inserting the domain name and associated label into the SecurityLabel table in the HostServer database. The label has two components: Authentication Provider and Role Provider.

This document assumes some programming knowledge and familiarity with SQL Server.

If you have sub domains or domains in a different forest, you must add those domains to the same security label by modifying the AuthInit and RoleInit fields in the SecurityLabel table in the HostServer database. The following placeholders are used in the examples below:

NETBIOS Name LDAP String
[PARENTNETBIOSNAME] [PARENTNETBIOSNAME]
[CHILDNETBIOSNAME] LDAP://DC=ChildDomain1,DC=ParentDomain,DC=COM

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 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=&lt;DataSources&gt;
&lt;DataSource 
Path="LDAP://DC= ParentDomain,DC=COM" 
NetBiosName="[PARENTNETBIOSNAME]"/&gt;
&lt;DataSource 
Path="LDAP://DC=ChildDomain1,DC=ParentDomain,DC=com" 
NetBiosName="[CHILDNETBIOSNAME]"/&gt;
&lt;/DataSources&gt;

    The escape characters "&lt;" and "&gt;" must be used as specified in the example above. Only replace the DataSources substring of the RoleInit string.

Implementation Script

Run the following query 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=&lt;DataSources&gt;
	&lt;DataSource Path="LDAP://DC=[PARENTDOMAIN],DC=[PARENTDC]" NetBiosName="[PARENTNETBIOSNAME]"/&gt;
	&lt;DataSource Path="LDAP://DC=[CHILDDOMAIN],DC=[PARENTDOMAIN],DC=[PARENTDC]"
          NetBiosName="[CHILDNETBIOSNAME]"/&gt;
	&lt;/DataSources&gt;
	</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]"
  1. Execute the modified script against your K2 database.
  2. Restart the K2 blackpearl service (if you have multiple machines on the same farm, you need to restart the service on each server).

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" />

    The name attribute in the code shown above (the name attribute is shown in bold type) must be unique in the additional entry or an error occurs when browsing to the K2 Workspace site.

Important Considerations

When unused multiple domains are configured in K2 Workspace and a client event wizard is used in a workflow, there is a performance delay in the delivery of K2 notifications due to the notification passing through each domain. The notifications are more delayed as the number of unused domains increases. It is recommended that any unused domains be removed from K2 Workspace to increase performance.