Kentico CMS 6.0 Developer's Guide

Security handler (CustomSecurityHandler class)

Security handler (CustomSecurityHandler class)

 Previous topic Next topic Mail us feedback on this topic!  

Security handler (CustomSecurityHandler class)

 Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

The security handler allows you to integrate external user databases and modify the authentication and authorization process.

 

Any code added to the handlers is executed after the standard authentication or authorization checks performed by the system.

 

The class contains handlers for the following events:

 

•OnAuthentication - triggered when a user attempts to sign in with a name and password.

•OnResourceAuthorization - triggered when the system checks if a user is authorized to access a module.

•OnUIElementAuthorization - triggered when the system checks if a UI element should be displayed to a user.

•OnClassNameAuthorization - triggered when the system checks if a user is authorized to access a particular document type.

•OnTreeNodeAuthorization - triggered when the system checks if a user is authorized to access a document in the content tree.

•OnFilterDataSetByPermissions - triggered when a DataSet is filtered according to the permissions or custom personalization rules of the current user.

 

Example

 

In the following example, you will learn how to integrate external user authentication using the custom security handler.

 

The handler of the OnAuthentication event will be used for this purpose. It has the following parameters:

 

•object userInfo - an object representing the user attempting to log in. This object is returned as the result of the standard authentication check performed by the system. It is null if the default authentication failed.

•string username - a string containing the username entered during the login attempt.

•string password - a string containing the password entered during the login attempt.

 

The handler must return an object representing the user if external authentication using the entered credentials is successful, or null to indicate that authentication failed.

 

Now modify the code of the OnAuthentication handler according to the following:

 

[C#]

 

public override object OnAuthentication(object userInfo, string username, string password)
{

    // Check if the user was authenticated by the system
    if (userInfo != null)
    {
        return userInfo;
    }
 
    // Sample external user credentials
    UserInfo usr = null;
 
    // Authenticate against the external source
    if ((username.ToLower() == "externaluser") && (password == "pass"))
    {
        // Create base user record if external authentication is successful
        usr = new UserInfo();
        usr.IsExternal = true;
        usr.UserName = username;
        usr.FullName = "externaluser fullname";
        usr.Enabled = true;
 
        // Initialize a hash table mapping roles to sites for the user
        Hashtable rolesTable = new Hashtable();
       
        // Get the code name of the current site
        string siteName = CMSContext.CurrentSite.SiteName;
 
        // Assign the user to the current site
        usr.SitesRoles[siteName.ToLower()] = rolesTable;
 
        // Add new role "external role" to the hash table to assign it to the user
        rolesTable["external role"] = 0;
    }
 
    // Return the user info object
    return usr;
}

 

For simplicity, the example does not use any particular database. Instead, it only checks if the current user name and password are equal to some constants. In a real‑world scenario, you would need to replace this condition with code that checks if the user name with the given password is authenticated against your external database. Also, instead of simply assigning the user to a role named external role, you would have to implement code that checks the external database for any roles that the authenticated user is a member of and assigns them dynamically.

 

Once this is done, save the changes and Build the CustomEventHandler project. The system will now be able to perform authentication according to user data from an external source.

 

The roles created during this external authentication will not have any permissions assigned by default, so they will not authorize the user to perform any actions. You can programmatically check if a user belongs to a role using the CMS.CMSHelper.CurrentUserInfo.IsInRole(string roleName, string siteName) method and implement your own security logic in the other event handlers under the CustomSecurityHandler class.

 

However, we recommend importing all external roles into the CMS_Role table of the website's Kentico database. Then you can configure the appropriate permissions for these roles. This way, you will be able to fully use the built‑in security model of Kentico CMS together with external users.