Authenticating application clients

Application client authentication consists of enabling client-server security and credential authentication, and configuring an authenticator and a system credential generator.

Procedure

Enable client-server security
You must enable security on both the client and server to successfully authenticate with the ObjectGrid.
1. Enable client security.
  WebSphere® eXtreme Scale provides a client property sample file, the sampleClient.properties file, in the was_root/optionalLibraries/ObjectGrid/properties directory for a WebSphere Application Server installation, or the /ObjectGrid/properties directory in a mixed-server installation. You can modify this template file with appropriate values. Set the securityEnabled property in the objectgridClient.properties file to true. The securityEnabled property indicates if security is enabled. When a client connects to a server, the value on the client and server side must be set both true or both false. For example, if the connected server security is enabled, the property value must be set to true on the client side for the client to connect to the server.
  When you set securityEnabled to true, then the following settings are available:
  credentialAuthentication
  
  Specifies the client credential authentication support. Use one of the following valid values:
  Never: The client does not support credential authentication.
  
  Supported: The client supports credential authentication if the server also supports credential authentication. (Default)
  
  Required: The client requires credential authentication.
  
  authenticationRetryCount
  
  Specifies the number of times that authentication is tried if the credential is expired. If the value is set to 0, attempts to authenticate are not tried again.
  Default: 3
  
  credentialGeneratorAssembly
  
  Specifies the name of the assembly that is used to generate credentials for the WebSphere eXtreme Scale Client for .NET. To specify this property, the credentialAuthentication property must be set to Supported or Required. The value must be a valid C# .dll assembly name with version, culture and other properties included.
  Example: IBM.WebSphere.Caching.CredentialGenerator, Version=8.6.0.0, Culture=neutral, PublicKeyToken=b439a24ee43b0816
  
  credentialGeneratorClass
  
  Specifies the name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. To specify this property, the credentialAuthentication property must be set to Supported or Required. This class is used to get credentials for clients.
  Default: no value
  
  credentialGeneratorProps
  
  Specifies the properties for the CredentialGenerator implementation class. The properties are set to the object with the setProperties(String) method. To specify this property, the credentialAuthentication property must be set to Supported or Required. The credentialGeneratorprops value is used only if the value of the credentialGeneratorClass property is not null.
  
  transportType
  
  Specifies the client transport type. The possible values are:
  TCP/IP: Indicates that the client only supports TCP/IP connections.
  
  SSL-Supported: Indicates that the client supports both TCP/IP and Secure Sockets Layer (SSL) connections. (Default)
  
  SSL-Required: Indicates that the client requires SSL connections.
  
  publicKeyFile
  
  Specifies a fully-qualified path name to a file that contains the exported public key from the server.
  Example: c:\tmp\wxs\serverA.cer
  
  protocol
  
  Indicates the type of security protocol to use for the client. Set this protocol value based on which security provider you use. If you indicate a value that is not valid, a security exception results that indicates that the protocol value is incorrect.
  Valid values: SSL, SSLv3, TLS, TLSv1, and so on.
  
  Valid values: SSLv2, SSLv3, TLS or Default (SSLv3 or TLS1.0)
  The com.ibm.websphere.objectgrid.security.config.ClientSecurityConfiguration interface represents the security.ogclient.props file. You can use the com.ibm.websphere.objectgrid.security.config.ClientSecurityConfigurationFactory public API to create an instance of this interface with default values, or you can create an instance by passing the ObjectGrid client security property file. The security.ogclient.props file contains other properties. See the ClientSecurityConfiguration API Documentation and ClientSecurityConfigurationFactory API Documentation for more details.
2. Enable server security.
  To enable the security on the server side, you can set the securityEnabled property in the security.xml file to true. Use a security descriptor XML file to specify the data grid security configuration to isolate the grid-wide security configuration from the non-security configuration.

Enable credential authentication.

After the eXtreme Scale client retrieves the Credential object using the CredentialGenerator object, the Credential object is sent along with the client request to the eXtreme Scale server. The server authenticates the Credential object before processing the request. If the Credential object is authenticated successfully, a Subject object is returned to represent this Credential object. This Subject object is then used for authorizing the request.

Set the credentialAuthentication property on the client and server properties files to enable the credential authentication. For more information, see Client properties file and Server properties file.

The following table provides which authentication mechanism to use under different settings.

Table 1. Credential authentication under client and server settings
Client credential authentication	Server credential authentication	Result
No	Never	Disabled
No	Supported	Disabled
No	Required	Error case
Supported	Never	Disabled
Supported	Supported	Enabled
Supported	Required	Enabled
Required	Never	Error case
Required	Supported	Enabled
Required	Required	Enabled

Configure an authenticator.
The eXtreme Scale server uses the Authenticator plug-in to authenticate the Credential object. An implementation of the Authenticator interface gets the Credential object and then authenticates it to a user registry, for example, a Lightweight Directory Access Protocol (LDAP) server, and so on. eXtreme Scale does not provide a registry configuration. Connecting to a user registry and authenticating to it must be implemented in this plug-in.

For example, one Authenticator implementation extracts the user ID and password from the credential, uses them to connect and validate to an LDAP server, and creates a Subject object as a result of the authentication. The implementation can use Java™ Authentication and Authorization Service (JAAS) login modules. A Subject object is returned as a result of authentication.
You can configure the authenticator in the security descriptor XML file, as shown in the following example:
```
<?xml version="1.0" encoding="UTF-8"?>
<securityConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://ibm.com/ws/objectgrid/config/security ../objectGridSecurity.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config/security">

	<security securityEnabled="true" 
        loginSessionExpirationTime="300">
	
		<authenticator className ="com.ibm.websphere.objectgrid.security.plugins.builtins.KeyStoreLoginAuthenticator">
        </authenticator>

	</security>
	
</securityConfig>
```
Use the -clusterSecurityFile option when starting a secure server to set the security XML file. See the Java SE security tutorial - Step 2 for samples on how to start a secure server.
Configure a system credential generator.
The system credential generator is used to represent a factory for the system credential. A system credential is similar to an administrator credential. You can configure the SystemCredentialGenerator element in the catalog security XML file, as shown in the following example:
```
<systemCredentialGenerator className ="com.ibm.websphere.objectgrid.security.plugins.
	builtins.UserPasswordCredentialGenerator">
          <property name="properties" type="java.lang.String" value="manager manager1" 
						description="username password" />
 </systemCredentialGenerator>
```
For demonstration purposes, the user name and password are stored in clear text. Do not store the user name and password in clear text in a production environment.
WebSphere eXtreme Scale provides a default system credential generator, which uses the server credentials. If you do not explicitly specify the system credential generator, this default system credential generator is used.