Building on the previous step, the following topic shows how to implement client authentication in a distributed eXtreme Scale environment.
A client credential is represented by a com.ibm.websphere.objectgrid.security.plugins.Credential interface. A client credential can be a user name and password pair, a Kerberos ticket, a client certificate, or data in any format that the client and server agree upon. Refer to Credential API documentation for more details.
This interface explicitly defines the equals(Object) and hashCode() methods. These two methods are important because the authenticated Subject objects are cached by using the Credential object as the key on the server side.
eXtreme Scale also provides a plug-in to generate a credential. This plug-in is represented by the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface, and is used to generate a client credential. This is useful when the credential is expirable. In this case, the getCredential() method is called to renew a credential. Refer to CredentialGenerator API Documentation for more details.
You can implement these two interfaces for eXtreme Scale client runtime to obtain client credentials.
This sample uses the following two sample plug-in implementations provided by eXtreme Scale.
com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredential
com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator
For more information about these plug-ins, see Client authentication programming
This Subject object is then cached, and it expires after its lifetime reaches the session timeout value. The login session timeout value can be set by using the loginSessionExpirationTime property in the cluster XML file. For example, setting loginSessionExpirationTime="300" makes the Subject object expire in 300 seconds.
This Subject object is then used for authorizing the request, which is shown later.An eXtreme Scale server uses the Authenticator plug-in to authenticate the Credential object. Refer to Authenticator API Documentation for more details.
This example uses an eXtreme Scale built-in implementation: KeyStoreLoginAuthenticator, which is for testing and sample purposes (a key store is a simple user registry and should not be used for production). For more information, see the topic on authenticator plug-in under Client authentication programming.
This KeyStoreLoginAuthenticator uses a KeyStoreLoginModule to authenticate the user with the key store by using the JAAS login module "KeyStoreLogin". The key store can be configured as an option to the KeyStoreLoginModule class. The following example illustrates the keyStoreLogin alias configured in the JAAS configuration file og_jaas.config:
KeyStoreLogin{ com.ibm.websphere.objectgrid.security.plugins.builtins.KeyStoreLoginModule required keyStoreFile="../security/sampleKS.jks" debug = true; };
cd objectgridRoot
mkdir security
cd security
keytool -genkey -v -keystore ./sampleKS.jks -storepass sampleKS1 -alias administrator -keypass administrator1 -dname CN=administrator,O=acme,OU=OGSample -validity 10000
keytool -genkey -v -keystore ./sampleKS.jks -storepass sampleKS1 -alias manager -keypass manager1 -dname CN=manager,O=acme,OU=OGSample -validity 10000
keytool -genkey -v -keystore ./sampleKS.jks -storepass sampleKS1 -alias cashier -keypass cashier1 -dname CN=cashier,O=acme,OU=OGSample -validity 10000
The client security configuration is configured in the client properties file. Use the following command to create a copy in the %OBJECTGRID_HOME%/security directory:
cd objectgridRoot/security
cp ../properties/sampleClient.properties client.properties
The server security configuration is specified in the security descriptor XML file and the server security property file.
The security descriptor XML file describes the security properties common to all servers (including catalog servers and container servers). One property example is the authenticator configuration which represents the user registry and authentication mechanism.Here is the security.xml file to be used in this sample:
<?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>
<authenticator className ="com.ibm.websphere.objectgrid.security.plugins.builtins.KeyStoreLoginAuthenticator"> </authenticator>
For more detailed explanation on the security.xml file, see Security descriptor XML file.
cd objectgridRoot/security
cp ../properties/containerServer.properties server.properties
// This sample program is provided AS IS and may be used, executed, copied and modified // without royalty payment by customer // (a) for its own instruction and study, // (b) in order to develop applications designed to run with an IBM WebSphere product, // either for customer's own internal use or for redistribution by customer, as part of such an // application, in customer's own products. // Licensed Materials - Property of IBM // 5724-J34 (C) COPYRIGHT International Business Machines Corp. 2007-2009 package com.ibm.websphere.objectgrid.security.sample.guide; import com.ibm.websphere.objectgrid.ClientClusterContext; import com.ibm.websphere.objectgrid.ObjectGrid; import com.ibm.websphere.objectgrid.ObjectGridManager; import com.ibm.websphere.objectgrid.ObjectGridManagerFactory; import com.ibm.websphere.objectgrid.security.config.ClientSecurityConfiguration; import com.ibm.websphere.objectgrid.security.config.ClientSecurityConfigurationFactory; import com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator; import com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator; public class SecureSimpleApp extends SimpleApp { public static void main(String[] args) throws Exception { SecureSimpleApp app = new SecureSimpleApp(); app.run(args); } /** * Get the ObjectGrid * @return an ObjectGrid instance * @throws Exception */ protected ObjectGrid getObjectGrid(String[] args) throws Exception { ObjectGridManager ogManager = ObjectGridManagerFactory.getObjectGridManager(); ogManager.setTraceFileName("logs/client.log"); ogManager.setTraceSpecification("ObjectGrid*=all=enabled:ORBRas=all=enabled"); // Creates a ClientSecurityConfiguration object using the specified file ClientSecurityConfiguration clientSC = ClientSecurityConfigurationFactory .getClientSecurityConfiguration(args[0]); // Creates a CredentialGenerator using the passed-in user and password. CredentialGenerator credGen = new UserPasswordCredentialGenerator(args[1], args[2]); clientSC.setCredentialGenerator(credGen); // Create an ObjectGrid by connecting to the catalog server ClientClusterContext ccContext = ogManager.connect("localhost:2809", clientSC, null); ObjectGrid og = ogManager.getObjectGrid(ccContext, "accounting"); return og; } }
To run the application, start the catalog server. Issue the -clusterFile and -serverProps command line options to pass in the security properties:
cd objectgridRoot/bin
startOgServer.sh catalogServer -clusterSecurityFile ../security/security.xml -serverProps ../security/server.properties -jvmArgs -Djava.security.auth.login.config="../security/og_jaas.config"
startOgServer.bat catalogServer -clusterSecurityFile ../security/security.xml -serverProps ../security/server.properties -jvmArgs -Djava.security.auth.login.config="../security/og_jaas.config"
Then, launch a secure container server by using the following script:
cd objectgridRoot/bin
startOgServer.sh c0 -objectgridFile ../xml/SimpleApp.xml -deploymentPolicyFile ../xml/SimpleDP.xml -catalogServiceEndpoints localhost:2809 -serverProps ../security/server.properties -jvmArgs -Djava.security.auth.login.config="../security/og_jaas.config"
startOgServer.bat c0 -objectgridFile ../xml/SimpleApp.xml -deploymentPolicyFile ../xml/SimpleDP.xml -catalogServiceEndpoints localhost:2809 -serverProps ../security/server.properties -jvmArgs -Djava.security.auth.login.config="../security/og_jaas.config"
cd objectgridRoot/bin
java -classpath ../lib/objectgrid.jar;../applib/secsample.jar com.ibm.websphere.objectgrid.security.sample.guide.SecureSimpleApp ../security/client.properties manager manager1
The secsample.jar file contains the SimpleApp class.
The SecureSimpleApp uses three parameters that are provided in the following list:
After you issue the class, the following output results:
The customer name for ID 0001 is fName lName.
You see the following output.
This administrative utility is provided as a sample only and is not to be considered a fully supported component of the WebSphere eXtreme Scale product.
Connecting to Catalog service at localhost:1099
*********** Displaying Results for Grid - accounting, MapSet - mapSet1 ***********
*** Listing Maps for c0 ***
Map Name: customer Partition #: 0 Map Size: 1 Shard Type: Primary
Server Total: 1
Total Domain Count: 1
Now you can use stopOgServer command to stop the container server or catalog service process. However you need to provide a security configuration file. The sample client property file defines the following two properties to generate a userID/password credential (manager/manager1).
credentialGeneratorClass=com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator
credentialGeneratorProps=manager manager1
Stop the container c0 with the following command.
If you do not provide the -clientSecurityFile option, you will see an exception with the following message.
>> SERVER (id=39132c79, host=9.10.86.47) TRACE START:
>> org.omg.CORBA.NO_PERMISSION: Server requires credential authentication but there is no security context from the client. This usually happens when the client does not pass a credential the server.
vmcid: 0x0
minor code: 0
completed: No
You can also shut down the catalog server using the following command. However, if you want to continue trying the next step tutorial, you can let the catalog server stay running.
If you do shutdown the catalog server, you will see the following output.
CWOBJ2512I: ObjectGrid server catalogServer stopped
Now, you have successfully made your system partially secure by enabling authentication. You configured the server to plug in the user registry, configured the client to provide client credentials, and changed the client property file and cluster XML file to enable authentication.
If you provide an invalidate password, you see an exception stating that the user name or password is not correct.
For more details about client authentication, see Application client authentication.