Sun Java System Access Manager version 7 2005Q4
Sample
 

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.

  1. 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.

  2. 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
           gmake
    The generated class files are placed under <EP_dir>/classes,along with the class files compiled from auto-generated jaxb java files.

  3. 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>/bin
    Modify 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.sh
    This 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.sh
    This 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 :

  1. 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.
      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.

    c. Create a user called "idpUser"
    In the Access Manager Admin Console :
      - Select Access Control Tab .
      - 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.
    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).
    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.

  2. 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.

  1. Federate user "spUser" and "idpUser"
    Follow Liberty sample1, and logout.

  2. Single-sign-on
    Single sign on from SP to IDP using "idpUser".

  3. 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".

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.


End of Sample