|
| |
| Sun Java System Identity Server 2004Q2 Federation Management Guide | |
Chapter 2
Creating a Liberty Web Services EnvironmentIdentity Server provides a collection of sample files, named Sample1, to illustrate how to configure basic identity federation using one Service Provider and one Identity Provider. The example demonstrates the basic use of various Liberty protocols including Account Federation, Single Sign-On, Single Logout, and Federation Termination.
Instructions for implementing Sample1 are described in the following sections and should be completed in this sequence:
You will find all Service Provider and Identity Provider files required to implement the examples in the following locations:
Installing Identity Server
The first step in creating a Liberty environment is installing Identity Server on two separate machines. One Identity Server installation will act as a Service Provider, and one Identity Server installation will act as an Identity Provider. Follow the Identity Server installation instructions in the Java Enterprise System Installation Guide. Table 2-2 summarizes the variable placeholders and default values used in Sample 1.
Deploying the Service Provider
Before you can deploy the Service Provider, Identity Server must be installed and running over the HTTP(S) protocol. See Installing Identity Server.
Instructions for deploying the Service Provider are described in the following sections and should be completed in this sequence:
To Upload the Metadata for the Service Provider
- Update the following file with values appropriate to your Identity Server installation: begin_dir/samples/liberty/sample1/sp1/sp1Metadata.xml
Default values are listed in Table 2-2.
- Load sp1Metadata.xml using following command:
begin_dir/bin/amadmin -u amadmin -w password -t sp1Metadata.xml
To Configure the Service Provider
- Locate the AMClient.properties file located in this directory:
begin_dir/samples/liberty/sample1/sp1/WEB-INF/classes/
Replace the following tags with values appropriate for your environment:
SERVER_PROTO: Enter HTTPS or HTTP.
SERVER_HOST: Enter the fully-qualified hostname for your Identity Server installation. Example: www.sp1.com
SERVER_PORT: Enter the port number on which Identity Server is running.
SERVICE_DEPLOY_URI: Enter the Identity Service services deployment URI. The default value is amserver.
META_ALIAS: Enter the metaAlias for SP1. In sp1Metadata.xml, the default value is www.sp1.com.
- Create the.war file for SP1.
cd sp1_sample_dir
jar -cvf sp1.war- Deploy the sp1.war file.
See the next section.
To Deploy the Service Provider.WAR File
Choose one of the following as appropriate for your environment:
If Identity Server is installed on Sun Java System Web Server
- Before you deploy a web application manually, be sure that the server_root/bin/https/httpsadmin/bin directory is in your path and that the IWS_SERVER_HOME environment variable is set to your server_root directory.
- Enter the following command
wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_file
- uri_path is the URI prefix for the web application.
- instance is the server instance name.
- vs_id is the virtual server ID.
- directory is the directory to which the application is deployed, or from which the application is deleted. If not specified for deployment, the application is deployed to the document root directory.
- war_file is the WAR file name.
Example:
- Restart Web Server.
If Identity Server is installed on Sun Java System Application Server
- Use the asadmin deploy command to deploy the WAR module. The syntax is as follows:
For example, in Sample1 the asadmin deploy command deploys a web application as an individual module:
asadmin deploy --user admin --password pswd1234
--host www.sp1.com --port 4848 --type web --contextroot SP1
--instance server1 sp1.war
- Restart Application Server.
Deploying the Identity Provider
Before you can deploy the Service Provider, Identity Server must be installed and running over the HTTP protocol. See Installing Identity Server.
The instructions for implementing Sampe1 are described in the following sections and should be followed in this sequence:
To Upload the Metadata for the Identity Provider
- Update the following file as per your Identity Server installation: begin_dir/samples/liberty/sample1/idp1/sp1Metadata.xml
Default values are listed in Table 2-2.
- Load idp1Metadata.xml using following command.
begin_dir/bin/amadmin -u amadmin -w password -t idp1Metadata.xml
To Configure the Identity Provider
- Locate the AMClient.properties file located in this directory:
begin_dir/samples/liberty/sample1/idp1/WEB-INF/classes/
Replace the following tags with values appropriate for your environment:
SERVER_PROTO: Enter HTTP or HTTPS
SERVER_HOST: Enter a fully-qualified hostname for your Identity Server installation. Example: www.idp1.com
SERVER_PORT: Enter the port number where Identity Server is running.
SERVICE_DEPLOY_URI: Enter the Identity Server services deployment URI. The default value is amserver.
META_ALIAS: Enter the metaAlias for IDP1. In idp1Metadata.xml, the default value is www.idp1.com.
- Create the WAR file for IDP1.
cd idp1_sample_dir
jar -cvf idp1.war .- Deploy idp1.war.
See the next section, To Deploy the Service Provider.WAR File.
To Deploy the Identity Provider .WAR File
Follow the steps for one of the following:
If Identity Server is installed on Sun Java System Web Server
- Before you can deploy a web application manually, you must make sure that the server_root/bin/http/httpsadmin/bin directory is in your path and that the IWS_SERVER_HOME environment variable is set to your server_root directory.
- Enter the following command:
wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_file
- uri_path is the URI prefix for the web application.
- instance is the server instance name.
- vs_id is the virtual server ID.
- directory is the directory to which the application is deployed, or from which the application is deleted. If not specified for deployment, the application is deployed to the document root directory.
- war_file is the WAR file name.
Example:
wdeploy deploy -u /idp1 -i www.idp1.com -v https-www.idp1.com
-d begin_dir/web-apps/idp1 idp1.war- Restart the Web Server.
If Identity Server is installed on Sun Java System Application Server
- Use the asadmin deploy command to deploy the WAR module. The syntax is as follows:
asadmin deploy --user admin_user [--password admin_password]
[--passwordfile password_file] --host hostname --port adminport
[--secure | -s] [--virtualservers virtual_servers]
[--type application|ejb|web|connector]
[--contextroot contextroot] [--force=true] [--precompilejsp=false] [--verify=false]
[--name component_name] [--upload=true]
[--retrieve local_dirpath]
[--instance instance_name] filepath
For example, the following command deploys a web application as an individual module:
asadmin deploy --user admin --password pswd1234 --host www.sp1.com
--port 4848 --type web --contextroot IDP1 --instance server1 idp1.war(Optional) Configuring a Third Level Domain
The Sample1 application does not require the use of a third level domain. But if you want to configure third level domain, you can use the following instructions.
To Configure a Third-Level Domain
- Access the Identity Server administration console.
- Click the Federation tab.
- Select Authentication Domain in the View menu, and then click Show.
- Select sample1Alliance in the left pane.
- In the right pane, enter the Reader Service URL and Writer Service URL as appropriate for your common domain services installation.
For example, if common domain services are installed on machine3 with hostname is www.machine3.com, then for the default installation:
Writer Service URL: http://www.machine3.com:80/amcommon/writer
Reader Service URL: http://www.machine3.com:80/amcommon/transfer
Verifying a Successful Liberty Setup
The following sections provide detailed steps for using basic Liberty protocols to verify that you’ve successfully implemented Sample1:
SP1 has a protected page named index.jsp, and IDP1 has a protected page named index.jsp. Both protected pages include _head.jsp. The _head.jsp will check for a valid user session. If a session is invalid, the request is redirected to the Pre-Login service. The Pre-Login service attempts to perform a single sign-on (SSO). On first-time access, SSO will fail and the Pre-Login service redirects the request to the common Login page.
The protected page index.jsp contains the following three links:
Federate: Initiates the federation process.
Logout: Initiates the single logout process.
Terminate Federation: Initiates the federation termination process.
To Federate Service Provider and Identity Provider Accounts
- Access the following URL in a web browser:
SERVER_PROTO//SERVER_HOST:SERVER_PORT/sp1/index.jsp
Example:
http://www.sp1.com:58080/sp1/index.jsp
- In the common Login page, click the Local Login link.
You are redirected to the SP1's login page.
- Log in to SP1.
After successful authentication at SP1, the index.jsp is displayed.
- Click the Federate link.
The Federate page is displayed.
- Select the preferred Identity Provider you want to federate with.
In Sample1, select IDP1 as your preferred Identity Provider. IDP1's login page is displayed.
- Provide authentication credentials for your IDP1 account.
If the authentication is successful, the Federation Done page is displayed. This indicates that you have successfully federated your account between SP1 and IDP1.
Note that if the account is already federated, you will be redirected to the IDP login page.
To Perform a Single Sign-On
- After successful federation (see previous section, To Federate Service Provider and Identity Provider Accounts), start a new browser session and access the SP1 protected page:
SERVER_PROTO://SERVER_HOST:SERVER_PORT/sp1/index.jsp
Example:
http://www.sp1.com:58080/sp1/index.jsp
The user is redirected to the IDP1 Login page.
- Provide authentication credentials for your IDP1 account.
If authentication is successful, the initially accessed SP1 protected page is displayed without asking for SP1 authentication credentials.
If authentication is not successful, an error message is displayed, and you are directed to start over.
To Perform a Single Logout
In either the SP1 protected page or the IDP protected page, index.jsp, click the Logout link.You are logged out from both SP1 and IDP1, and the LogoutDone page is displayed.
To Terminate Account Federation
- In either the SP1 protected page or the IDP1 protected page, click the Terminate Federation link.
The Federation Termination page is displayed.
- Select a provider to terminate your account federation. For Sample1, select IDP1.
Upon successful federation termination, the Termination Done page is displayed.
Deploying a Web Service ConsumerDeploying a web service consumer entails the following:
Sample code for a web service consumer is provided with Identity Server to illustrate how to deploy and run a Liberty service client on top of the framework provided by Identity Server. All the files you need to deploy and initiate the service are located in the following directory:
install-dir/SUNWam/samples/phase2/wsc
Note
Before you can implement this web service consumer example, you must have two Identity Servers already installed, running, and Liberty-enabled. Complete the steps in Creating a Liberty Web Services Environment before you continue with this web service consumer example.
The Web Service Consumer Example
This example explains how you use the Discovery Service and Data Service Template client APIs to implement a web service client to communicate with a web service provider. In this example, the web service provider is the Personal Profile service that comes with Identity Server 2004Q2. The example demonstrates the flow of the Liberty Web Service Framework, and how the security mechanism and interaction service come into play in the federation process.
Once you’ve deployed and configured both a Service Provider and an Identity Provider, the Personal Profile service resides in the Identity Provider. Client code in the form of five .jsp files reside in the Service Provider. All the files you need to deploy and initiate the service are located in the following directory:
install-dir/SUNWam/samples/phase2/wsc
Table 2-3 summarizes the .jsp files provided with this example.
Table 2-3 JSPs provided in this sample
Name
Description
index.jsp
Retrieves boot strapping resource offering for discovery service.
discovery-modify.jsp
Adds Resource Offering for a user.
discovery-query.jsp
Sends query to discovery service for service resource offering.
id-sis-pp-modify.jsp
Sends Data Service Modify request to modify user attributes.
id-sis-pp-query.jsp
Sends Data Service Query Request to retrieve user attributes
Two machines are required for this sample:
Variable Placeholder
Host Name
Components Deployed on This Host
machine1
www.sp1.com
machine2
www.idp1.com
There are five parties involved in this sample:
Configuring the Service Provider
- Deploy the Liberty Sample1 Service Provider.
Follow the instructions in the section Deploying the Service Provider.
- Change the protocol support for the remote Identity Provider to ID-FF 1.2.
- Login to Identity Server Administration Console as Top-Level administrator.
- Click the Federation Management tab, and then in the View menu, choose Entity Descriptors.
- In the Entity ID list, choose the remote Identity Provider entity ID.
- In the right pane, in the View menu, choose Provider.l
- Under Provider, click the Edit link.
- Under the Protocol Support Enum field, choose urn:liberty:iff:2003-08.
- Click Save.
- Replace the following tags and hostnames in discovery-modify.jsp and index.jsp with values appropriate for your environment.
- IDP_SERVER_PORT: Enter server port of the Identity Provider host.
- SERVICE_DEPLOY_URI: Enter the service deployment URI of the Identity Provider host.
- www.sp1.com: Enter the host name of the Service Provider machine if it is different from www.sp1.com.
- www.idp1.com: Enter host name of Identity Provider machine if different from www.idp1.com.
- Deploy the Service Provider .jsp files.
Copy all the five .jsp files to a subdirectory in the document root of the web container. For example, if the web container is, Sun Java System Web Server 6.1 run following command:
mkdir webserber_install_root/docs/wsc
cp is_install_root/SUNWam/samples/phase2/wsc/*.jsp webserber_install_root/docs/wsc/- Log in to the Identity Server.
- Create a user named spUser.
This user will be used as a federated user on the Service Provider side.
Configuring the Identity Provider
- Deploy the Liberty Sample1 Identity Provider.
Follow the instructions in the section Deploying the Identity Provider.
- Register the Liberty Personal Profile Service.
- Create a user named idpUser with the Liberty Personal Profile Service enabled.
This user will be used as the federated user on the Identity Provider side. It is also used for storing the Discovery Service resource offering and Personal Profile Service attributes.
Running the Web Service Consumer Sample
The following is an overview of what happens when you run the Web Service Client sample that comes with the product.
- Complete the Liberty Single-Sign-On Process and obtain Discovery Service Boot Strapping Resource Offering.
- Register user's Resource Offering at the Personal Profile Service instance using Discovery Service Modification.
- Send Discovery Service Lookup request.
Discovery service returns the discovery lookup response to the Web Service Consumer. The lookup responses contains the resource offering for the user's Personal Profile Service instance.
- Send Data Service Query to the Personal Profile Service Instance to retrieve user attributes.
- Send Data Service Modification to the Personal Profile Service Instance to modify user attributes.
To Run the Web Service Client Sample
- Federate users spUser and idpUser.
See Verifying a Successful Liberty Setup for detailed instructions on federating user accounts, single sign-on, and single logout.
- As idpUser, perform a single sign-on from the Service Provider to the Identity.
- Using a browser, go to the following URL:
http://machine1:sever_port/wsc/index.jsp
You will see the boot strapping resource offering for the Discovery Service and two buttons: "Send Discovery Lookup" and "Add PP Resource Offering."
- Click "Add PP Resource Offering."
The discovery-modify.jsp page is displayed. The Personal Profile Service resource offering has been computed based on the bootstrapping Discovery Service Resource Offering.
- Click "Send Discovery Update Request.”
The user's Personal Profile resource offering is registered in idpUser on machine2.
- Click the "Return to index.jsp" link.
The index.jsp page is displayed; you see the bootstrapping resource offering.
- Click "Send Discovery Lookup."
The discovery-query.jsp page is displayed.
- (Optional) If you leave the “ServiceType to look for” field blank, all service instances will be returned.
You can enter a value in the "ServiceType to look for" field. Values are defined in the Liberty Web Service Consumer specification. For example, urn:liberty:idpp:2003-08 indicates a Personal Profile service.
- Click "Send Discovery Lookup Request."
The Personal Profile resource offering added in Step 4 will be displayed.
- Choose one of the following two options:
- To query the Personal Profile Service in machine2 for user attributes:
- Click "Send PP Query.”
The id-sis-pp-query.jsp page is displayed.
- In the Authentication Mechanism field, choose urn:liberty:security:2003-08:null:null.
- (Optional) You can change the value in the XPath Expression field to a different XPath expression for attribute selection. The default is /PP/CommonName.
- To modify a user's Personal Profile attributes:
- Choose one of the following:
- In the Authentication Mechanism field, choose urn:liberty:security:2003-08:null:null.
- (Optional) You can modify the XPath Expression field for attribute selection. The default is /PP/CommonName/AnalyzedName/FN. Then modify the Value to include new values for the attribute.
Interacting with the Personal Profile Service
Follow these instructions to verify that you’ve successfully implemented the Personal Profile Service and can perform basic interactions with it.
- Log in to Identity Server on machine2 as Top-Level administrator. This is the Service Provider.
- Create a policy for the Personal Profile service that requires user interaction for Query and Modify operations.
- In the console, click the Identity Management tab.
- In the View menu, choose Policies, and then click New.
- In the View menu for this policy, choose Rules, and then click Add.
- In the Service menu, choose "Liberty Personal Profile Service, " and then click "Next".
- In the Rule Name field, enter a name that will be meaningful to you.
- In the Resource Name field, enter an asterisk (*).
- Select the Modify or Query checkbox, or you can select them both.
- In the Value menu, select one of the following:
Interact for Consent: Select this option if you want to ask the user for consent.
Interact for Value: Select this option if you want to ask the user to provide values for the query response or the modify result.- Click OK.
- Click Save to save the rule.
- In the View menu for this policy, choose Subjects and then click Add.
- Enable policy evaluation for Personal Profile Service query and modify operations.
- To run the sample, follow the instructions in the section Running the Web Service Consumer Sample.
You can change the policy defined in Step 2 to see different behavior for user interaction.
X.509 Message Authentication
The following sections provides steps setting up X.509 Message Authentication, and for verifying that you’ve authentication work properly in your Sample1 deployment
Setup
- For machine1 and machine2, follow the instructions in the SAML xmlsig sample to set up the JKS signing key store:
is_install_root/SUNWam/samples/saml/xmlsig
- Edit /etc/opt/SUNWam/config/AMConfig.properties to reflect the key store, password and cert alias.
- In machine1, which is the Service Provider, locate the following file:
/etc/opt/SUNWam/config/AMConfig.properties.
Set the com.sun.identity.liberty.ws.wsc.certalias property to the alias of the signing certification.
To test X.509 Message Authentication in discovery service
- Log in to Identity Server as Top-Level administrator.
- Click the Service Configuration, then choose Discovery Service.
- In the Discovery Service page, under “Resource Offering for Bootstrapping Resources,”click Edit.
- In the Edit Resources Offering page, change the Authentication Mechanism from urn:liberty:security:2003-08:null:null to urn:liberty:security:2003-08:null:X509.
- Click Save.
To test X.509 Message Authentication in Personal Profile Service,
- Run the sample service. Follow the steps in the section Running the Web Service Consumer Sample.
- Perform a Personal Profile service query or modify operation.
Choose urn:liberty:security:2003-08:null:X509 as the Authentication Mechanism.
To test SSL (urn:liberty:security:2003-08:TLS:X509),
- Import the Ceritificate Authority (CA) for the Web Server on the Identity Provider (machine2) to the Web Server certificate database on the Service Provider (machine1).
- Run the sample service.
Follow the steps in the section Running the Web Service Consumer Sample.