Authentication Examples

This topic discusses the concepts and configurations for sample LDAP and PKCS implementations. Descriptions of their interfaces, classes and methods are available in the online API documentation.

Note: Disclaimer: The security samples serve only as example implementations. The implementation and its source code is provided on an “as-is�? basis, without warranties or conditions of any kind, either express or implied. You can modify these samples to suit your specific requirements and security providers. VMware takes no responsibility and accepts no liability for any damage to computer equipment, companies or personnel that might arise from the use of these samples.

Using an LDAP Server for Client and Peer Authentication

The LDAP sample code in the templates/security directory is UserPasswordAuthInit.java, LdapUserAuthenticator.java, and UsernamePrincipal.java.

In the example, a client or joining peer submits its credentials to a server or locator, which in turn submits the credentials to the LDAP server. To be authenticated, the credentials must match one of the valid entries in the LDAP server. If the submitted credentials result in a connection to the LDAP server, then the connection is authenticated. If the connection to the LDAP server fails, an AuthenticationFailedException is sent back and the client or peer connection fails.

These are the gemfire.properties file (or gfsecurity.properties file if you are creating a special restricted access file for security configuration) settings for client, and for all peers in the server system, including the servers and locators.

Client:

security-client-auth-init=templates.security.UserPasswordAuthInit.create 
security-username=�?username�? 
security-password=�?password�?

Server system members:

security-peer-auth-init=templates.security.UserPasswordAuthInit.create 
security-peer-authenticator=templates.security.LdapUserAuthenticator.create
security-ldap-server=�?name of ldap server�?
security-ldap-basedn=�?ou=www, dc=xxx, dc=yyy, dc=zzz�?

LDAP authentication and authorization requires the LDAP server to have entries for each member that is authenticated by the system. The server also requires information to authorize or reject operations by authenticated clients when the authorization callback is invoked.

During the client authentication process, a server searches for a specific entry in the LDAP server. The uid and password parameters submitted by the client are used to search the entries in the LDAP server. The LDAP authenticator is initialized with an LDAP base DN, which is the top level for the LDAP directory tree. The authenticator is also provided with the LDAP server name. The LDAP authenticator can be initialized to make a secure connection by setting the security-ldap-usessl property to true.

The sample LdapUserAuthenticator class implements the Authenticator interface, which verifies the credentials provided in the properties as specified in member ID and returns the principal associated with the client. The init method for LdapUserAuthenticator gets the LDAP server name from the security-ldap-server property in the gemfire.properties. It also gets the LDAP server base DN name from the security-ldap-basedn property, and SSL usage information from the security-ldap-usessl property.

Using PKCS for Encrypted Client Authentication

The PKCS sample code in the templates/security directory is PKCSAuthInit.java, PKCSAuthenticator.java, and PKCSPrincipal.java.

With this sample, clients send encrypted authentication credentials to a GemFire cache server when they attempt to connect to the server. The credentials are the alias name and digital signature created using the private key retrieved from the provided keystore. The server uses a corresponding public key to decrypt the credentials. If decryption is successful, the client is authenticated and it connects to the server. An unsuccessful decryption generates an AuthenticationFailedException that is sent to the client, and the client connection to the server is closed.

These are the gemfire.properties file (or gfsecurity.properties file if you are creating a special restricted access file for security configuration) settings for client and server.

Client:

security-client-auth-init=templates.security.PKCSAuthInit.create
security-keystorepath=�?keystore path�?
security-alias=�?alias�?
security-keystorepass=�?keystore password�?

Server:

security-client-authenticator=templates.security.PKCSAuthenticator.create
security-publickey-filepath=�?path and name of public key file�?
security-publickey-pass=�?password of public key file store on the server�?

The authenticator gets the path to the truststore from the security-publickey-filepath property in the gemfire.properties (or gfsecurity.properties file if you are creating a special restricted access file for security configuration).

When the client requires authentication, PKCSAuthInit gets the alias retrieved from the security-alias property, and the keystore path from the security-keystorepath property. PKCSAuthInit also gets the password for the keystore file from the security-keystorepass property so the keystore can be opened.

You can generate keys for encryption using the Java keytool utility, which is a key and certificate management utility located in the jre/bin directory of your Java JDK or JRE installation. The keytool utility manages a keystore, or database, of private keys and their associated X.509 certificate chains for authenticating the corresponding public keys. Certificates from trusted entities are also managed using keytool. See the Security Tools section at http://download.oracle.com/javase/6/docs/technotes/tools for more information about using keytool. The public keys from the client keystores should be provided in the public keystore that is referenced by the security-publickey-filepath property.

These are the steps to provide the keys, with example utility invocations:

Generate a public and private key pair for the client:

keytool -genkeypair \
-dname "cn=Your Name, ou=GemFire, o=GemStone, c=US" \
-storetype PKCS12 \
-keyalg RSA \
-keysize 2048 \
-alias gemfire8 \
-keystore gemfire8.keystore \
-storepass your_password
-validity 180

This step creates a keystore called gemfire8.keystore in the local directory and adds a public/private key pair to it.

Export the self-signed certificate:

keytool -exportcert \
-storetype PKCS12 \
-keyalg RSA
-keysize 2048 
-alias gemfire8 \
-keystore gemfire8.keystore \
-storepass your_password
-rfc \
-file gemfire8.cer

After successfully exporting the certificate, you should see the following message:

Certificate stored in file <gemfire8.cer>

The above commands exports the certificate file to the current local directory.

Import the signed certificate to the truststore:
```
keytool -importcert \
-alias gemfire8 \
-file gemfire8.cer \
-keystore certificatetruststore
```
You will be prompted to enter your keystore password. After you have authenticated, the certificate appears. After you respond to the prompt "Trust this certificate?", the certificate is imported into the certificatetruststore keystore, creating it if necessary.

Multiple certificates can be imported to the same truststore. The alias name used to generate the key pair and the alias name used to import the certificate to the truststore can be different, but the PKCS sample implementation assumes that both are the same. The credentials authenticator reads the truststore file and loads all the public keys from the truststore, along with the alias names.