How do I implement NCache security programmatically?

Security can be implemented programmatically by initializing a Credentials object with a username and password, then assigning it to the UserCredentials property of CacheConnectionOptions before calling GetCache.

What causes an Alachisoft.NCache.Runtime.Exceptions.SecurityException?

This exception is triggered by unauthorized access attempts, incorrect credentials provided via the API, or failures in authenticating the user against the domain's LDAP services.

How to use Security?

NCache provides two ways to secure your cache and prevent unauthorized access to your NCache cluster. You can configure Client Node Security through the NCache Management Center, allowing the clients connected with this node to access the cache with the same credentials you provided while configuring Client Node Security. No code change is required to do so. Alternatively, you can configure security programmatically, which is useful when the NCache client is not installed on your system, as demonstrated below.

Prerequisites

Install the Alachisoft.NCache.SDK NuGet package in your application.
Include the following namespaces in your application:
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.Exceptions
- System.Configuration
Add System.Configuration assembly through Reference Manager.
Cache must be running.
The application must be connected to cache before performing the operation.
For API details, refer to: ICache, CacheConnectionOptions, GetCache, CacheManager, Credentials.

Add the following Maven dependencies in your pom.xml file:

<dependency>
    <groupId>com.alachisoft.ncache</groupId>
    <artifactId>ncache-client</artifactId>
    <version>5.3.6</version>
</dependency>

Import the following packages in your application:
- import com.alachisoft.ncache.client.*;
- import com.alachisoft.ncache.runtime.exceptions.*;
- import com.alachisoft.ncache.web.security.*;
Cache must be running.
The application must be connected to cache before performing the operation.
For API details, refer to: Cache, getCache, Credentials, CacheManager, CacheConnectionOptions.

Install the following NuGet package in your .NET client application:
- Enterprise: Install-Package Alachisoft.NCache.SDK -Version 4.9.1.0
Create a new Console Application.
Make sure that the data being added is serializable.
Add NCache References by locating %NCHOME%\NCache\bin\assembly\4.0 and adding Alachisoft.NCache.Web and Alachisoft.NCache.Runtime as appropriate.
Include the Alachisoft.NCache.Web.Caching and Alachisoft.NCache.Web.Security namespaces in your application.
To learn more about the NCache Legacy API, please download the NCache 4.9 documents available as a .zip file on the Alachisoft Website.

The following example demonstrates how to enable security on the cache. After security is configured, the appropriate credentials must be provided when initializing the cache using CacheConnectionOptions.

try
{
    string cacheName = "demoCache";

    // Use CacheConnectionOptions to provide credentials
    var options = new CacheConnectionOptions();

    // Use UserCredentials property to assign credentials
    options.UserCredentials = new Credentials("your-username", "your-password");

    // Connecting to cache with security credentials
    ICache cache = CacheManager.GetCache(cacheName, options);
}
catch (ConfigurationException ex)
{
      if(ex.ErrorCode == NCacheErrorCodes.SERVER_INFO_NOT_FOUND)
      {     
            // client.ncconf must have server information
      }
}
catch (Exception ex)
{
      // Any generic exception like ArgumentNullException or ArgumentException
      // Argument exception occurs in case of empty string name
}

try
{
    String cacheName = "demoCache";

    // Use CacheConnectionOptions to provide credentials
    CacheConnectionOptions options = new CacheConnectionOptions();

    // Use UserCredentials property to assign credentials
    options.setUserCredentials(new Credentials("your-username", "your-password"));

    // Connecting to cache with security credentials
    Cache cache = CacheManager.getCache(cacheName, options);
}
catch (OperationFailedException ex) 
{
    // NCache specific exception
    if (ex.getErrorCode() == NCacheErrorCodes.NO_SERVER_AVAILABLE) 
    {
          // Make sure NCache Service is running
          // Make sure that the cache is running
    }
    else
    {
        // Exception can occur due to:
        // Connection Failures: ErrorCode 17506
        // Operation Timeout: ErrorCode 35003
        // Operation performed during state transfer
    }
}
catch (ConfigurationException ex) 
{
    if (ex.getErrorCode() == NCacheErrorCodes.SERVER_INFO_NOT_FOUND) 
    {
        // client.ncconf must have server information
    }
}
catch (Exception ex) 
{
    // Any generic exception like ArgumentNullException or ArgumentException
    // Argument exception occurs in case of empty string name
}

try
{
    // Using NCache Enterprise 4.9.1
    string cacheName = "demoCache";

    CacheInitParams ciParam = new CacheInitParams();

    // Use CacheInitParams to assign credentials
    ciParam.PrimaryUserCredentials = new SecurityParams("primaryUserId", "primaryUserPassword");
    ciParam.SecondaryUserCredentials = new SecurityParams("secondaryUserId", "secondaryUserPassword");

    // Connecting to cache with security credentials
    Cache cache = NCache.InitializeCache("demoCache", ciParam);
}
catch (OperationFailedException ex)
{
    // High-level NCache specific exception
    if (ex.ErrorCode == NCacheErrorCodes.INVALID_CREDENTIALS)
    {
        // Occurs if Primary or Secondary credentials fail AD authentication
    }
    else if (ex.ErrorCode == NCacheErrorCodes.NO_SERVER_AVAILABLE)
    {
        // Occurs if the client cannot reach any server specified in client.ncconf
    }
}
catch (ConfigurationException ex)
{
    // Errors related to client.ncconf or config.ncconf
    if (ex.ErrorCode == NCacheErrorCodes.SERVER_INFO_NOT_FOUND)
    {
        // Check if client.ncconf is missing or the server IP is incorrect
    }
}
catch (Exception ex)
{
    // Generic exceptions like ArgumentException for null/empty cache names
}

Note

To ensure the operation is fail-safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Or as an alternative, the security credentials can be provided in the property file of your application:

./media/image1.png

// Initialize credentials
string userName = string.Empty;
string password = string.Empty;
string cacheName = "demoCache";

// Check if Username and Password are provided through App.config file
if (ConfigurationManager.AppSettings["Username"] != null)
{
      userName = ConfigurationManager.AppSettings["Username"].ToString();
}
if (ConfigurationManager.AppSettings["Password"] != null)
{
      password = ConfigurationManager.AppSettings["Password"].ToString();
}

// Use CacheConnectionOptions to provide credentials
var options = new CacheConnectionOptions();

options.UserCredentials = new Credentials(userName, password);

// Connect to cache with security credentials provided in App.config file
ICache cache = CacheManager.GetCache(cacheName, options);

// Initialize credentials
String userName = "";
String password = "";
String cacheName = "demoCache";

// Load credentials from a properties file
Properties properties = new Properties();
properties.load(new FileInputStream("src/main/resources/security.properties"));

if (properties.getProperty("Username") != null) {
      userName = properties.getProperty("Username");
}

if (properties.getProperty("Password") != null) {
      password = properties.getProperty("Password");
}

// Set credentials in CacheConnectionOptions
CacheConnectionOptions options = new CacheConnectionOptions();
options.setUserCredentials(new Credentials(userName, password));

// Connect to cache
return CacheManager.getCache(cacheName, options);

// Using NCache Enterprise 4.9.1

//Initialize Credentials
string userName = string.Empty;
string password = string.Empty;

// Check if Username and Password are provided through App.config file
if (System.Configuration.ConfigurationManager.AppSettings["Username "] != null)
{
userName = System.Configuration.ConfigurationManager.AppSettings["Username"].ToString();
}
if (System.Configuration.ConfigurationManager.AppSettings["Password"] != null)
{
password = System.Configuration.ConfigurationManager.AppSettings["Password"].ToString();
}

// Use CacheinItParams to provide credentials
CacheInitParams cacheParam = new CacheInitParams();
cacheParam.PrimaryUserCredentials = new SecurityParams(userName, password);

// Initializing cache with security credential provided in App.config file
Cache cache = NCache.InitializeCache("mycache", cacheParam);

Troubleshooting

Alachisoft.NCache.Runtime.Exceptions.SecurityException

This exception is raised if an unauthorized user tries to perform cache operations, or wrong credential information is given in the GetCache() or Configure Security in client.ncconf file.

Workaround

Check if you have given correct credential information through API or in client.ncconf. A typing mistake can be the result of this exception.
See if the specified user exists under a given domain in LDAP. The login credentials are required to belong to any server hosting the user login and running LDAP services.