How to use Security?

NCache provides two ways to secure your cache and prevent unauthorized access to your NCache cluster. You can configure Cache 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 Cache 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.

Additionally, NCache enables cache users to securely connect to the cache using a Group Managed Service Account (gMSA) identity using a Security property of type SecurityOptions.

Prerequisites

• .NET
• Java
• Legacy API

• 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.
• To lean about gMSA requirements, please see Configure gMSA section.
• The application must be connected to cache before performing the operation.
• For API details, refer to: ICache, CacheConnectionOptions, GetCache, CacheManager, UserCredentials, CreateWithCredentials, CreateWithGMSA, SecurityOptions.

Using Security API

The Security property of the CacheConnectionOptions class allows you to either provide a username and password or use gMSA for password-less authentication. You can use helper methods like CreateWithCredentials or CreateWithGMSA to create the desired configuration, which is used during cache connection.

Connect using CreateWithCredentials API

The following example demonstrates how to use the SecurityOptions API to provide a username and password when initializing the cache.

• .NET

try
{
    string cacheName = "demoCache";

    var cacheConnectionOptions = new CacheConnectionOptions();

    // If the user wants to use username/password credentials, they can set the Security property to use those credentials
    cacheConnectionOptions.Security = SecurityOptions.CreateWithCredentials("your-username", "your-password");

    ICache cache = CacheManager.GetCache(cacheName, cacheConnectionOptions);
}
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
}

Note

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

Connect using gMSA Security

The following code sample shows how to configure the cache connection to use Group Managed Service Account (gMSA) credentials for password-less authentication, using CreateWithGMSA().

• .NET

string cacheName = "demoCache";
var cacheConnectionOptions = new CacheConnectionOptions();

cacheConnectionOptions.Security = SecurityOptions.CreateWithGMSA();

ICache cache = CacheManager.GetCache(cacheName, cacheConnectionOptions);

Connect via App.config using Credentials

The following code sample demonstrates how to retrieve security credentials stored in the App.config file and apply them using the SecurityOptions property.

• .NET

// 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 cacheConnectionOptions = new CacheConnectionOptions();

cacheConnectionOptions.Security = SecurityOptions.CreateWithCredentials(userName, password);

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

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

1. Check if you have given correct credential information through API or in client.ncconf. A typing mistake can be the result of this exception.
2. 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.

See Also

NCache Data Encryption
Configuring Security