README.TXT

--------------------------------------------------------------------
Sun(TM) ONE Identity Server Policy Agents 2.1
(formerly iPlanet(TM) Directory Server Access Management Edition)
--------------------------------------------------------------------

DISCLAIMER
-----------
   THIS SAMPLE CODE IS PROVIDED AS-IS FOR REFERENCE PURPOSES ONLY. 
   SUN MICROSYSTEMS, INC. IS NOT LIABLE FOR ANY DAMAGE RESULTING 
   FROM THE USE OF THIS CODE OR ANY PORTION THEREOF.


SAMPLE CODE
-----------

   * What is provided.
   * Building Sample Program on Solaris
   * Building Sample Program on Windows
   * Executing the Sample Program
     * Executing the Sample Program on Solaris
     * Executing the Sample Program on Windows
   * Related References

What is provided
----------------
   The sample distribution contains source files:
          
          1. am_policy_test.c
          2. apache_agent.c
	  3. am_auth_test.c
          4. am_sso_test.c

   The file am_policy_test.c demonstrates the basic usage of Policy SDK APIs 
   that can be used to evaluate policy for specified resources.
   
   The file apache_agent.c demonstrates how the Policy SDK APIs can be used
   to build a Web Agent for the Apache Web Server. Please note that this
   is a sample Web Agent and is not intended to serve as a real Web 
   Agent. 

   The file am_auth_test.c demonstrates the basic usage of Authentication SDK APIs 
   that can be used to login to an Identity Server.

   The file am_sso_test.c demonstrates the basic usage of SSO SDK APIs 
   that can be used to perform session operations.

   When you build the sample code, only apache_agent.c is not compiled. The
   apache_agent.c is provided for reference purposes only.


Building Sample Program on Solaris
----------------------------------

   On Solaris platform, the sample program can be built using gmake. This
   can be done by the following steps:

   1. Make sure you have gmake or any other compliant make program 
      available. We recommend the use of GNU's gmake program version
      3.76 or higher.

   2. Make sure you have gcc or any other compliant C compiler program
      available.

   3. From the samples directory, simply invoke the make program. For
      example, 

	  $ gmake

   4. This produces executable files am_policy_test, am_auth_test, 
      am_sso_test in the same directory. 
      

Building Sample Program on Windows
----------------------------------

   On Windows platform, the sample programs can be built using 
   Microsoft Visual Studio 6.0.  Be sure to do the following: 
       - Define WINNT in the compile flags.
       - Add ../include as an additional include path. 
       - Add ../lib as an additional lib path. 
       - Link with all libraries in the ../lib directory. 

   If gmake and MKS toolkit are installed on the system, the default 
   Makefile can be used to make all samples by simply typing a 
   gmake on the command. For example: 
  
       C:\samples>gmake


Executing the Sample Program
----------------------------

   The sample programs operate in a command line mode and demonstrate
   the use of C API for policy, auth and sso . Usage of sample programs
   are as follows:

am_policy_test

   Note: You must have a policy defined for the specified resource in 
   an Identity Server before running this program.

   Description: am_policy_test evaluates the policy for the given ssoToken, 
   resource name, action.

   Usage: 
      am_policy_test <init property file> <ssoToken> <resource name> <action>

   <init property file> 
       is the path to the AMAgent.properties file. For example:
       ../config/AMAgent.properties

   <ssoToken> 
       is a valid SSO Token issued by Identity Server. You can get this
       value out of your browser after logging into Identity Server. Please
       refer to the documentation for your browser on how to find out the
       cookie values. Once you have that information, you can use the value
       of the cookie iPlanetDirectoryPro as the value for this argument.

       Note: In case the browser you are using does not provide URL decoded
       cookie values, you may have to decode the value yourself before using
       it in this sample program. Alternatively, for test purposes, you can
       also use the SSO value displayed in the debug logs of the Identity
       Server.

   <resource name> 
       is the name of a resource that you wish to evaluate the policy for. 
       For example: http://myserver.mydomain.com:80/myresource.html

   <action>
       is the action name. For example GET or POST.


am_auth_test

   Note: You must have an Identity Server with a user profile set up with the 
   corresponding authentication module before running this program.

   Description: am_auth_test authenticates to the specified org (if any) using 
   the specified authentication module.

   Usage: am_auth_test [-u user] [-p password] [-f properties_file] [-r url]
                       [-n cert_nick_name] [-o org_name] [-m auth_module]

   With no options supplied on the command line, login defaults to use the
   org_name specified in the properties file and auth_module LDAP. The
   user may specify the org_name (for example: dc=iplanet,dc=com) on the
   command line to override the value specified in the properties file. The
   user is prompted for "User Name: " and "Password: " in either case.

   For Cert based login, the user specifies auth_module Cert on the command
   line. The user may optionally specify the cert_nick_name on the command
   line to override the value specified in the properties files. Other values
   affecting certificate based login are taken from the properties file.

   The default properties file is ../../config/AMAgent.properties. Check to
   make sure the appropriate properties and values are set in the properties
   file before calling this program. The following properties are specific
   to authentication:
      com.sun.am.auth.orgName
      com.sun.am.auth.certificateAlias

am_sso_test

   Note: You must have an Identity Server with a user profile set up with the 
   LDAP authentication module before running this program.

   Description: am_sso_test logs into an Identity Server using the given user 
   and password using the LDAP authentication module, and performs sso token 
   operations on the session.

   Usage: 
      am_sso_test -u user -p password [-f properties_file] [-s session_url]

   Where:

   <user> 
   <password> 
       user and password to login to Identity server using the LDAP 
       authentication module.

   <properties_file> 
       the path to the properties file. If not set, the default properties 
       file ../../config/AMAgent.properties is used. Check to make sure 
       appropriate values are set in the properties file before calling 
       this program. See the Agents documentation for more information on the 
       properties file.

   <session_url> 
       the session URL of the Identity Server, if known. For example, 
       https://myhost/amserver/sessionservice. If not set (by default) 
       the naming service specified in the properties file is used to obtain 
       the session URL for the Token ID of the login session.


Executing the Sample Program on Solaris
---------------------------------------
   On Solaris platform you can run the sample programs by launching
   the generated executables on the command line. 

   Note: Set the LD_LIBRARY_PATH environment variable to include the
   lib directories, /usr/lib/mps:/opt/SUNWam/lib:/usr/lib:/usr/ucblib
   which contain libamsdk.so, libxml2.so, libssl3.so, libnss3.so,
   libplc4.so, libplds4.so, libnspr4.so, and libucb.so. The directory
   /usr/lib is included before /usr/ucblib so that common programs,
   like editors, will continue to function.

Executing the Sample Program on Windows
---------------------------------------
   On Windows platform you can run the sample programs by launching
   the generated executables on the command line
   
   Note: You must have the <sample-directory>/lib directory 
   in your path before launching the sample programs. 
   Alternatively, you can use the run.bat script to launch the sample programs 
   which will set your path appropriately.


Related References
------------------
   * RFC 1738: Uniform Resource Locators (URL). 
     Available at http://www.ietf.org/rfc/rfc1738.txt
   * GNU Project and Free Software Foundation (FSF) Website:
     http://www.gnu.org/


