README revision 07e7dcd4d7f52b182ecc8bc086fb9b8369bf1d93
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock------------------------------------------------------------------------------
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockREADME file for Open Federation Library
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock------------------------------------------------------------------------------
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockCopyright (c) 2008 Sun Microsystems Inc. All Rights Reserved
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockThe contents of this file are subject to the terms
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockof the Common Development and Distribution License
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock(the License). You may not use this file except in
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockcompliance with the License.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockYou can obtain a copy of the License at
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockhttps://opensso.dev.java.net/public/CDDLv1.0.html or
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockSee the License for the specific language governing
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockpermission and limitations under the License.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockWhen distributing Covered Code, include this CDDL
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockHeader Notice in each file and include the License file
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockIf applicable, add the following below the CDDL Header,
ac88567a7a5bb7f01cf22cf366bc9d6203e24d7aHyon Kimwith the fields enclosed by brackets [] replaced by
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockyour own identifying information:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock"Portions Copyrighted [year] [name of copyright owner]"
ac88567a7a5bb7f01cf22cf366bc9d6203e24d7aHyon KimPortions Copyright 2012 ForgeRock AS
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock%% Contents:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock %% 1. Contents of this directory
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock %% 2. How to use fedlet.war for demo.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock %% 3. How to embed Fedlet into existing application
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock %% 4. How to integrate with existing application after Single Sign-on
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock %% 5. How to enable Fedlet to support multiple Identity Providers
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock %% 6. How to enable Identity Provider Discovery service in Fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock %% 7. How to perform Fedlet Attribute Query
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock %% 8. How to perform Fedlet XACML Query
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock%% 1. Contents of this directory
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock This README file provides information on Fedlet ZIP file with pre-configured
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock IDP and Fedlet (SP) metadata.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock |- fedlet.war Fedlet WAR file. This is a ready-to-deploy WAR
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock | to show the Fedlet features.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock |- README This README file. The file shows how to use Fedlet.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock%% 2. How to use fedlet.war for demo
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock The fedlet.war contains all necessay bits for Fedlet to acting as a
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock light-weighted SAMLv2 Service provider. It also provides convenient ways
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock to setup and validate Fedlet deployment.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock After deploying fedlet.war into your web container, try access the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Fedlet(SP) index.jsp page to start Fedlet setup, e.g.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <SP_PROTOCOL>://<SP_HOST>:<SP_PORT>/<SP_DEPLOY_URI>/index.jsp
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock If this is the first time the page is accessed, it will show that the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Fedlet home directory is not configured yet, and a link will be provided
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock for you to create the configuration automatically. After done, you will
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock be shown links to start Fedlet(SP) and IDP initiated Single Sign-on.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Click the link, you will be redirected to IDP for login, then Single
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Sign-on to Fedlet(SP). Upon successful completion, a Fedlet(SP) side JSP
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock will be presented to show the SSO Response, Assertion and
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock AttributeStatement if any.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock%% 3. How to embed Fedlet into your existing application WAR
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) Extract the fedlet.war into a temporal directory.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) Copy files inside "conf" directory to a sub directory named "fedlet"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock under your web container running user's home directory (pointed by
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock JVM property "user.home"). For example, assume running user's home
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock directory is "/home/webservd":
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock The "fedlet" subdirectory under the web container running user's home
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock is the default location for Fedlet to read its metadata, COT and
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock configuration properties. To change this default directory, set the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock value of a JVM run-time property "com.sun.identity.fedlet.home" to the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock desired location. For example:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock this will tell Fedlet to read metadata/COT/configuration files from
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "/export/fedlet/conf" directory instead.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) Copy all other files to your application WAR staging directory, overlay
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock them with your existing application WAR structure.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Optionally you could remove index.jsp, fedletEncode.jsp and "conf"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock directory from the temporal directory created in step a) before copying.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock d) Create the application WAR and redeploy in your web container.
9af3851a3a831b4de34b42482c22351e14f33f16eschrock%% 4. How to integrate with existing application after Single Sign-on
9af3851a3a831b4de34b42482c22351e14f33f16eschrock There is a sample Fedlet application, fedletSampleApp.jsp, bundled
9af3851a3a831b4de34b42482c22351e14f33f16eschrock with fedlet.war. The fedletSampleApp.jsp first invokes a util method
9af3851a3a831b4de34b42482c22351e14f33f16eschrock to complete SAMLv2 protocol processing. A map containing various data,
9af3851a3a831b4de34b42482c22351e14f33f16eschrock including Response/Assertion/Attributes, is returned to caller for further
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock processing. The fedletSampleApp.jsp also provides some sample code on
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock how to retrieve data from the returned map.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock You could either modify fedletSampleApp.jsp to add your application
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock specific logic or replace fedletSampleApp.jsp with your own servlet/jsp.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock To replace fedletSampleApp.jsp with new servlet/JSP:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock 1. Modify web.xml to set servlet and servlet-mapping for your new servlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock or JSP. You must map your new servlet/JSP to the url-pattern
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "/fedletapplication" since it is the URI set in the Fedlet metadata
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock (the assertion consumer URL). For example:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <servlet-name>yourapplication</servlet-name>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <jsp-file>/Your-Application.jsp</jsp-file>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <servlet-mapping>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <servlet-name>yourapplication</servlet-name>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <url-pattern>/fedletapplication</url-pattern>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </servlet-mapping>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock 2. Copy following code from fedletSampleApp.jsp to your
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock application processing code with proper import statement:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock // invoke the Fedlet processing logic. this will do all the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock // necessary processing conforming to SAMLv2 specifications,
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock // such as XML signature validation, Audience and Recipient
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock // validation etc.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock map = SPACSUtils.processResponseForFedlet(request, response);
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock} catch (SAML2Exception sme) {
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock response.sendError(response.SC_INTERNAL_SERVER_ERROR, sme.getMessage());
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock} catch (IOException ioe) {
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock response.sendError(response.SC_INTERNAL_SERVER_ERROR, ioe.getMessage());
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock} catch (SessionException se) {
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock response.sendError(response.SC_INTERNAL_SERVER_ERROR, se.getMessage());
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock} catch (ServletException se) {
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock response.sendError(response.SC_BAD_REQUEST, se.getMessage());
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock After obtaining the returned "map" object, you could follow the sample
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock code to retrieve data needed for your business logics.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock%% 5. How to enable Fedlet to support multiple Identity Providers
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock To configure second Identity Provider with this Fedlet:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) Get the standard metadata XML file for the new Identity Provider, name
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the XML file as "idp2.xml" and copy it to the Fedlet home directory.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) Decide on the circle-of-trust (COT) the new Identity Provider would
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock belong. This IDP could be added to an existing COT (e.g. "saml2cot") or
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a brand new COT.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock ** To add the Identity Provider to an existing COT, edit the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock corresponding COT file (e.g. "fedlet.cot") under your Fedlet home
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock directory, and append the new IDP entity ID (pointed by the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "entityID" attribute in the "idp2.xml" metadata file) to the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock value of "sun-fm-trusted-providers" attribute using "," as separator.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock ** To add to a new circle-of-trust:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock -- create a new file named "fedlet2.cot" and put it under the Fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock home directory. Use the existing fedlet.cot as a template, but
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock change the value of attribute "cot-name" to the actual name of
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the new COT (e.g. "cot2"), and include both the new IDP entity ID
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock and the Fedlet entity ID as value for "sun-fm-trusted-providers"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock attribute (two entity IDs separated by ",").
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock -- edit the sp-extended.xml file, add the new COT name to the value
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock of "cotlist" attribute, e.g.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Attribute name="cotlist">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>saml2cot</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>cot2</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </Attribute>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) Create a new "idp2-extended.xml" file as the extended metadata for the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock new Identity Provider. Use the existing idp-extended.xml as a template
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock but change the "entityID" to the new IDP entity ID, change the value for
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "cotlist" attribute to the COT name if a new COT is created for the IDP.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Note : make sure the second IDP is a remote IDP by setting the "hosted"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock attribute in the EntityConfig element to "false".
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock d) Send the Fedlet metadata XML file (i.e. "sp.xml" under your Fedlet home)
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock to the second IDP, import the metadata in the remote IDP and add it to
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the same circle-of-trust as the IDP.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Repeat the same steps for the third, fourth, ... and [x]th IDP, use
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock idpx.xml/idpx-extended.xml/fedletx.cot as standard meta/extended meta/COT
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock name for the new IDP. Restart your Fedlet web container to make the change
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Now accessing the index.jsp again, it will prompt you with a list of IDPs
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the Fedlet trusted. You could choose any of the IDP and perform Single
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock%% 6. How to enable Identity Provider Discovery service in Fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock When Fedlet is setup with multiple Identity Providers in a COT, it could be
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock configured to use IDP Discovery service to find out the preferred IDP.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock You need to have the Identity Provider Discovery service set up before
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock performing following steps. If you installed the OpenSSO WAR, the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock IDP discovery service is bundled in the products already. Or you could
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock follow the document to create a separate WAR for the IDP discovery
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock service using the OpenSSO WAR. Please refer to the OpenSSO
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock document set on how to setup and use the Identity Provider
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Discovery service. After set up the IDP discovery service, have the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock reader service URL (URL to find out preferred IDP) and writer service
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock URL (URL to write the preferred IDP) ready, they are needed in step
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) and c) below. If you are using OpenSSO server instance
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock or the IDP discovery only WAR instance, the reader service URL is:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <protocol>://<host>:<port>/<deploy_uri>/saml2reader
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock (e.g : http://discovery.common.com/opensso/saml2reader)
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the writer service URL is :
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <protocol>://<host>:<port>/<deploy_uri>/saml2writer
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock (e.g : http://discovery.common.com/opensso/saml2writer)
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock To setup IDP discovery in the Fedlet:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) edit the COT file (e.g. "fedlet.cot"), and set the value for attribute
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "sun-fm-saml2-readerservice-url" to the SAML2 reader service URL
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock (e.g. http://discovery.common.com/opensso/saml2reader), set the value
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock for attribute "sun-fm-saml2-writerservice-url" to the SAML2 writer
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock service URL (e.g. http://discovery.common.com/opensso/saml2writer).
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) Restart your Fedlet web container to make the change to be effective.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) Setup IDP discovery on each of your IDPs. If your IDP is an OpenSSO
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock server instance, need to goto console, find the COT for
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the IDP and Fedlet, and specify the SAML2 reader service URL and
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock SAML2 writer service URL.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock d) Access the Fedlet index.jsp page, you will be presented with IDP
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock selection page. Don't click the "use IDP discovery service ..."
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock link yet, as your preferred IDP has not been set yet. Choose one
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock of the IDPs, and complete the Single Sign-on process. The preferred IDP
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock is set right now by the IDP discovery service.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) Access the Fedlet index.jsp page again, and choose the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "use IDP discovery service to find out preferred IDP" link.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock You will be redirected to the IDP discovery service to find out
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the preferred IDP and send back to Fedlet side with the chosen
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock IDP to start the Fedlet initiated single sign-on.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock%% 7. How to perform Fedlet Attribute Query:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock II. Signing and Encryption
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock III. Testing
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Following steps need to be performed on hosted IDP:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) When creating the IDP entity metadata, make sure that you specify that
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock particular entity with Attribute Authority role. Also the reponse from
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Attribute Authority needs to be signed. Enable signing for Attribute
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Authority role.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) Specify the list of attributes to be fetched in the Attribute Map
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock IDP Entity -> Assertion Processing -> Attribute Map
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock ex : CommonName=cn
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock GiveName=sn
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock UserStatus=inetUserStatus
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) Create the Fedlet.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Following steps need to be performed on Fedlet side:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) Deploy fedlet.war and configure the fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) The Attribute Query needs to be signed. Please follow the links
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock below on creating a key store and using the certificate.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock http://openam.forgerock.org/doc/admin-guide/index.html#change-signing-key
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock http://openam.forgerock.org/doc/dev-guide/index.html#fedlet-signing-encryption
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Add the certificate to the "RoleDescriptor" element as shown below
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <RoleDescriptor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock xsi:type="query:AttributeQueryDescriptorType"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock protocolSupportEnumeration= "urn:oasis:names:tc:SAML:2.0:protocol">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <KeyDescriptor use="signing">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:X509Data>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:X509Certificate>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock --certificate--
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:X509Certificate>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:X509Data>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:KeyInfo>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </KeyDescriptor>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </RoleDescriptor>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) In the "sp-extended.xml", specify the correct value for
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "signingCertAlias" inside the AttributeQueryConfig element as follows:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Attribute name="signingCertAlias">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>test</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </Attribute>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock d) Goto Step (1) i.e to Hosted IDP side
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock e) Delete existing fedlet metadata and obtain the standard metadata
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockII. Signing and Encryption
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock==========================
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Following steps need to be performed on hosted IDP:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) When creating the IDP entity metadata, make sure that you specify that
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock particular entity with Attribute Authority role. Also the response from
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Attribute Authority needs to be signed. Enable signing for Attribute
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Authority role. Enable encryption for the IDP Attribute Authority
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) Specify the list of attributes to be fetched in the Attribute Map
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock IDP Entity -> Assertion Processing -> Attribute Map
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock ex : CommonName=cn
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock GiveName=sn
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock UserStatus=inetUserStatus
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) Specify the Attribute Authority Mapper.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock IDP Entity -> Attribute Authority -> Subject Data Store
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Specify the Attribute name which contains X.509 Subject DN.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock d) Create the Fedlet.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Following steps need to be performed on hosted SP:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) Deploy fedlet.war and configure the fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) For signing and encryption, please follow the links
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock below on creating a key store and using the certificate.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock http://openam.forgerock.org/doc/admin-guide/index.html#change-signing-key
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock http://openam.forgerock.org/doc/dev-guide/index.html#fedlet-signing-encryption
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Add the certificate to the "RoleDescriptor" element as shown below
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <RoleDescriptor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock xsi:type="query:AttributeQueryDescriptorType"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock protocolSupportEnumeration= "urn:oasis:names:tc:SAML:2.0:protocol">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <KeyDescriptor use="signing">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:X509Data>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:X509Certificate>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock --certificate--
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:X509Certificate>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:X509Data>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:KeyInfo>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </KeyDescriptor>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <KeyDescriptor use="encryption">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:X509Data>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:X509Certificate>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock --certificate--
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:X509Certificate>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:X509Data>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:KeyInfo>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <xenc:KeySize xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">128</xenc:KeySize>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </EncryptionMethod>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </KeyDescriptor>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </RoleDescriptor>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) In the "sp-extended.xml", specify the correct value for
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "encryptionCertAlias". If you want Assertion to be encrypted by IDP,
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the NameID from Fedlet needs to be encrypted. Please specify the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock value of "true" to the attribute "wantNameIDEncrypted" in
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock AttributeQueryConfig element as follows:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Attribute name="encryptionCertAlias">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>test</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </Attribute>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Attribute name="wantNameIDEncrypted">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>true</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </Attribute>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock d) Goto Step (1) i.e to Hosted IDP side
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock e) Delete existing fedlet metadata and obtain the standard metadata
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockIII. Testing:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockTwo JSP files are bundled along inside fedlet.war. fedletAttrQuery.jsp and
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Gets the list of attributes from the form whose values needs to be
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock fetched from IDP. Please make sure you define the correct mapping in the IDP.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Retrieves the attribute names from the previous jsp and invokes the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock below method to get the attribute values and display the same.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Map attrMap = AttributeQueryUtil.getAttributeMapForFedlet(
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock spEntityID,
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock idpEntityID,
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock newNameIDValue,
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock attrQueryProfile ,
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock subjectDN);
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockc) Select either the "Default" or "X.509" profile. If "X.509" profile is
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock selected, specify the right value for the "X.509 Subject DN".
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock%% 8. How to perform Fedlet XACML Query
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock I. General Information
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock II. Signing
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock III. Encryption
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock IV. Testing
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockI. General Information
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock======================
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockFollowing steps are common for all the scenarios (including Signing and
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockEncryption). Unlike Fedlet Attribute Query which required query signing
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockto be done on the Fedlet side, no such requirement is there for Fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockXACML Query. Signing and Encryption are optional.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Following steps need to be performed on hosted IDP:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) When creating the IDP entity metadata, make sure that you specify that
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock particular entity with XACML PDP role.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) Specify the Request Handler for SAMLv2 SOAP Binding. Log into
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock the OpenSSO console.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Configuration tab -> Global -> SAMLv2 SOAP Binding -> New
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Key = /pdp (This should be the same metaAlias specified while
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock creating the IDP)
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock class = com.sun.identity.xacml.plugins.XACMLAuthzDecisionQueryHandler
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Click the "Save" button.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) Create the Fedlet.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock d) Specify the right URL policies for the resources for which the Fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock is issuing a XACML query. Right URL policies with right actions
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock (GET or POST) should be specified for the XACML query to get the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock policy decisions for the resoruce.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Access Control -> Realm Name -> Policies -> New Policy
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Following steps need to be performed on Fedlet side:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) Deploy fedlet.war and configure the fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) If Signing or Encryption is enabled, please make sure when you
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock create PDP on IDP, signing cert or encryption cert should have a
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock valid value. Also the updated Fedlet metadata is loaded on IDP
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) If Signing and Encryption are not enabled, skip to Step IV.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Please follow the links below on creating a key store and using the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock certificate.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock http://openam.forgerock.org/doc/admin-guide/index.html#change-signing-key
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock http://openam.forgerock.org/doc/dev-guide/index.html#fedlet-signing-encryption
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Add the certificate to the "XACMLAuthzDecisionQueryDescriptor"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock element as shown below inside "sp.xml".
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <XACMLAuthzDecisionQueryDescriptor WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <KeyDescriptor use="signing">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:X509Data>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <ds:X509Certificate>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock --certificate--
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:X509Certificate>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:X509Data>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </ds:KeyInfo>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </KeyDescriptor>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </XACMLAuthzDecisionQueryDescriptor>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) In the "sp-extended.xml", specify the correct value for
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "signingCertAlias" inside the XACMLAuthzDecisionQueryConfig element as
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Attribute name="signingCertAlias">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>test</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </Attribute>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) If Fedlet wants have the Authorization Decision Response signed, it
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock will specify the following.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock 1) On the Fedlet side, specify the value for
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "wantXACMLAuthzDecisionResponseSigned" inside the
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock XACMLAuthzDecisionQueryConfig as shown below:
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Attribute name="wantXACMLAuthzDecisionResponseSigned">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>true</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </Attribute>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock c) Goto to Hosted IDP side
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock d) If IDP wants the XACML Query signed, it will enable the below
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock property on the XACML PDP tab for the IDP Entity
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock Authorization Decision Query Signed
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock e) Specify the below value for the attribute
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "wantXACMLAuthzDecisionQuerySigned" in "idp-extended.xml" on the Fedlet
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock side for this change to happen.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Attribute name="wantXACMLAuthzDecisionQuerySigned">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>true</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </Attribute>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock f) Delete existing fedlet metadata and obtain the standard metadata
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock g) If Authorization Decision Response Signed is required (Step b), click
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock on the XACML PEP entity that was added. Enable the attribute
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock "Authorization Decision Response Signed".
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrockIII. Encryption
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock===============
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock In addition to above section, the Fedlet might want to get the Assertion
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock from IDP to be encrypted. It will do the following.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock a) Enable the following in "sp-extended.xml" inside
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock XACMLAuthzDecisionQueryConfig element.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Attribute name="wantAssertionEncrypted">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <Value>true</Value>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock </Attribute>
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock b) For signing and encryption, please follow the links
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock below on creating a key store and using the certificate.
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock http://openam.forgerock.org/doc/admin-guide/index.html#change-signing-key
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock http://openam.forgerock.org/doc/dev-guide/index.html#fedlet-signing-encryption
ac88567a7a5bb7f01cf22cf366bc9d6203e24d7aHyon Kim Add the certificate to the "XACMLAuthzDecisionQueryDescriptor"
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock element as shown below inside "sp.xml".
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <XACMLAuthzDecisionQueryDescriptor WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <KeyDescriptor use="signing">
275c9da86e89f8abf71135cf63d9fc23671b2e60eschrock <KeyDescriptor use="signing">
ac88567a7a5bb7f01cf22cf366bc9d6203e24d7aHyon Kim <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
<xenc:KeySize xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">128</xenc:KeySize>
c) In the "sp-extended.xml", specify the correct value for
pdpEntityID, NameID) to fedletXACMLResp.jsp
String policy_decision = XACMLQueryUtil.getPolicyDecisionForFedlet(