
Liberty Employee Service Sample for Liberty Phase II



This sample shows how to develope, deploy and invoke a Liberty-enabled
service on top of the framework provided by Java System (JS) Identity
Server 2004Q2.

The emphasis is on how to add a new service to JS Identity Server.
Liberty Employee Profile (EP) service is the example service to be added
in this example.

For deployment and running of this sample, two Identity Server installations
are needed. One serves as Liberty Service Provider (SP), and one serves as
Liberty Identity Provider (IDP).

EP service will be located in IDP, and client code in the forms of jsp files
will be located in SP.

In the following description,
<EP_dir> = <install_dir>/SUNWam/samples/phase2/sis-ep

1. Developement
===============

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

1.1 Start with 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

First EP service and the related schema files are gathered under 
<EP_dir>/xsd/.

Now jaxb compiler "xjc" has to be available somewhere in your environment.
If not, download JWSDP 1.3 from Sun's web site.

Next, make sure to use the correct xjc.sh path inside the script
invoke_xjc.sh which is under <EP_dir>/bin, and then please do this:

# jar tvf <install_dir>/SUNWam/lib/am_services.jar | grep "impl/runtime"

Based on the result, replace the package name behind 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 result of the comiplation is a bunch of java files being auto-generated
from those xsd files and being placed under <EP_dir>/xsd/gen. 

(2) Compile the auto-generated java files

# <EP_dir>/bin/compile_gen.sh

The result is a bunch of class files being generated and placed under
<EP_dir>/classes. The <EP_dir>/classes directory is soft-linked from
<install_dir>/SUNWam/lib which is already on the web container's class
path.

1.2 Develope and compile the EP service code
--------------------------------------------

The sample code is already written and placed under <EP_dir>/src/ep.
Here a few things are noted about the procedures being followed and 
simplications being 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(Object request) method. The implementation 
need to process the incoming request object (DST Query or Modify), 
and return the result as response.

Identity Server'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 JS Identity
Server's service management API.

Some simplications are made in the code, e.g., no authorization,
only supporting urn:liberty:security:2003-08:null:null authentication
mechanism (i.e., no support for SSL/X509 Token/SAML Token), 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 developement and deployment
procedures for adding a new service instead of trying to implement
every aspect of a complete EP service.

Now lets compile these hand-written code.

# cd <EP_dir>/src
# make

The generated class files are placed under <EP_dir>/classes, together
with those class files compiled from auto-generated jaxb java files.

1.3 Setting up back-end data store
----------------------------------

This step has to do with JS Identity Server backend data store and service
management (for more details, see JS Identity Server Administration Manual).
 
(1)  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.

(2) 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 JS Identity Server service management schema defined 
in <EP_dir>/xml/amLibertyEmployeeProfile.xml into the Identity Server
(ultimately into directory server). This has to do with JS Identity
Server service management through API (which is used the our 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.

This roughly ends the developement phase, even though some steps above
already have to do with deployment.

2. Deployment
=============

Some of the steps below have to do with set up the EP service, some have to
do with set up Liberty scenario in general.

2.1 Server side deployment on the IDP machine
---------------------------------------------

(1) Configure SOAP Receiver to recognize EP Request Handler

Login to Identity Server's admin console as top level administrator.
Go to "Service Config" Panel, select "SOAP Binding" on the left,
then on the right, add "key=idep|class=ep.EPRequestHandler" to "RequestHandler
List". Note that 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.

In /etc/opt/SUNWam/config/AMConfig.properties, add "ep.jaxb" to the property
"com.sun.identity.liberty.ws.jaxb.packageList". This is to let SOAP binding 
layer knows about the EP service jaxb package which is new to JS Identity 
Server platform.

(2) Register EP Service to the default org

Still as top level administrator, go to Identity Management, choose "Services"
in View  menu, click "Add". Select "Liberty Employee Profile Service" on the
right panel, click "OK".

(3) Create a user called "idpUser"

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.

(4) Deploy liberty sample1 IDP

Follow the instruction in <install_dir>/SUNWam/samples/liberty/sample1/idp1.
This is to set up a runnable liberty scenario.

If this is already done, then simply skip this step.

(5) Restart the server

Restart the web container in which Identity Server is running.

2.2 Client side deployment on the SP machine
--------------------------------------------

Please note that so far everything is done on the IDP machine. Now you need to
get on to the SP machine and do the following.

(1) Deploy liberty sample1 SP

Follow the instruction in <install_dir>/SUNWam/samples/liberty/sample1/sp1.
This is to set up a runnable liberty scenario.

If this is already done, then simply skip this step.

(2) Change protocol support of the remote IDP  to ID-FF 1.2

Login to Identity Server Administration Console as top level administrator,
go to Federation Management, select "Entity Descriptors" View,  click the remote
IDP entity ID from the list,  select "Provider" on the View menu in the right
panel, click the "[Edit...]"  link under Provider, select
"urn:liberty:iff:2003-08" under the "Protocol Support Enum" field (enter an
integer value, e.g. 60, in the "Cache Duration" field if it is empty), then
click "Save".

If this is already done, then simply skip this step.

(3) 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. 

(4) 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 <webserber_install_dir>/docs/ep
# cp <is_install_dir>/SUNWam/samples/phase2/ep/*.jsp <webserber_install_dir>/docs/ep/

(5) Create a user called "spUser"

Login to identity server 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.

(6) Restart the server

Restart the web container in which Identity Server is running.

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

3.1 Federate user "spUser" and "idpUser"
----------------------------------------

Follow Liberty sample1, and logout.

3.2 Single-sign-on 
------------------

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

3.3 Invoke EP service client
----------------------------

Use your browser, connect to "http://<machine1>:<sever_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".

3.4 Add EP Resource Offering
----------------------------

Click "Add PP 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. 

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

3.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 3.4 will be displayed. 

3.8 EP Query and modify
-----------------------

There are two options in this page:
 
(1) 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. 
       
(2) Click "Send PP 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.
