Configuring the K2 LDAP User Manager

This topic lists and describes LDAP settings, which are used to configure the K2 LDAP user manager. A sample script at the end of the topic can be edited for your environment and used to configure your K2 LDAP user manager.

There are many available settings mainly due to the nature of LDAP and its various implementations. Each user directory implements different methodologies, and, for example, very few AD-based LDAP queries work on Novell. Once you understand these settings, you should be able to make K2 work with your user directory.

LDAP Setting Description
LdapConnection
  • LdapServer: This is the server or directory name (e.g. “denallix.com” or “mydns”). This setting is similar the server setting in the SharePoint configuration.
  • LdapServerPort: This is the port for the connection. This can be 0 for the default (usually 389) or you can set a different one, such as for SSL (usually 636). This setting is similar the port setting in the SharePoint configuration.
  • LdapAuthTypeConnect: This is the type of connection K2 makes whenever it queries the directory (e.g. for user information, group membership etc.). “Negotiate” would be the simplest for AD, but if you need a username and password then Basic would be an alternative. For more information see AuthType Enumeration (MSDN).

    This value should be set to Negotiate as it will use NTLM or Kerberos depending on the underlying requirement.

  • LdapAuthTypeAuthenticateUser: This is the type of connection K2 makes whenever it authenticates a user (giving their credentials). “Negotiate” would be the simplest for AD, but if you need a username and password then Basic would be an alternative. For more information see AuthType Enumeration (MSDN).

    This value should be set to Negotiate as it will use NTLM or Kerberos depending on the underlying requirement.

  • LdapResolveAuthenticationUserToDistinguishedName: In some directories (e.g. Novell) users are logged on with their distinguished name instead of their actual username. If this is true, K2 takes the user’s name and queries the directory in order to retrieve the distinguished name. If users are logging in with their distinguished names (e.g. passing it in the K2 connection string), then this should be false as there’s no need to resolve it.
  • LdapAutoBind: Whether or not explicit binding is avoided in the connection (LDAP connects first, and then binds to validate the connection). This is a compatibility setting and can usually be left false.
  • LdapScope: This is the scope of user searches. Unless you have specific requirements (such as only searching in a root OU), then “Subtree” would be the recommended option. For more information see SearchScope Enumeration (MSDN). This setting is similar to the scope setting in the SharePoint configuration.
  • LdapConnectIntegrated: Whether or not the connection has integrated authentication. If LdapAuthTypeConnect is something like “NTLM”, this would need to be true. This only correlates to K2’s own connections, as end users will not make integrated connections.
  • LdapConnectUserName: If the LDAP directory doesn’t support integrated connections or you want to use an account different to the K2 Service account, then K2 will use this user to connect to query the directory. Some directories support connections with blank username / password for general queries, but you may find that you only receive a limited number of attributes.
  • LdapConnectUserPassword: The password for the above user.
  • LdapTimeout: A timeout for LDAP queries (in seconds). 0 means to use the default.
  • LdapProtocolVersion: The LDAP protocol version to use. 3 is recommended, but 2 should also work.
  • LdapSsl: Whether the connection uses SSL (ensure that the port used reflects this). This setting is similar to the useSSL setting in the SharePoint configuration.
  • LdapServerCertificatePath: If you are using SSL, this is an optional value that allows you to verify the LDAP server’s SSL certificate (to ensure someone isn’t spoofing your user directory). This provides a local path (on the K2 server) where the certificate can be found. If no certificate is supplied and you’re doing SSL, then K2 will assume that you don’t want to check it and SSL will proceed regardless.
LdapUserSearchFormatString This is the LDAP query used to search for users. It should include a placeholder “{0}” for where the user's ID should be inserted. Don’t include any wildcards, as these are handled automatically. As this is in XML, any reserved XML characters (e.g. &) should be escaped. For example:
(&(objectClass=Person)(objectCategory=User)(samAccountName={0})
LdapUserGroupSearchFormatString This is the LDAP query used to search for users that belong to a specific group. It should include a placeholder “{0}” for where the group’s ID should be inserted. Don’t include any wildcards, as these are handled automatically. As this is in XML, any reserved XML characters (e.g. &) should be escaped. For example, to return users from this specific group and all nested groups:
(memberOf :1.2.840.113556.1.4.1941:={0})
For more information see Search Filter Syntax (MSDN).
LdapGroupSearchFormatString This is the LDAP query used to search for groups. It should include a placeholder “{0}” for where the user’s ID should be inserted. Don’t include any wildcards, as these are handled automatically. As this is in XML, any reserved XML characters (e.g. &) should be escaped. For example:
(&(objectCategory=Group)(samAccountName={0}))
LdapGroupMemberSearchFormatString This is the LDAP query used to search for groups of which the user is a member. It should include a placeholder “{0}” for where the user’s ID should be inserted. Don’t include any wildcards, as these are handled automatically. As this is in XML, any reserved XML characters (e.g. &) should be escaped. For example, to return groups and all nested groups of which the user is a member:
(member:1.2.840.113556.1.4.1941:={0})
For more information see Search Filter Syntax (MSDN).
LdapUserBaseObject This is the LDAP base object from which all user searches are made. Make sure that this correlates correctly to your LdapScope setting above. This setting is similar to the userContainer setting in the SharePoint configuration. For example:
dc=denallix,dc=com
LdapGroupBaseObject This is the LDAP base object from which all group searches are made. Make sure that this correlates correctly to your LdapScope setting above. This setting is like the groupContainer setting in the SharePoint configuration. For example:
dc=denallix,dc=com
LdapUserAttributes The following is the set of attributes that are used in your directory. The available settings for each attribute are:
  • K2Name: If K2 supports this attribute, then this is the name it knows it by. You should stick to the names supplied otherwise K2 will not know how to use the property. This name is case sensitive.
  • LDAPName: This is the name used in the LDAP directory (e.g. samAccountName). LDAP is generally case in-sensitive, however care should be taken with setting these properties as it is possible to have case sensitive implementations. If this value is blank, K2 will take the distinguished name of the object.
  • ObjectType: This is so that K2 knows what it’s retrieving from this property. Currently, only System.String (a string value) and System.Collections.ArrayList (a collection of values) are supported.
  • Multiline: Typically, properties are only found on the first line. However, some values (such as description) can be on multiple lines and therefore setting this property will make K2 concatenate these values.
  • FullOnly: If this item is of something that is time consuming to retrieve (e.g. group members, which all have to be resolved), setting this to true means it will only be retrieved in full searches such as when one specific user is retrieved and not when a set of users are being searched for. If you find delays in searches, set this to true on as many properties as possible unless you find issues in K2 functionality.
  • SearchQuery: Some LDAP properties only include a distinguished name (e.g. memberOf). If you want to search for the user / group of that distinguished name, in order to replace this value with one K2 will recognize, you can supply a query here and it will use this for the search. This is always a distinguished name and because of that there is no need for any placeholders, so it should be a complete query.
  • SearchResultProperty: If you are using a SearchQuery, this specifies the property of the returned object you want to retrieve (e.g. samAccountName). This will then replace the distinguished name originally retrieved for the attribute.
    The minimum set of required attributes for resolving users and groups is ID, Name, DistinguishedName and Description (where ID and Name are usually the same). Others may be used in K2 and therefore should be included where possible (e.g. e-mail, manager), but they are not required for base functionality.
    If you find that your queries are returning only a small number of attributes, it may mean that the user you connecting with does not have sufficient privileges.
LdapGroupAttributes As above, except these attributes would be the ones returned for groups.

The K2LDAP label will be visible in K2 where labels normally appear such as Management Console in K2 Workspace.

The following example is for the fictitious Denallix.com domain and is inserted into the SecurityLabels table of the K2 database. You must change some of the values below to match your environment. This is the same XML that is included in the downloadable script file.

<AuthInit>
<LdapConnection
LdapServer="dlx.denallix.com"
LdapServerPort="389"
LdapSsl="false"
LdapAuthTypeConnect="Negotiate"
LdapAuthTypeAuthenticateUser="Negotiate"
LdapResolveAuthenticationUserToDistinguishedName="false"
LdapAutoBind="false"
LdapScope="Subtree"
LdapConnectIntegrated="true"
LdapConnectUserName=""
LdapConnectUserPassword=""
LdapTimeout="0"
LdapProtocolVersion="3"
LdapServerCertificatePath="" />
<LdapUserBaseObject>dc=denallix,dc=com</LdapUserBaseObject>
<LdapUserSearchFormatString>(&amp;(objectClass=Person)(objectCategory=User)(samAccountName={0}))</LdapUserSearchFormatString>
<LdapUserGroupSearchFormatString>(memberOf:1.2.840.113556.1.4.1941:={0})</LdapUserGroupSearchFormatString>
<LdapUserAttributes>
<K2LdapMapping K2Name="ID" LdapName="samAccountName" ObjectType="System.String" />
<K2LdapMapping K2Name="Name" LdapName="samAccountName" ObjectType="System.String" />
<K2LdapMapping K2Name="Description" Multiline="true" LdapName="description" ObjectType="System.String" />
<K2LdapMapping K2Name="Email" LdapName="mail" ObjectType="System.String" />
<K2LdapMapping K2Name="DistinguishedName" LdapName="distinguishedName" ObjectType="System.String" />
<K2LdapMapping K2Name="ObjectSID" FullOnly="true" LdapName="objectSID" ObjectType="System.String" />
<K2LdapMapping K2Name="CommonName" LdapName="cn" ObjectType="System.String" />
<K2LdapMapping K2Name="UserPrincipalName" LdapName="userPrincipalName" ObjectType="System.String" />
<K2LdapMapping K2Name="Manager" FullOnly="true" LdapName="manager" ObjectType="System.String" SearchQuery="(&amp;(objectClass=Person)(objectCategory=User))" SearchResultProperty="samAccountName" />
<K2LdapMapping K2Name="SipAccount" LdapName="msRTCSIP-PrimaryUserAddress" ObjectType="System.String" />
<K2LdapMapping K2Name="DisplayName" LdapName="displayName" ObjectType="System.String" />
<K2LdapMapping K2Name="TelephoneNumber" LdapName="telephoneNumber" ObjectType="System.String" />
<K2LdapMapping K2Name="Mobile" LdapName="mobile" ObjectType="System.String" />
<K2LdapMapping K2Name="HomePage" LdapName="wWWHomePage" ObjectType="System.String" />
<K2LdapMapping K2Name="FaxNumber" LdapName="facsimileTelephoneNumber" ObjectType="System.String" />
<K2LdapMapping K2Name="HomePhone" LdapName="homePhone" ObjectType="System.String" />
<K2LdapMapping K2Name="IPPhone" LdapName="ipPhone" ObjectType="System.String" />
<K2LdapMapping K2Name="StreetAddress" LdapName="streetAddress" ObjectType="System.String" />
<K2LdapMapping K2Name="City" LdapName="l" ObjectType="System.String" />
<K2LdapMapping K2Name="Country" LdapName="c" ObjectType="System.String" />
<K2LdapMapping K2Name="State" LdapName="st" ObjectType="System.String" />
<K2LdapMapping K2Name="Title" LdapName="title" ObjectType="System.String" />
<K2LdapMapping K2Name="Department" LdapName="department" ObjectType="System.String" />
<K2LdapMapping K2Name="Company" LdapName="company" ObjectType="System.String" />
<K2LdapMapping K2Name="Office" LdapName="physicalDeliveryOfficeName" ObjectType="System.String" />
<K2LdapMapping K2Name="ManagedUsers" FullOnly="true" LdapName="managedUsers" SearchQuery="(&amp;(objectClass=Person)(objectCategory=User))" SearchResultProperty="samAccountName" ObjectType="System.Collections.ArrayList" />
<K2LdapMapping K2Name="Groups" FullOnly="true" LdapName="memberOf" SearchQuery="(objectCategory=Group)" SearchResultProperty="samAccountName" ObjectType="System.Collections.ArrayList" />
</LdapUserAttributes>
<LdapGroupBaseObject>dc=denallix,dc=com</LdapGroupBaseObject>
<LdapGroupSearchFormatString>(&amp;(objectCategory=Group)(samAccountName={0}))</LdapGroupSearchFormatString>
<LdapGroupMemberSearchFormatString>(member:1.2.840.113556.1.4.1941:={0})</LdapGroupMemberSearchFormatString>
<LdapGroupAttributes>
<K2LdapMapping K2Name="ID" LdapName="samAccountName" ObjectType="System.String" />
<K2LdapMapping K2Name="Name" LdapName="cn" ObjectType="System.String" />
<K2LdapMapping K2Name="Description" Multiline="true" LdapName="description" ObjectType="System.String" />
<K2LdapMapping K2Name="Email" LdapName="mail" ObjectType="System.String" />
<K2LdapMapping K2Name="DistinguishedName" LdapName="distinguishedName" FullOnly="true" ObjectType="System.String" />
<K2LdapMapping K2Name="ObjectSID" LdapName="objectSID" FullOnly="true" ObjectType="System.String" />
<K2LdapMapping K2Name="Member" LdapName="member" FullOnly="true" SearchQuery="(&amp;(objectClass=Person)(objectCategory=User))" SearchResultProperty="samAccountName" ObjectType="System.Collections.ArrayList" />
</LdapGroupAttributes>
</AuthInit>
DECLARE @SecurityLabelID UNIQUEIDENTIFIER = NEWID(); --Assigning new GUID
DECLARE @AuthSecurityProviderID UNIQUEIDENTIFIER = NEWID(); --Assigning new GUID
DECLARE @AuthInit XML = @XmlConfig;
DECLARE @RoleSecurityProviderID UNIQUEIDENTIFIER = @AuthSecurityProviderID;
DECLARE @RoleInit XML = @XmlConfig;
DECLARE @DefaultLabel BIT = NULL; --1 = true, NULL and 0 = false
DECLARE @ProviderClassName NVARCHAR(200) = 'SourceCode.Security.Providers.LdapProvider.Trusted.Ldap';
DECLARE @SPProviderID UNIQUEIDENTIFIER;
-- UPDATE TABLES
DELETE FROM [HostServer].[SecurityProvider] WHERE ProviderClassName = @ProviderClassName;
DELETE FROM [HostServer].[SecurityLabel] WHERE SecurityLabelName = @SecurityLabelName;
INSERT INTO [HostServer].[SecurityProvider] VALUES (@AuthSecurityProviderID, @ProviderClassName);
INSERT INTO [HostServer].[SecurityLabel] VALUES (@SecurityLabelID, @SecurityLabelName, @AuthSecurityProviderID, @AuthInit, @RoleSecurityProviderID, @RoleInit, @DefaultLabel);
SELECT @SPProviderID = [SecurityProviderId] FROM [HostServer].[SecurityProvider] WHERE [ProviderClassName] = N'SourceCode.Security.Providers.SharePoint.SharePointProvider';
IF NOT EXISTS (SELECT 1 FROM [HostServer].[GroupProvider] WHERE [SecurityLabelID] = @SecurityLabelID)
BEGIN
INSERT INTO [HostServer].[GroupProvider]
(
[GroupProviderID]
,[SecurityLabelID]
,[SecurityProviderID]
,[Name]
,[Init]
)
VALUES
(
NEWID()
,@SecurityLabelID
,@SPProviderID
,'*'
,'<init><label name="SP" /></init>'
)
END

To register the LDAP User Manager, the SecurityLabels table in the database must be modified. This table stores the security label, security provider and authorization / role initialization data for the user manager. The K2 User Manager sample scripts available for download allow you to add or remove a LDAP User Manager. Be sure to edit the scripts to fit your configuration before executing them. Follow the steps below to add the LDAP User Manager.

  1. Download and extract the K2 User Manager sample scripts.
  2. Open the K2 LDAP User Manager (Forms - Setup).sql script and edit it for your environment.
  3. Execute the K2 LDAP User Manager (Forms - Setup).sql script from Microsoft SQL Server Management Studio against the K2 database.
  4. Refresh the User Manager Cache.
  5. Restart the K2 blackpearl Server service.

The example scripts contain references to the DLX SQL instance, the K2HostServer database and the Denallix.com domain. Please edit the .sql files to replace these values before executing.