------------------------------------------------------------------------------

README file for Open Federation Library

------------------------------------------------------------------------------

DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

Copyright (c) 2008 Sun Microsystems Inc. All Rights Reserved

The contents of this file are subject to the terms

of the Common Development and Distribution License

(the License). You may not use this file except in

compliance with the License.

You can obtain a copy of the License at

https://opensso.dev.java.net/public/CDDLv1.0.html or

See the License for the specific language governing

permission and limitations under the License.

When distributing Covered Code, include this CDDL

Header Notice in each file and include the License file

at opensso/legal/CDDLv1.0.txt.

If applicable, add the following below the CDDL Header,

with the fields enclosed by brackets [] replaced by

your own identifying information:

"Portions Copyrighted [year] [name of copyright owner]"

$Id: README,v 1.3 2008/11/24 18:51:13 alanchu Exp $

%% Contents:

%% 1. Contents of this directory

%% 2. How to use AG.war with your Fedlet application

%% 1. Contents of this directory

This README file provides information on Assertion Generator (AG).

The Assertion Generator is a deployable WAR which could be used to

generate SAMLv2 Single Sign-on Assertions to validate your Fedlet setup.

AG.zip

|

|- AG.war Assertion Generation WAR file. This is a ready-to-deploy

| WAR to test the Fedlet configuration.

|

|- README This README file. The file shows how to use the

Assertion Generator with your Fedlet application.

%% 2. How to use AG.war with your Fedlet application

<Prerequisites>

- Before deploying the Assertion generator war file, the Fedlet

has to be deployed and configured, i.e. there should a Fedlet

home directory that contains the IDP and Fedlet (SP) meta data.

- The Assertion generator WAR has to be deployed in the same web

container where your Fedlet application is deploy.

<Steps to Validate the Fedlet>

Step 1: Back up the Fedlet home directory

Save a copy of the whole Fedlet home directory before making

following changes. You will need to restore them before running

Fedlet application with your real IDP.

Step 2: Configure Assertion Generator

Depending on whether the priate key from the real IDP is available

or not, follow the instructions described in one of the two cases

below to configure your Assertion Generator:

Case I: If the private key from the real IDP is not available (this

is the most common case)

(a) Remove the idp.xml and idp-extended.xml from the Fedlet home

directory.

(b) Restart the web container.

(c) Access the AG index.jsp page. AG will copy a test IDP metadata

and keystore to the Fedlet home directory. The test IDP will

be used to validate your Fedlet setup.

Case II: If the private key from the real IDP is available

(a) Import the the private key into the "keystore.jks" under

your Fedlet home directory. This has to be done after

accessing the Assertion Generator index.jsp and before

actually running the assertion generation test.

Note: Make sure you are using the alias name "test" when

importing the private key into the keystore.jks file (you need

to remove the bundled "test" private key before importing the

new one).

Step 3: Edit the "FederationConfig.properties"

Edit the "FederationConfig.properties" under your Fedlet home

directory. Replace all occurence of "@FEDLET_HOME@" with the

actual fedlet home directory name, e.g. "/fedlet".

Step 4: Restart your web container.

Step 5: Access the AG index.jsp page using your browser to validate

the Fedlet

The AG index page has relaystate and attribute input fields for

you to enter. To add attributes, you first need to remove the

null value. Selecting the null value from the first column and

click on the remove button will remove the value. To add an

attribute, enter the name and value of the attribute in the

respective field and click the "Add" button.

Once all the desired attribute have been entered, select all

the values under the Name column and select all the values

under the Value column, click "Submit Query" button to run the

Assertion Generator code.

The AG will create a SAML2 Single Sign-on Assertion and post

it to your Fedlet application. If your Fedlet is configured

correctly, Single Sign-on will be successful, and your Fedlet

application will be invoked.

Step 6: Restore the original Fedlet home directory

Restore the original Fedlet home directory before running

Fedlet application with your real IDP.