
Sun Java System Access Manager 7.0: Distributed Authentication User Interface
=============================================================================

This file contains information on installing and using Access Manager
Distributed Authentication User Interface web application. 
It is assumed that 
- SUNWamclnt (Access Manager Client SDK package) is installed
- SUNWjato (JATO package) is installed
- Access Manager Server is available (remotely)
- Client SDK will be able to communicate with Access Manager Server using http(s)

Table of contents:
-----------------
1. Supported JDK versions
2. What does this package contain
3. Building web application
4. What does the <DISTAUTH_DEPLOY_URI>.war contain
5. Initializing Distributed Authentication web application
   5.1 Security Properties
6. Accessing Distributed Authentication User Interface


1. Supported JDK versions
-------------------------
Supported JDK versions are J2SE 1.4.1 or higher. In order to run
using JDK 1.3.1, the following additional jar files would be
needed in the CLASSPATH:
1) Java Authentication and Authorization Service (JAAS)
   http://java.sun.com/products/jaas/
2) Java Secure Socket Extension (JSSE) for SSL
   http:///java.sun.com/products/jsse/
3) JDK Logging (jdk_logging.jar). Can be obtained from
   SUNWamsdk package for Solaris and sun-identity-sdk RPM
   for Linux

2. What does this package contains
----------------------------------
<ZIP_ROOT>
|
|----README.distAuthUI (this file)
|
|----amauthdistui.war (Distributed Authentication Web application)
|
|----Makefile.distAuthUI (to build properties file and web application)


3. Building web application
---------------------------------------- 
The package contains "Makefile.distAuthUI" that can used to generate
and build required web application. The makefile defines
targets to build configuration properties and web application
and jars.

Steps involved in building the web application are:

Step 1: Edit Makefile.distAuthUI to provide the required parameters
        such as JAVA_HOME, protocol, hostname and port number of Access Manager
        server, notification URL, etc.
        Specifically the follows paramters must be provided:
             JAVA_HOME             
             SERVER_PROTOCOL
             SERVER_HOSTNAME
             SERVER_PORT
             SERVER_DEPLOY_URI
             APPLICATION_USERNAME
             APPLICATION_PASSWORD
             DISTAUTH_PROTOCOL
             DISTAUTH_HOSTNAME
             DISTAUTH_PORT
             DISTAUTH_DEPLOY_URI                     

Step 2: Run "make -f Makefile.distAuthUI"
        Generates a deployable war file is <DISTAUTH_DEPLOY_URI>.war that 
        can be deployed in any Servlet 2.3 compliant container.

The targets defined in the Makefile.distAuthUI are:

properties: Generates AMConfig.properties in the temp directory
            that can used as a template for setting AM Distributed 
            Authentication Web Application's properties

webapp: Generates <DISTAUTH_DEPLOY_URI>.war that can be deployed on any
        Servlet 2.3 compliant web container.

        For example, on SUN Java System Web server 6.1 (sp4) -
        ./wdeploy deploy -u <uri_path> -i <instance> -v <vs_id> 
        [ [-V <verboseLevel>]| [-q] ] [-n] [-d <directory>] <war_file>


4. What does the <DISTAUTH_DEPLOY_URI>.war contain
-----------------------------------------------
<WAR_ROOT>
|
|----index.html (Welcome page)
|
|----WEB-INF
|      |
|      |----web.xml
|      |----jato.tld
|      |----auth.tld
|      |----classes/AMConfig.properties
|      |----classes/amAuth.properties
|      |----classes/amAuthContext.properties
|      |----classes/amAuthUI.properties
|      |----lib/am_auth_dist_ui.jar
|      |----lib/jato.jar
|      |----lib/servlet.jar
|      |----lib/amclientsdk.jar
|
|----config
|      |
|      |----auth (Web client type specific directories containing JSP pages)
|
|----js (javascript files)
|
|----css (style sheet files)
|
|----images (branding images)
|

5. Initializing Distributed Authentication web application 
(if not already done in "3. Building web application")
------------------------------------------------------------
In order for the Access Manager Client SDK to communicate with
Access Manager Server, few properties have to be initialized.

These properties can be set in one of the following 3 ways:

  i) Using properties file: Setting the properties in a file and
     providing a path to it at runtime using "-Damconfig=<filename>".
     The properties files should be in the CLASSPATH.
     The default properties file name is AMConfig.properties
     and is always read at start-up. A sample AMConfig.properties
     can be generated using the command:
         "make -f Makefile.distAuthUI properties"
     The AMConfig.properties will be present in the temp directory.

  ii) Programatically using the Java API:
          com.iplanet.am.util.SystemProperties.initializeProperties(
              java.util.Properties properties)
      where properties contain the properties

  iii) Individual properties can be set at runtime using the "-D"
       flag. For example "-D<propertyName>=<propertyValue>"

The properties expected by Distributed Authentication web application are:

a) Naming URL property:
       com.iplanet.am.naming.url
       com.iplanet.am.naming.failover.url
   This is a manadatory property and it specifies the Access Manager
   Server's Naming URL. For example:
   com.iplanet.am.naming.url=http://is.red.iplanet.com/amserver/namingservice

b) Debug Level and Directory: The following properties specfies the
   debug level and directory respectively:
     com.iplanet.services.debug.level
     com.iplanet.services.debug.directory
   The possible values for debug levels are: off, error, warning, message

c) Notification URL property:
        com.iplanet.am.notification.url        
   This web application can register for changes to server attributes.
   The above property must be set to receive such notifications.

5.1 Security Properties
-----------------------
Some of the Access Manager components such as Service Management, 
User Management, etc. require an identity for the client (i.e., application)
to read configuration data and to identity the client. The identity
for the client can be set up by either providing a username and
password that can be authenticated, or by providing an implementation
for the interface com.sun.identity.security.AppSSOTokenProvider that
returns a single-sign-on (SSO) token.

a) For setting the username and password, the properties are:
    com.sun.identity.agents.app.username
    com.iplanet.am.service.password
    
b) For setting the SSO Token provider:
    com.sun.identity.security.AdminToken


6. Accessing Distributed Authentication User Interface
------------------------------------------------------

Access URL : 
http://<dist_auth_server_host>.<dist_auth_server_domain>:<dist_auth_server_port>/<DISTAUTH_DEPLOY_URI>/UI/Login

Note about successful redirect URL : 
This URL should always be absolute URL, ideally would be used as 
"goto=<absolute successful redirect URL>" query parameter with the above Access URL 
since this web application would be normally deployed in DMZ layer in production.

For testing purpose, if you happen to use the server returned default successful 
redirect URL (which is server's Admin Console URL) here, then make sure that you
change this URL from its relative value (/<SERVER_DEPLOY_URI>/console) to absolute 
value (<SERVER_PROTOCOL>://<SERVER_HOSTNAME>:<SERVER_PORT>/<SERVER_DEPLOY_URI>/console)
via server's Admin console in Authentication configuration / properties.
