Introduction

K2 blackpearl allows for multiple security providers to be used for authentication purposes. This allows a customer’s security provider to be modified when business requirements change, or to allow for multiple security providers for use with K2 Host Server.

Note: A security provider is where users and groups are stored, and where authentication is performed.

This document will walk you through how to register a security provider. Typically, the authentication mechanism is Active Directory (AD) or SQL. Both AD and SQL providers ship in the box with K2 blackpearl. However, custom security providers can be written for other sources (such as Oracle, LDAP).

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

How to Register a Security Provider

 
To register a new security provider, two tables in the HostServer database must be modified:
  • SecurityProviders – In order to register the security provider as a Type that implements IHostableSecurityProvider
  • SecurityLabels – This table maps the security provider to a label and stores initialization data
 
In this example, a single security provider is used for both authentication and user and group definition.
 

Code the Security Provider

 
In order to implement a new security provider, you will first have to code the authentication methods and role providers. Your code must implement the IHostableSecurityProvider interface.
Note: Please see the Download section for the Sample Security Provider attachment. In this sample, there are some comments in the methods that must be implemented for the provider. This is a sample for reference only.
 
After developing and testing your security provider, compile your code. Copy the assembly into the following folder:

                C:\Program Files\K2 blackpearl\Host Server\Bin\SecurityProviders
 
In order for the K2 Host Server to register the new security provider, you will need to restart the K2 blackpearl Server service.
 

Register the Security Provider in the Database

 
The next step is to insert the security provider information into the database. The following needs to be inserted into the HostServer database:
Note: The following code sample has place holders for the security provider information. They are marked with {}. Be sure to replace the place holder text with your security provider’s information.
 
INSERT INTO [SecurityProviders]
           ([SecurityProviderID]
           ,[ProviderClassName])
     VALUES
           (newid()
           ,'{Full Name of your Security Provider Class}')
 
 
 
INSERT INTO [SecurityLabels]
           ([SecurityLabelID]
           ,[SecurityLabelName]
           ,[AuthSecurityProviderID]
           ,[AuthInit]
           ,[RoleSecurityProviderID]
           ,[RoleInit]
           ,[DefaultLabel])
     VALUES
            ('6E5DEBDF-00A1-4fe8-9F6B-F0B732BCD1DC'
           ,'{LabelName}'
           ,'{GUID of SecurityProvider for Authentication Services(IAuthenticationProvider)}'
           ,'{Initialization data for the Authentication Provider instance}'
           ,'{GUID of the SecurityProvider for User and Group Listing services
             (IRoleProvider)
}'
           ,'{Initialization data for the User and Group listing provider}'
           ,1)


Important: Please note it is imperative that the [AuthInit] and [RoleInit] values in the [SecurityLabels] table are NOT NULL.
 

Resolving Users in the Context of Multiple Labels


When multiple security providers are used, multiple labels will be registered with K2. This should be taken into account when creating a new security provider.
Note: The Label is a user friendly representation of the Security Provider.
In the case of Active Directory, the label may differ from the actual domain name. Usually, one user manager is available per domain. When multiple domains have been configured, there may be scenarios where users may or may not exist in each domain. Therefore, extra care should be taken when testing to look for these special cases.
 
The K2 tag or identifier is a security label assigned to the User Manager instance. The UserManager instances must be labeled so that the users are uniquely identifiable.
Note: When no security tag or label is specified, the default domain label will be used.
Scenarios may exist as below, which resolves worklist items for BPUser. For this example, K2DEMO is the default domain:
 
  • BPUser – This user will resolve with the default label (K2), with the default domain (K2DEMO). The internal result used by K2 will be K2:K2DEMO\BPUser
  • K2DEMO\BPUser – This user will resolve with the default label (K2). The internal result used by K2 will be K2:K2DEMO\BPUser
  • K2:K2DEMO\BPUser – This is the fully qualified name with the label and domain specified. K2 will use this result as is.