Client-side Authentication

Authentication methods will only be used if a password is supplied when creating a session to the server. The SASL implementation for Universal Messaging in .NET supports the following mechanisms: plain (plain text username/password authentication), CRAM-MD5 and Digest-MD5 (cryptographically encoded credential authentication). The preferred mechanism can be set either via an API call or an environment variable as detailed below.

Setting the preferred authentication mechanism via Environment Configuration

There are a number of environment variables which may be used to control the authentication behaviour of the .NET API:

Nirvana.sasl.client.mech

This specifies which SASL mechanism to use, and the supported options are PLAIN, CRAM-MD5 and DIGEST-MD5.

The mechanism defaults to PLAIN if this system property is not set, and the usual SASL trade-offs apply. PLAIN transmits the user password in plain text, so it is advisable to only use it over an SSL connection. On the other hand, CRAM-MD5 and DIGEST-MD5 do not transmit the password in plain text so are more appropriate for general connections.

Note that if the preferred mechanism is set via nSessionAttributes, the API-set value will be preferred over this one.

Nirvana.sasl.client.enablePrehash

This specifies whether to prehash the supplied password when using the CRAM-MD5 or DIGEST-MD5 mechanisms. It may be set to "true" or "false". This should be set to "true" only when the server is using the fSAGInternalUserRepositoryAdapter to store client credentials, otherwise CRAM-MD5 and DIGEST-MD5 authentication will fail. If Nirvana.sasl.client.enablePrehash is not set, then the value defaults to "false" and prehashing is not enabled.

Setting the preferred authentication mechanism via API

For the client and admin APIs, the preferred authentication mechanisms can be set via the nSessionAttributes class used to create a session as follows:

nSessionAttributes:

public void setSASLMechPrefs(nSaslMechanism[] mechPrefs)

Here, nSaslMechanism is an enum with possible values PLAIN, CRAM_MD5 or DIGEST_MD5. The array passed in should be an array of any number of these nSaslMechanisms in order of preference. Preferences set here will take precedence over any preferences set via environment variables. If this is unset, Universal Messaging will use the mechanism preference set via the environment variable Nirvana.sasl.client.mechanism. If this environment variable is unset, the default mechanism will be PLAIN. Note that this method is unavailable to clients using a reactive session. In this case, the mechanism preferences can only be set via the environment variable Nirvana.sasl.client.mechanism.

In order to supply credentials to the API, Universal Messaging offers a number of additions to the standard constructors and factory methods. Either the username and password can be supplied independently as a String and a SecureString (inbuilt in .NET in System.Security) respectively or in some cases both can be supplied together inside a NetworkCredentials object (inbuilt in .NET in System.Net).

Thus we have the following API additions:

Client Sessions:

nSessionFactory:

public static nSession create(nSessionAttributes sAttr,
String username, SecureString password)
public static nSession create(nSessionAttributes sAttr,
NetworkCredentials creds)
public static nSession create(nSessionAttributes sAttr,
nReconnectHandler handler, String username, SecureString password)
public static nSession create(nSessionAttributes sAttr,
nReconnectHandler handler, NetworkCredentials creds)
public static nSession createMultiplexed(nSessionAttributes sAttr,
String username, SecureString password)
public static nSession createMultiplexed(nSessionAttributes sAttr,
NetworkCredentials creds)
public static nSession createMultiplexed(nSession session,
String username, SecureString password)
public static nSession createMultiplexed(nSession session,
NetworkCredentials creds)

Admin Sessions:

nRealmNode:

Constructor -
nRealmNode(nSessionAttributes sAttr, String username, SecureString passwd);
Constructor -
nRealmNode(nSessionAttributes sAttr, NetworkCredentials creds);

nRealmAdmin:

Constructor -
nRealmAdmin(nSessionAttributes sAttr, String username,
SecureString password)
Constructor -
nRealmAdmin(nSessionAttributes sAttr, String username,
SecureString password, bool followTheMaster)

Reactive Sessions:

ISessionAttributes:

string Username { get; set; }
SecureString Password { get; set; }
NetworkCredentials Credentials { get; set; }