| Main Page >
    Liberty Sample Page
 Liberty Employee Service Sample for Liberty Phase II
 
 1. Introduction
    This sample shows how to develop, deploy and invoke a Liberty-enabled
    service on top of the liberty framework provided by Sun Java System (SJS) 
    Access Manager 7 2005Q4.
    
    The emphasis is on how to add a new service to SJS Access Manager.
    Liberty Employee Profile (EP) service is the sample service to be added.
    For deployment and running this sample, two Access Manager installations
    are needed. One serves as the Liberty Service Provider (SP), and the other 
    serves as Liberty Identity Provider (IDP).
    EP service will be located in IDP, and client code which in this sample are
    jsp files will be located in SP.
    
 The following variables are used :
 
    Solaris Sparc/x86 : 
	<BEGIN_DIR>  = <INSTALL_DIR>/SUNWam
	<CONFIG_DIR> = /etc/opt/SUNWam/config
    Linux : 
	<BEGIN_DIR>  = <INSTALL_DIR>/identity
	<CONFIG_DIR> = /etc/opt/sun/identity/config
    <EP_dir> : <BEGIN_DIR>/SUNWam/samples/phase2/sis-ep
    
 
 2. Development
    All the following steps are on IDP installation.
     
    Please first modify <EP_dir>/bin/install_dir.var file to change the value
    of the variable INSTALL_DIR to match your Access Manager installation directory.
     
 
Loading the Service Schema
 The xsd file which defines the EP service schema is the starting point
       for developing the EP service server-side code.
 
 1. Invoke jaxb compiler on xsd files
 
 EP service and the related schema files are under <EP_dir>/xsd/.
 2. Get the Runtime classes package name by doing the following:
 
       jar tvf <BEGIN_DIR>/lib/am_services.jar | grep "impl/runtime"
       Replace the package name returned by the above command after the option
       -use-runtime in the scripts invoke_xjc.sh. Then invoke it:
       <EP_dir>/bin/invoke_xjc.sh
       Note that xjc.sh needs JAVA_HOME environment variable to be set, it
       should point to a JDK version equal to or above 1.4.
 The java files which are auto-generated from the xsd files
       are under <EP_dir>/xsd/gen.
 
 2. Run the following command to compile the auto-generated java files
 
       <EP_dir>/bin/compile_gen.sh
       The class files generated are placed under <EP_dir>/classes. 
       The <EP_dir>/classes/ep directory is soft-linked
       from <BEGIN_DIR/lib which is in the web container's
       class path.
 
Develop and compile the EP service code
 The sample code is under <EP_dir>/src/ep.
       Here a few things are noted about the procedures being followed and 
       simple assumptions made in the sample code.
 When developing a new Data Service, use EPRequestHandler.java as a
       template for your new code, only thing need to implement in your code
       is the processDSTRequest() method. The implementation needs to process
       the incoming request object (DST Query or Modify), and return the result
       as response.
 Access Manager's backend data store is used here in this sample to
       store the requested EP data. The procedures for setting that up will
       follow next. The code for getting and setting the data is using SJS Access
       Manager's service management API.
 Some simplifications are made in the code, e.g., no authorization,
       only supporting urn:liberty:security:2003-08:null:null authentication
       mechanism, simple-minded select string parsing (instead of using XPATH
       API), a few attributes such as LInternalJobTitle, LOU, LCN, LAltCN and
       LLegalName not supported.
 This sample is trying to demonstrate the development and deployment
       procedures for adding a new service instead of trying to implement
       every aspect of a complete EP service.
 Compiling the code:
 
       cd <EP_dir>/src
       gmakeThe generated class files are placed under <EP_dir>/classes,along 
       with the class files compiled from auto-generated jaxb java files.
 
Setting up back-end data store
 This step has to do with SJS Access Manager backend data store and service
       management (for more details, see SJS Access Manager Administration
       Manual).
 
 a. Load EP ldif file (directory server schema)
 
       cd <EP_dir>/binModify load_ldif.sh file content to match your installation enviroment,
       such as host name, directory server port and password. Then run the
       script:
       ./load_ldif.shThis loads the directory server schema defined in <EP_dir>/ldif/ep.ldif
       into the directory server. The attribute names used in ldif file are
       the ones used in EmployeeProfile.java in <EP_dir>/src/ep.
 b. Load EP service management schema
 
 Still inside <EP_dir>/bin, modify load_xml.sh to change the amadmin's
       password and DN, and then run the command:
 
       ./load_xml.shThis loads the SJS Access Manager service management schema defined 
       in <EP_dir>/xml/amLibertyEmployeeProfile.xml into the Access Manager
       (ultimately into directory server). This has to do with SJS Access
       Manager service management through API (which is used by the EP service
       code for accessing EP data) and console. Note that the attribute names
       in the xml file are the same as those in ep.ldif file.
 
 
 
 3. Deployment
    Following steps describe setup of EP Service and Liberty :
     
 
Server side deployment on the IDP machine
 a. Configure SOAP Receiver to recognize EP Request Handler
 
 
       1.Login to Access Manager's Admin Console (/SERVER_DEPLOY_URI/console) 
	 as top level administrator. c. Create a user called "idpUser"2.Select "Web Services" tab.
 3.Select "SOAP Binding Service" sub tab.
 4.Click on "New" in the Request Handler List Section.
 5."Add Request Handler" Page will be displayed.
 6.In the Key Field enter "idep".
 7 In the Class Field enter ep.EPRequestHandler".
 Note: ep.EPRequestHandler is the class name for
       <EP_dir>/src/ep/EPRequestHandler.java which extends DSTRequestHandler.
       and idep will be part of the uri used to invoke EP service.
 8.In <CONFIG_DIR>/AMConfig.properties, add "ep.jaxb" to the
       property "com.sun.identity.liberty.ws.jaxb.packageList". This is to
       let SOAP binding layer know about the EP service jaxb package which
       is new to SJS Access Manager platform.
 
 
 In the Access Manager Admin Console :
 
           - Select Access Control Tab . This user will be used as the federated user on the IDP side, also as
       storage of Discovery Service resource offering and EP Service attributes.
       You must select "Liberty Employee Profile Service" in the "Available
       Services" when creating the idpUser (otherwise EP modify will fail).- Select Realm under which the user should be created .
 - Select Subjects -> User -> New. Enter the values for all
             required fields (marked *)
 .
	   - Select Create to create the user.
 
 If "idpUser" already exists, then simply add "Liberty Employee Profile
       Service" for this user.
 
 d. Set up the Liberty Scenario.Deploy liberty sample1 Identity Provider (IDP)..
 Follow the instruction in
       <BEGIN_DIR>/samples/liberty/sample1/idp1.
 If this is already done, then simply skip this step.
 
 e. Restart the web container in which Access Manager Web Applications are running.
 
 
Client side deployment on the SP machine
       a. Deploy liberty sample1 SP
       Follow the instruction in
       <BEGIN_DIR>/samples/liberty/sample1/sp1. This is to set
       up a runnable liberty scenario.
 If this is already done, then simply skip this step.
 
 b. Change protocol support of the remote IDP to ID-FF 1.2
 Login to Access Manager Administration Console as top level
       administrator:
 
	- Select "Federation"  tab.- Select "Entities" sub tab.
 - Click the remote IDP entity ID from the list.
 - Select "Identity Provider" from the View drop down menu.
 - Change the value of "Protocol Support Enumeration" attribute to "urn:liberty:iff:2003-08".
 - Click on "Save" button to save the changes.
 
 If this is already done, then simply skip this step.
 
 c. Replace tags and hosts in  discovery-modify.jsp and index.jsp
 All the JSP files are under <EP_dir>/jsp/. Inside, DST client API
       and Discovery client API are used for sending query/modify requests
       and receiving query/modify responses.
 
 
       Replace IDP_SERVER_PORT with server port of IDP machine.Replace SERVICE_DEPLOY_URI with service deployment URI of the IDP
       machine.
 Replace www.sp1.com with host name of the SP machine if needed.
 Replace www.idp1.com with host name of IDP machine if needed.
 
 d. Deploy JSP files
 Copy all the five JSP files to a sub directory of the document root of
       the web container.
 In case of Sun Java System Web Server 6.1, run following command:
 
       mkdir <webserver_install_dir>/docs/ep
       cp <BEGIN_DIR>/samples/phase2/ep/*.jsp
          <webserver_install_dir>/docs/ep/
       e. Create a user called "spUser"Login to access manager admin console, create a user called "spUser".
       This user will be used as federated user on the SP side.
 If this is already done, simply skip this step.
 
 f. Restart the server
 Restart the web container in which Access Manager is running.
 
 
 4. Run the sample
    Here are the steps to run the sample. These steps are similar to the
    wsc sample if you have run it already.
     
 
Federate user "spUser" and "idpUser"
       Follow Liberty sample1, and logout.
 
 
Single-sign-on 
       Single sign on from SP to IDP using "idpUser".
 
 
Invoke EP service client
       Use your browser, connect to
       "http://<SP_machine>:<server_port>/ep/index.jsp".
       You will see the boot strapping resource offering for Discovery Service,
       also two buttons, one for "Send Discovery Lookup", one for "Add EP
       Resource Offering".
 
 
Add EP Resource Offering
       Click "Add EP Resource Offering", this will lead to discovery-modify.jsp
       page, the EP resource offering has been computed based on the boot
       strapping Discovery Service Resource Offering.
 
 
Send Discovery Update Request
       Click "Send Discovery Update Request", the user's Employee Profile
       resource offering will be registered in "idpUser" on the IDP machine.
 
 
Back to the first page
       Click "Return to index.jsp" link, this will bring you back to index.jsp
       page with boot strapping resource offering.
 
 
Send Discovery Lookup
       Click "Send Discovery Lookup" button, this will lead to
       discovery-query.jsp page. Fill in "ServiceType to look for" field if
       needed. Click "Send Discovery Lookup Request", the EP resource offering
       added in step 4 will be displayed.
 
 
EP Query and modify
       There are two options in this page:
 
 a. Click "Send EP Query" will lead to id-sis-ep-query.jsp page, which
          will query Employee Profile Service in the IDP machine for user's
          employee profile attributes. You could change the "XPath Expression"
          field (default to /EP/EmployeeID) for different XPath expression for
          attribute selection.
 
 b. Click "Send EP Modify" will lead to id-sis-ep-modify.jsp page, which
          will send Modify request to Employee Profile Service in the IDP
	  machine to modify user's employee profile attributes. You could
	  modify "XPath Expression" field (default to /EP/EmployeeID) for
	  attribute selection, and "Value" field for new values for the
	  attribute.
 
 You could repeat above process for discovery/id-sis-ep query and modify
       cases.
 
 Note that you should first use Modify to set a value for an attribute,
       then be able to use Query to retrieve it, otherwise you'll get an
       exception complaining the value is not set. Alternatively, you could
       set all the values using Admin Console first, and then come to this
       page without worrying about having to do Modify before Query.
 |