The Configuration Manager provides access to server configuration settings such as licensing, current users, the path to the Host Server configuration file to name a few. For most custom security providers, the K2 Configuration Manager won't be of much use. The following code shows how to get a reference to the Configuration Manager through the serviceMarshalling argument of the Init() method.

// Get a reference to the Configuration Manager Object
_configurationManager = serviceMarshalling.GetConfigurationManagerContext();

The Host Server's Configuration file, located in [K2 Install]Host ServerinK2HostServer.config, can be used to store configuration values using .NET's built-in Configuration framework. For example, to add a connection string that's available to a custom security provider, the following connection string could be added to the K2HostServer.config file:

<add name="CustomProviderName.Connectionstring" connectionString="Data
Source=DLX;Database=CustomProviderDB; Integrated Security=True" />

To retrieve values stored in the Host Server's configuration file, use .NET's Configuration Manger class (System.Configuration.ConfigurationManager), like this:

string conn =
ConfigurationManager.ConnectionStrings["CustomProviderName.Connectionst
ring"].ConnectionString;

What's nice about using the Host Server's configuration file to store connection strings is that K2 will automatically encrypt the <connectionStrings> section, protecting any usernames and passwords that exist in that part of the configuration file using the Protected Configuration mechanisms provided in .NET 2.0.

The Security Manager provides access to different security features of the Host Server, including getting a reference to an authentication provider, access to cryptographic features of the Host Server, and the ability to enumerate the different security and role providers loaded in the Host Server. The following code demonstrates how to get a reference to the Security Manager:

// Get a reference to the Security Manager Object
_securityManager = ServerMarshaling.GetSecurityManagerContext();

When implementing a custom security provider, the ISecurityManager.GetSecurityLabelItem() method can be used to retrieve the initialization data for the custom security provider. This method allows a custom security provider to retrieve the XML-formatted custom configuration settings from the Host Server database.

string label = "SECURITY_LABEL";

// Retrieve the Initialization data from the Host Server
// database.
string initData = _securityManager.GetSecurityLabelItem("AuthInit", label) as string;

// Parse the initData to initialize the provider
. . .

The previous example shows how to retrieve the XML initialization data stored in the AuthInit column in the SecurityLabels table in the HostServer database where SecurityLabelName is equal to SECURITY_LABEL. The security label is the friendly name used to uniquely identify any security provider in K2.

In the introduction to the security provider API earlier in the chapter, it was pointed out that the IRoleProvider and the ISecurityProvider are separate object instances in memory, which means that fields initialized by one aren't accessible to the other, thus the need for multiple Init() methods. However, the Security Manager provides the ability for one provider to access another, and additionally the Security Manager can also provide a reference to any other security provider in the system, given the corresponding security label. The following example shows how to access another security provider running in the Host Server.

// Get a reference to the IRoleProvider for the given _securityLabel
IRoleProvider roleProvider =
           _securityManager.GetRoleProviderContext(_securityLabel);

// Get a reference to the IAuthenticationProvider for the given _securityLabel
IAuthenticationProvider authProvider =
            _securityManager.GetAuthenticationProviderContext(_securityLabel);

Another important item for use when developing a custom security provider is SourceCode.Logging.Logger. A reference to the logger allows security providers access to the main Host Server logging mechanism, allowing log messages to be written to the Debug Console, Host Server Log File, System Event log, and so on.

The following code shows how to get a reference to the Logger:

// Get a reference to the Logger Object
_logger = (Logger) ServiceMarshalling.GetHostedService(typeof(Logger).ToString());

The following table lists the logging methods of interest when creating a custom security provider:

The Host Server allows for different levels of logging based on the Logger's Severity configuration set in the [K2 Install Path]Host ServerinHostServerLogging.config file. When developing a custom security provider, make sure to enable the Debug Severity to the appropriate logging mechanism. This will allow for any debugging message output from the custom security provider being developed to be logged.

The IRoleProvider's initialization works very similarly to the IAuthenticationProvider initialization. The difference is that the IRoleProvider.Init() method is passed the RoleInit column name instead as the value for the roleInit parameter.

The following snippet is an example of an IRoleProvider.Init() method:

void IRoleProvider.Init(string label, string roleInit)
{
  // Retrieve the RoleInit data from the database
  roleInit =
     this._securityManager.GetSecurityLabelItem("RoleInit", label) as string;

  // Make sure roleInit has a value
  if (!string.IsNullOrEmpty(roleInit))
  {
     // extract Role Providers from Xml document
     . . .
  }
. . .
}

Once the values are extracted from the RoleInit XML document, they can be extracted and stored in field variables on the IHostableSecurityProvider object so that they can be used throughout the class.

Before exploring the specifics of some of the IRoleProvider methods, such as IRoleProvider.FindUsers() and IRoleProvider.FindGroups(), types for Users and Groups must be understood. The SourceCode.Hosting.Server.Interfaces namespace has four additional interfaces needed for building custom User and Role objects that work within K2 blackpearl. These interfaces are IUser, IUserCollection, IGroup, and IGroupCollection.

Figure 17-3 shows the class diagram for the IUser and IUserCollection. The interface defines the UserID and the UserName for the user within K2 blackpearl. The IUser.Properties dictionary can contain any attributes deemed useful, for example, phone number, address, cell phone, and so on.

Figure 17.3. Figure 17-3

The IRoleProvider.FindUsers() and IRoleProvider.GetUser() methods will return the IUser and IUserCollection objects. The following table defines the different IUser properties:

In order for an IUser object to function properly in the K2 environment, there are several required properties that MUST be added to the IUser.Properties collection. They are listed and defined in the following table:

Additionally, any number of custom properties can be added to provide additional user data to K2 Processes. For example, K2 allows support for instant messaging and the IUser.Properties dictionary contains an attribute called SipAccount to facilitate that functionality.

Here is a sample implementation of the IUser interface, with only the required properties:

class CustomUser : IUser
{
    private IDictionary<String, Object> _properties;
    private string _userID;
    private string _userName;

    #region IUser Members

    public IDictionary<string, object> Properties
    {
        get { return _properties; }
        set { _properties = value; }
    }

    public string UserID
    {
        get { return _userID; }
        set { _userID = value; }
    }

    public string UserName
    {
        get { return _userName; }
        set { _userName = value; }
    }

    #endregion

    public CustomUser(
        string securityLabel,
        string userName,
        string name,
        string description,
        string email,
        string manager)
    {
        _userID = securityLabel + ":" + userName;
        _userName = userName;

        _properties = new Dictionary<string, object>();
        _properties.Add("Name", name);
        _properties.Add("Description", description);
        _properties.Add("Email", email);
        _properties.Add("Manager", manager);
    }
}

Notice that the UserID is made up of a combination of the security label and the username. This guarantees that the UserID for a given provider is unique within the system. Also, the name, description, email, and manager properties are the minimum fields required to be added to an IUser to properly function within K2. Additional fields can be added to add support for additional functionality in your workflows.

&!@#$%^&*()+=-[]';,./{}|":<>?_~

-:.&$#@

The other class required is IUserCollection.

class CustomUserCollection : IUserCollection
{
    private Collection<IUser> _collection;

    public CustomUserCollection()
    {
        _collection = new Collection<IUser>();
    }

    #region IUserCollection Members

    public IUser this[int index]
    {
        get { return _collection[index]; }
    }

    #endregion

    #region IEnumerable Members

    public System.Collections.IEnumerator GetEnumerator()
    {
        return _collection.GetEnumerator();
    }

    #endregion

    public void Add(IUser user)
    {
        _collection.Add(user);
    }
}

That's as simple as it needs to be. More functionality can certainly be added, but the two classes stubbed out as shown in the preceding code would be enough to build a complete provider. Next, we explore how to retrieve users and groups.

Figure 17-4 shows the class diagram for the IGroup and IGroupCollection. This interface defines the GroupID and GroupName properties as well as a property collection called Properties used for any additional fields that will be made available to the K2 Processes.

Figure 17.4. Figure 17-4

The following table documents the class members of the IGroup interface:

The IRoleProvider.FindGroups() and IRoleProvider.GetGroup() methods return IGroup and IGroupCollection objects.

In order for an IGroup object to be compatible with K2, there are two required properties that MUST be added to the IGroup.Properties collection. They are listed and defined in the following table:

Additional custom fields can be added to the IGroup as well to facilitate additional functionality in K2 processes.

The actual implementation of the IGroup and IGroupCollection is almost identical to the IUser and IUserCollection implementations. The following is an implementation of the IGroup interface:

class CustomGroup : SourceCode.Hosting.Server.Interfaces.IGroup
{
    private string _groupID;
    private string _groupName;
    private IDictionary<string, object> _properties;

    #region IGroup Members

    public string GroupID
    {
        get { return _groupID; }
        set { _groupID = value; }
    }

    public string GroupName
    {
        get { return _groupName; }
        set { _groupName = value; }
    }

    public IDictionary<string, object> Properties
    {
        get { return _properties; }
        set { _properties = value; }
    }
    #endregion

    public CustomGroup(string securityLabel, string groupName, string description)
    {
        _groupID = securityLabel + ":" + groupName;
        _groupName = groupName;

        _properties = new Dictionary<string, object>();
        _properties.Add("Name", _groupID);
        _properties.Add("Description", description);
    }
}

Notice that the GroupID combines the group's name with the security label. This makes the GroupID unique in K2 for any security provider. Also, remember the Name and Description properties are required for any IGroup implementation. Additional properties can be added to add additional functionality into K2 blackpearl.

The following code is a sample implementation of the IGroupCollection interface:

class CustomGroupCollection : SourceCode.Hosting.Server.Interfaces.IGroupCollection
{
    Collection<IGroup> _groups;

    #region IGroupCollection Members

    public SourceCode.Hosting.Server.Interfaces.IGroup this[int index]
    {
        get { return _groups[index]; }
    }

    #endregion

    #region IEnumerable Members

    public System.Collections.IEnumerator GetEnumerator()
    {
        return _groups.GetEnumerator();
    }

    #endregion

    public CustomGroupCollection()
    {
        _groups = new Collection<IGroup>();
    }

    public void Add(IGroup group)
    {
        _groups.Add(group);
    }
}

These sample implementations of the IGroup and IGroupCollection interfaces contain all the functionality needed to use them in an actual security provider.

There are two methods defined on the interface that retrieve one user or one group, each with one overload for extra metadata:

Each is defined as follows:

// Interface Method Definitions for GetUser
IUser GetUser(string name);
IUser GetUser(string name, string extraData);

// Interface Method Definitions for GetGroup()
IGroup GetGroup(string name);
IGroup GetGroup(string name, string extraData);

The following table defines both FindUser and FindGroup:

IRoleProvider.GetUser() is called, for example, immediately after an AuthenticateUser() method is run to retrieve user information.

In order to search the underlying Role provider store for users and groups, a dictionary of properties is provided to the Find methods with the corresponding search criteria. In order to be able to implement the search properly, K2 needs to know what properties (required and custom) have been defined for the provider.

K2 is able to discover what properties and their corresponding types are defined on the IUser and IGroup objects of a security provider by calling the IRoleProvider.QueryUserProperties() and IRoleProvider.QueryGroupProperties() methods. Before every search, K2 queries the properties and then fills in the search criteria to the appropriate ones.

The basic implementation of the QueryUserProperties() method, taking into account the required properties, would look like this:

public Dictionary<string, string> QueryUserProperties()
{
    Dictionary<string,string> userProperties = new Dictionary<string, string>();
    userProperties.Add("Name", "System.String");
    userProperties.Add("Description", "System.String");
    userProperties.Add("Email", "System.String");
    userProperties.Add("Manager", "System.String");
    return _userProperties;
}

A more flexible option, other then hardcoding the list into the Role provider, might be to store a list of the properties in the RoleInit XML document so that the list could be changed without recompiling. This is exactly how the ADUM security provider is configured.

Similarly, the most basic implementation of the QueryGroupProperties() method would look like this:

public Dictionary<string, string> QueryGroupProperties()
{
    Dictionary<string,string> groupProperties = new Dictionary<string, string>();
    groupProperties.Add("Name", "System.String");
    groupProperties.Add("Description", "System.String");
    return groupProperties;
}

Now that K2 knows what properties the custom IUser and IGroup objects contain, it can now successfully search for them.

The method IRoleProvider.FindUser() retrieves a collection of users from the security provider's data store — SQL Server, LDAP, or so forth. There are two interface signatures; one requires two arguments, and the other requires three arguments:

IUserCollection IRoleProvider.FindUsers(
     string groupName,
     IDictionary<string, object> properties
);

IUserCollection IRoleProvider.FindUsers(
     string groupName,
     IDictionary<string, object> properties,
     string extraData
);

The following table defines each argument:

When the groupName argument is provided, it will contain the exact name of the group to search for. This means that the search criterion is not needed, so the properties dictionary can be ignored. Likewise, if the groupName argument is null or empty, then a search is being performed, and the exact group name is unknown, so the search criteria will be in the properties dictionary. If both the groupName and the properties dictionary items don't have any values, then a complete wildcard search should be performed of all users in the underlying security provider data store.

The IRoleProvider.FindGroups() functions very similar to the IRoleProvider.FindUsers() previously described. The following code uses the two interface signatures; one requires two arguments, and the other requires three:

IGroupCollection FindGroups(
     string userName,
     IDictionary<string, object> properties
)
IGroupCollection FindGroups(
     string userName,
     IDictionary<string, object> properties,
     string extraData
);

The following table describes each argument:

When the userName argument is provided to the FindGroups() method, it will contain an exact username that was previously resolved. This allows for a direct retrieval of the user, and the properties dictionary of search parameters can be ignored. When the userName argument is null or empty, then the search parameters will contain the attributes to search on that match the properties of the IGroup.Properties dictionary. If the userName argument is empty and there are no values for any of the keys in the properties dictionary, then FindGroups should return all groups from the underlying security provider data store.

To demonstrate how searching works between K2 and any security provider, we look to the K2 Workspace as it contains Search functionality in many places.

For an example of where IRoleProvider.FindUsers() and IRoleProvider.FindGroups() are called, see Figure 17-5, which shows the K2 Workspace Search Screen that is used to assign Process Rights to users and groups.

Figure 17.5. Figure 17-5

When the user fills out the search criteria and clicks the Search button, the K2 Workspace then calls the K2 server and asks the security provider for the registered label, in this case the provider registered with the security label K2, to do a partial search for all users and groups whose name starts with "Adm". Both FindUsers() and FindGroups() are called. The groupName and userName arguments will both be null; the properties dictionary for both will contain all the properties, but only the Name property will have a value set; and based on the screen above the value for Name will be "Adm*" because the Search Criteria drop-down has the "Starts With" option selected. Notice it found both a user named "Administrator" and a group called "Administrators."

Four possible options control where the wildcard will show up (as shown in Figure 17-6).

Figure 17.6. Figure 17-6

The Workspace will add a wildcard in different places, depending on which item is selected in the drop-down shown in Figure 17-6:

Make sure to convert the asterisks' wildcard to the appropriate search symbol used by the underlying security provider data store. For example, if you are passing the phrase with the asterisks' wildcard to an LDAP-based system, the asterisks will work just fine as the wildcard. However, if SQL Server is the underlying data store, the asterisks will need to be converted to percent (%) characters before they can be passed along.

Destination queue functionality is a remnant from K2.net 2003 so the functionality provided in IRoleProvider.ResolveQueue() is used to maintain backward compatibility with K2.net 2003. In the case where you have upgraded a K2.net 2003 process or have migrated a K2.net 2003 process to K2 blackpearl, when a process utilizes a destination queue it will call IRoleProvider.ResolveQueue(). In most situations for many custom security providers used in K2.net 2003, it's rare that this method will need to be implemented.

Once K2 blackpearl SP2 is released, any custom security provider built for K2.net 2003 should be able to be migrated to K2 blackpearl under its own security label. Some manual steps will need to be performed in K2 blackpearl to register the custom security provider from K2.net 2003 into K2 blackpearl.

The following table briefly describes how IRoleProvider.ResolveQueue() should function:

The following code shows a sample of the DestinationQueues XML document:

<DestinationQueues>
  <DestinationQueue>
    <SendToBehaviour Name="Send To" Type="sendto">
      <SendToItem Name="DENALLIXSales " Type="group"
                Path="LDAP://CN=Sales,CN=Users,DC=denallix,DC=com" />
      <SendToItem Name="DENALLIXOperations" Type="organizationalunit"
                Path="LDAP://OU=Operations,OU=Depts,DC=denallix,DC=com" />

</SendToBehaviour>
    <SendToBehaviour Name="Send To Manager" Type="sendtomanager">
      <SendToItem Name="DENALLIXjanet" Type="user"
        Path="LDAP://CN=Janet Brown,OU=Operations,OU=Depts,DC=denallix,DC=com"         />
    </SendToBehaviour>
  </DestinationQueues>
</DestinationQueue>

The DestinationQueues XML document contains the following elements:

An implementation of IRoleProvider.ResolveQueue() will need to consume the DestinationQueues XML document and resolve all the users based on the behaviors defined in the SendToBehaviour elements using the SendToItems elements.

If the custom security provider has any dependencies, they must be deployed and configured before integrating the security provider library into the Host Server. For example, if the custom security provider requires that a database be created and populated with data, make sure to stage that first.

After all the external dependencies are set up and configured, stop the K2 blackpearl Service.

After the service is stopped, any K2 blackpearl-specific configuration settings used by the custom security provider need to be installed–for instance, if the security provider depends on Application Configuration settings in the K2HostServer.config, appSettings section or it may have a database connection string stored in the connectionStrings section.

In the K2 blackpearl Host Server folder, there is a subfolder called securityproviders. This is where the assembly that implements the IHostableSecurityProvider interface goes. After stopping the K2 blackpearl server, copy the new security provider assembly into the [K2 Install Folder]K2 blackpearlHost ServerBinsecurityproviders folder. Make sure to include copying any non-K2 assemblies that aren't installed in the GAC that the custom security provider references.

Here are the steps to register an assembly in the Host Server database for version 0807 and later:

Once the Security Provider library has been copied and the configuration settings have been set up, start the K2 blackpearl Service. On service startup, the K2 server polls the securityproviders folder. If the server finds an assembly that contains an object that implements the IHostableSecurityProvider interface, the Host Server will insert a new record in the SecurityProviders table in the HostServer database for the new provider.

To finish integrating the custom security provider into K2, the HostServer database needs to be updated to set the security label name as well as the authentication and roles initialization data (AuthInit and RoleInit columns). Make sure to give the server a little bit of time to record the new security provider in the database before running the following script; the script will fail if the K2 server either doesn't detect the new security provider for some reason, or if it hasn't had enough time to detect and add the record to the SecurityProviders table.

The following sample SQL script can be modified to add a new security label to the HostServer database:

declare @securityProviderName nvarchar(255)
declare @securityLabel nvarchar(255)
declare @authProviderID uniqueidentifier
declare @securityProviderID uniqueidentifier
declare @securityLabelID uniqueidentifier
declare @authInit xml
declare @roleInit xml
declare @defaultLabel bit

USE [HostServer]

-- This is the security label that will be seen in the K2 Workspace
SET @securityLabel = 'Custom Label Name'

-- This is the Class name of the Provider
SET @securityProviderName = 'Custom.Auth.Provider'

-- Generate a new GUID
SET @securityLabelID = newid()

-- Set up the AuthInit xml document used to initialize the
-- Authentication Provider
SET @authInit = '<authInit />'

-- Set up the RoleInit xml document used to initialize the
-- Roles Provider
SET @roleInit = '<roleProvider><init /></roleProvider>'

-- This is not the system default Label
SET @defaultLabel = 0

-- Extract the Authentication SecurityProviderID for the newly
-- added Provider
SELECT
  @authProviderID = [SecurityProviderID]
FROM
  [SecurityProviders]
WHERE
   [ProviderClassName] = @securityProviderName

-- Extract the Roles SecurityProviderID for the newly
-- added Provider
SELECT
  @securityProviderID = [SecurityProviderID]
FROM
  [SecurityProviders]
WHERE
   [ProviderClassName] = @securityProviderName

-- Link the SecurityProvider to a new Security Label
INSERT INTO [SecurityLabels]
(
     [SecurityLabelID],
     [SecurityLabelName],
     [AuthSecurityProviderID],
     [AuthInit],
     [RoleSecurityProviderID],
     [RoleInit],
     [DefaultLabel]
)
VALUES
(
     @securityLabelID,
     @securityLabel,
     @authProviderID,
     @authInit,
     @roleProviderID,
     @roleInit,
     @defaultLabel
)

At this point, the custom security provider is installed. Check the HostServer log file. There should be an entry making note of the security providers that are loaded. If the K2 blackpearl Service starts and then stops, most likely an exception has occurred in one or multiple Init() methods in the provider. These types of issues can be more difficult to troubleshoot because the service isn't up long enough to attach the debugger and the logger may not be up and running to capture messages written to the Logger.

To debug a provider, make sure to copy the .pdb file into the [K2 Install Folder]Host Serverinsecurityprovider folder alongside the security provider assembly.

To debug a custom security provider:

If you are developing on a K2 blackpearl server, a decent debugging approach is to configure the Security Provider project in Visual Studio to start the K2 server in Console mode by launching K2HostServer.exe. This will require configuring the K2 Service to run successfully under your developer account instead of the normal K2 blackpearl Service Account. Make sure to stop the K2 Service before using this approach.

To configure Visual Studio to directly start and debug K2HostServer.exe:

Now when you press the Start Debugging toolbar button in Visual Studio, it will start the K2 Host Server with the debugger attached.

Additionally, if you're developing on the K2 server, you can create a post-build event in Visual Studio to copy the latest built version of the custom security provider to the Host Serverinsecurityproviders folder in the K2 Installation folder. The security provider has been successfully installed.

To configure Visual Studio to copy the latest version of the security provider assembly and debugging symbols (..pdb file) to the securityproviders folder after a successful build:

If the files are unable to be copied successfully, a build error will be reported. Check the Build Output window to trouble-shoot post-build event Errors. Most likely, any post-build event errors encountered will be because the K2 Host Service is running and has a handle on the custom security provider file, locking it.

There are a couple of other things to avoid when directly debugging on the server. Do not use the K2 Object Browser in the same Visual Studio session you are debugging. It gets deadlocked and the Host Server will have to be killed. Start a second Visual Studio session and use the Object Browser in there.

To verify that the provider is working: