#
# README.txt
#
# Copyright 2000-2006 by Tangosol, Inc.  All rights reserved.
#
# This software is the confidential and proprietary information of
# Tangosol, Inc.  You shall not disclose such confidential and pro-
# prietary information and shall use it only in accordance with the
# terms of the license agreement you entered into with Tangosol, Inc.
#
# Tangosol, Inc. makes no representations or warranties about the suit-
# ability of the software, either express or implied, including but not
# limited to the implied warranties of merchantability, fitness for a
# particular purpose, or non-infringement.  Tangosol, Inc. shall not be
# liable for any damages suffered by licensee as a result of using,
# modifying or distributing this software or its derivatives.
#
# Tangosol, Inc. is located at http://www.tangosol.com and can be
# contacted by e-mail at info@tangosol.com.
#
# This notice may not be removed or altered.
#

README
======

Tangosol Coherence*Extend Security Example

Contents
========

    * Overview
    * Prerequisites
    * Build Instructions
    * Running the Example

Overview
========

This example demonstrates how to authenticate a Coherence*Extend user and
pass the user's identity to the cluster, where it is used to enforce
entitlements on a target NamedCache.

A Coherence*Extend client authenticates a user using either standard JAAS API
calls or via the Coherence Security Framework. Once authenticated, the client
accesses a target remote NamedCache by executing a PrivilegedAction on
behalf of the user's authenticated Subject. The Coherence*Extend client
transparently passes the user's Subject to the cluster, where an example
NamedCache wrapper is used to enforce that the remote user has a specified
Principal. The example NamedCache wrapper could easily be enhanced to enforce
more sophisticated entitlements, such as transforming cached data or
providing a filtered view of the target NamedCache.

Prerequisites
=============

  To build the example, you must have the following software installed:

    * J2SE SDK 1.4 or later  (http://java.sun.com/)
    * Apache Ant             (http://ant.apache.org/)
    * Tangosol Coherence 3.3 (http://www.tangosol.com/index.jsp)

Build Instructions
==================

  * Update bin/set-env.sh to reflect your system environment.

  * Open a shell and execute the following command in the bin directory:

      ./ant.sh build

  * To completely remove all build artifacts from your filesystem, run:

      ./ant.sh clean

Running the Example
===================

  * Start a cache server by executing the following script:

      ./start-server.sh

  * Launch the client using a user with insufficient privileges to access
    a target remote NamedCache:

      ./start-client.sh guest secret

  * Launch the client using a user with access privileges to a target remote
    NamedCache:

      ./start-client.sh admin secret