Product overview > Tutorials, examples, and samples > Java SE security tutorial


Java SE security tutorial - Step 2


Overview

The following topic shows how to implement client authentication in a distributed eXtreme Scale environment.

Be sure that you have completed Java SE security tutorial - Step 1.

With client authentication enabled, a client is authenticated before connecting to the WXS server. This section demonstrates how client authentication can be done in a WXS server environment, including sample code and scripts to demonstrate.

As any other authentication mechanism, the minimum authentication consists of the following steps:

  1. The administrator changes configurations to make authentication a requirement.
  2. The client provides a credential to the server.
  3. The server authenticates the credential to the registry.


Procedure

  1. Client credential

    A client credential is represented by interface...

    com.ibm.websphere.objectgrid.security.plugins.Credential

    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.

    WXS 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 WXS client runtime to obtain client credentials.

    This sample uses the following two sample plug-in implementations provided by WXS.

    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

  2. Server authenticator

    After the WXS client retrieves the Credential object using the CredentialGenerator object, this client Credential object is sent along with the client request to the WXS server. The WXS server authenticates the Credential object before processing the request. If the Credential object is authenticated successfully, a Subject object is returned to represent this client.

    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 WXS server uses the Authenticator plug-in to authenticate the Credential object. Refer to Authenticator API Documentation for more details.

    This example uses a WXS 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;
    };
    

    Create a key store sampleKS.jks and three user certificates representing the users administrator, manager, and cashier...

    1. Create a directory called "security".

      cd objectgridRoot
      
      mkdir security
      cd security

      Create a user "administreator" with password "administrator1" in the key store sampleKS.jks.

      javaHOME/bin/keytool -genkey 
                           -v 
                           -keystore ./sampleKS.jks 
                           -storepass sampleKS1 
                           -alias administrator 
                           -keypass administrator1 
                           -dname CN=administrator,O=acme,OU=OGSample -validity 10000
      

    2. Create a user "manager" with password "manager1" in the key store sampleKS.jks.

      javaHOME/bin/keytool -genkey 
                           -v 
                           -keystore ./sampleKS.jks 
                           -storepass sampleKS1 
                           -alias manager 
                           -keypass manager1 
                           -dname CN=manager,O=acme,OU=OGSample 
                           -validity 10000
      

    3. to create a user "cashier" with password "cashier1" in the key store sampleKS.jks.

      javaHOME/bin/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...

    1. Copy the sampleClient.properties file to the client.properties file.

      cd objectgridRoot/security
      cp ../properties/sampleClient.properties client.properties
      

    The following properties are highlighted in the client.properties file in the security directory.

    securityEnabled True enables client security, including authentication. Default: True
    credentialAuthentication Supported means the client supports credential authentication. Default: Supported
    transportType TCP/IP means no SSL will be used.
    singleSignOnEnabled Default is false). Single sign-on is not available.

  3. Server security configuration

    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>
    

    1. securityEnabled: Set to true, which enables the server security including authentication.

    2. loginSessionExpirationTime: Set the value to 300 (default value).

    3. authenticator: Add the authenticator class KeyStoreLoginAuthenticator to the cluster XML file...

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

    4. credentialAuthentication: Set credentialAuthentication attribute to Required so the server requires authentication

    For more detailed explanation on the security.xml file, see Security descriptor XML file.

    Copy the server properties file into the security directory. At this time, you do not need to modify anything in this file.

    1. Navigate to the security directory.

      cd objectgridRoot/security
      

    2. Copy the sample objectGrid sampleServer.properties file from the properties directory to the new server.properties file.

      cp ../properties/containerServer.properties server.properties
      

    Make the following changes in the server.properties file:

    1. securityEnabled: Set the securityEnabled attribute to true.

    2. transportType: Set transportType attribute to TCP/IP, which means no SSL is used.

    3. secureTokenManagerType: Set secureTokenManagerType attribute to none to not configure the secure token manager.

  4. Secure client

    Connect the client application to the server securely as demonstrated in the following example:

    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;
    
        }
    
    }
    

    There are three things different from the non-secured application:

    1. Created a ClientSecurityConfiguration object by passing the configured client.properties file.

    2. Created a UserPasswordCredentialGenerator by using the passed-in user ID and password.

    3. Connected to the catalog server to obtain an ObjectGrid from the ClientClusterContext by passing a ClientSecurityConfiguration object.

  5. Issue the application

    To run the application, start the catalog server. Issue the -clusterFile and -serverProps command line options to pass in the security properties:

    1. Navigate to the bin directory:

      cd objectgridRoot/bin
      

    2. Launch the catalog server:

      • [Unix][Linux]

        startOgServer.sh catalogServer -clusterSecurityFile ../security/security.xml 
        -serverProps ../security/server.properties -jvmArgs 
        -Djava.security.auth.login.config="../security/og_jaas.config"
        

      • [Windows]

        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:

    1. Navigate to the bin directory again:

      cd objectgridRoot/bin
      

    2. Launch a secure container server:

      • [Linux][Unix]

        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"
        

      • [Windows]

        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"
        

    The server property file is passed by issuing -serverProps.

    After the server is started, start the client by using the following command:

    1. cd objectgridRoot/bin
      

    2. java -classpath ../lib/objectgrid.jar;../applib/secsample.jar
              com.ibm.websphere.objectgrid.security.sample.guide.SecureSimpleApp
              ../security/client.properties manager manager1
      

      Use a colon (:) for the classpath separator instead of a semicolon (;) as in the previous example.

    The secsample.jar file contains the SimpleApp class.

    The SecureSimpleApp uses three parameters that are provided in the following list:

    1. The ../security/client.properties file is the client security property file.

    2. manager is the user ID.

    3. manager1 is the password.

    After you issue the class, the following output results:

    The customer name for ID 0001 is fName lName.

    You may also use xsadmin to show the mapsizes of the "accounting" grid.

    • Navigate to the directory objectgridRoot/bin.

    • Use the xsadmin command with option -mapSizes as follows.

      • [Unix][Linux] xsadmin.sh -g accounting -m mapSet1 -username manager -password manager1 -mapSizes

      • [Windows] xsadmin.bat -g accounting -m mapSet1 -username manager -password manager1 -mapSizes

      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.

      Connect 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 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.

    • [Unix][Linux] stopOgServer.sh c0 -catalogServiceEndPoints localhost:2809 -clientSecurityFile ..\security\client.properties

    • [Windows] stopOgServer.bat c0 -catalogServiceEndPoints localhost:2809 -clientSecurityFile ..\security\client.properties

    If you do not provide the -clientSecurityFile option, we 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, to continue trying the next step tutorial, you can let the catalog server stay running.

    • [Unix][Linux] stopOgServer.sh catalogServer -catalogServiceEndPoints localhost:2809 -clientSecurityFile ..\security\client.properties

    • [Windows] stopOgServer.bat catalogServer -catalogServiceEndPoints localhost:2809 -clientSecurityFile ..\security\client.properties

    If you do shutdown the catalog server, we will see the following output.

    CWOBJ2512I: ObjectGrid server catalogServer stopped

    Now, you have successfully made the 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.

    Next step of tutorial


Parent topic:

Java SE security tutorial: overview


Previous topic:

Java SE security tutorial - Step 1


Next topic:

Java SE security tutorial - Step 3