8N/A------------------------------------------------------------------------------
8N/AREADME file for Open Federation Library
8N/A------------------------------------------------------------------------------
8N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
8N/ACopyright (c) 2008 Sun Microsystems Inc. All Rights Reserved
8N/AThe contents of this file are subject to the terms
8N/Aof the Common Development and Distribution License
8N/A(the License). You may not use this file except in
8N/Acompliance with the License.
8N/AYou can obtain a copy of the License at
8N/ASee the License for the specific language governing
8N/Apermission and limitations under the License.
8N/AWhen distributing Covered Code, include this CDDL
8N/AHeader Notice in each file and include the License file
8N/AIf applicable, add the following below the CDDL Header,
8N/Awith the fields enclosed by brackets [] replaced by
8N/Ayour own identifying information:
8N/A"Portions Copyrighted [year] [name of copyright owner]"
65N/APortions Copyright 2012-2016 ForgeRock AS.
24N/A %% 1. Contents of this directory
65N/A %% 3. How to embed Fedlet into existing application
58N/A %% 4. How to integrate with existing application after Single Sign-on
516N/A %% 5. How to enable Fedlet to support multiple Identity Providers
416N/A %% 6. How to enable Identity Provider Discovery service in Fedlet
95N/A %% 7. How to perform Fedlet Attribute Query
95N/A %% 8. How to perform Fedlet XACML Query
516N/A%% 1. Contents of this directory
1195N/A This README file provides information on the Fedlet ZIP file with pre-configured
8N/A IDP and Fedlet (SP) metadata.
8N/A |- conf Directory containing Fedlet and IDP metadata files,
290N/A | COT and configuration files generated by OpenAM.
635N/A |- README This README file. The file shows how to use Fedlet.
1182N/A In conjunction with the
fedlet.war from the unconfigured Fedlet distribution,
1182N/A the configuration contained in the zip has all the necessary bits for the Fedlet
1182N/A to act as a light-weight SAMLv2 Service provider. It also provides convenient ways
1182N/A to setup and validate a Fedlet deployment.
1182N/A Before accessing the deployed
fedlet.war in your web container, follow the steps in sub-section 3b
1183N/A and you will be shown links to start Fedlet(SP) and IDP initiated Single Sign-on.
1183N/A Click one of the sign-on links and you will be redirected to IDP for login, then Single
1183N/A Sign-on to Fedlet(SP). Upon successful completion, a Fedlet(SP) side JSP
635N/A will be presented to show the whole SAML2 Response XML along with the Assertion XML and
574N/A%% 3. How to embed Fedlet into your existing application WAR
664N/A b) Copy files inside "conf" directory to a sub directory named "fedlet"
749N/A under your web container running user's home directory (pointed by
1190N/A The "fedlet" subdirectory under the web container running user's home
574N/A is the default location for Fedlet to read its metadata, COT and
792N/A configuration properties. To change this default directory, set the
574N/A desired location. For example:
792N/A c) Copy all other files to your application WAR staging directory, overlay
1016N/A them with your existing application WAR structure.
58N/A d) Create the application WAR and redeploy in your web container.
50N/A%% 4. How to integrate with existing application after Single Sign-on
1182N/A to complete SAMLv2 protocol processing. A map containing various data,
822N/A how to retrieve data from the returned map.
792N/A 1. Modify
web.xml to set servlet and servlet-mapping for your new servlet
792N/A "/fedletapplication" since it is the URI set in the Fedlet metadata
792N/A (the assertion consumer URL). For example:
792N/A <servlet-name>yourapplication</servlet-name>
792N/A <servlet-name>yourapplication</servlet-name>
574N/A <url-pattern>/fedletapplication</url-pattern>
1190N/A application processing code with proper import statement:
1190N/A // invoke the Fedlet processing logic. this will do all the
815N/A // necessary processing conforming to SAMLv2 specifications,
1183N/A // such as XML signature validation, Audience and Recipient
65N/A} catch (SAML2Exception sme) {
71N/A} catch (IOException ioe) {
575N/A} catch (SessionException se) {
575N/A} catch (ServletException se) {
1182N/A After obtaining the returned "map" object, you could follow the sample
1182N/A code to retrieve data needed for your business logics.
262N/A%% 5. How to enable Fedlet to support multiple Identity Providers
262N/A To configure second Identity Provider with this Fedlet:
355N/A a) Get the standard metadata XML file for the new Identity Provider, name
262N/A the XML file as "
idp2.xml" and copy it to the Fedlet home directory.
1190N/A b) Decide on the circle-of-trust (COT) the new Identity Provider would
262N/A belong. This IDP could be added to an existing COT (
e.g. "saml2cot") or
262N/A ** To add the Identity Provider to an existing COT, edit the
65N/A directory, and append the new IDP entity ID (pointed by the
1182N/A value of "sun-fm-trusted-providers" attribute using "," as separator.
58N/A ** To add to a new circle-of-trust:
71N/A change the value of attribute "cot-name" to the actual name of
1195N/A the new COT (
e.g. "cot2"), and include both the new IDP entity ID
71N/A and the Fedlet entity ID as value for "sun-fm-trusted-providers"
71N/A attribute (two entity IDs separated by ",").
75N/A <Attribute name="cotlist">
71N/A <Value>saml2cot</Value>
71N/A <Value>cot2</Value>
1190N/A but change the "entityID" to the new IDP entity ID, change the value for
8N/A "cotlist" attribute to the COT name if a new COT is created for the IDP.
8N/A Note : make sure the second IDP is a remote IDP by setting the "hosted"
212N/A attribute in the EntityConfig element to "false".
95N/A d) Send the Fedlet metadata XML file (
i.e. "
sp.xml" under your Fedlet home)
1238N/A to the second IDP, import the metadata in the remote IDP and add it to
95N/A the same circle-of-trust as the IDP.
95N/A Repeat the same steps for the third, fourth, ... and [x]th IDP, use
95N/A name for the new IDP. Restart your Fedlet web container to make the change
95N/A Now accessing the
index.jsp again, it will prompt you with a list of IDPs
95N/A the Fedlet trusted. You could choose any of the IDP and perform Single
815N/A%% 6. How to enable Identity Provider Discovery service in Fedlet
459N/A When Fedlet is setup with multiple Identity Providers in a COT, it could be
95N/A configured to use IDP Discovery service to find out the preferred IDP.
1182N/A You need to have the Identity Provider Discovery service set up before
95N/A performing following steps. If you installed the OpenAM WAR, the
95N/A IDP discovery service is bundled in the products already. Or you could
95N/A follow the document to create a separate WAR for the IDP discovery
95N/A service using the OpenAM WAR. Please refer to the OpenAM
95N/A document set on how to setup and use the Identity Provider
95N/A Discovery service. After set up the IDP discovery service, have the
579N/A reader service URL (URL to find out preferred IDP) and writer service
579N/A URL (URL to write the preferred IDP) ready, they are needed in step
579N/A a) and c) below. If you are using OpenAM server instance
575N/A or the IDP discovery only WAR instance, the reader service URL is:
575N/A <protocol>://<host>:<port>/<deploy_uri>/saml2reader
95N/A the writer service URL is :
95N/A <protocol>://<host>:<port>/<deploy_uri>/saml2writer
355N/A To setup IDP discovery in the Fedlet:
95N/A "sun-fm-saml2-readerservice-url" to the SAML2 reader service URL
355N/A for attribute "sun-fm-saml2-writerservice-url" to the SAML2 writer
347N/A b) Restart your Fedlet web container to make the change to be effective.
347N/A c) Setup IDP discovery on each of your IDPs. If your IDP is an OpenAM
1182N/A server instance, need to goto console, find the COT for
347N/A the IDP and Fedlet, and specify the SAML2 reader service URL and
347N/A SAML2 writer service URL.
347N/A selection page. Don't click the "use IDP discovery service ..."
347N/A link yet, as your preferred IDP has not been set yet. Choose one
1190N/A of the IDPs, and complete the Single Sign-on process. The preferred IDP
1190N/A is set right now by the IDP discovery service.
1190N/A "use IDP discovery service to find out preferred IDP" link.
1190N/A You will be redirected to the IDP discovery service to find out
1183N/A the preferred IDP and send back to Fedlet side with the chosen
99N/A IDP to start the Fedlet initiated single sign-on.
95N/A%% 7. How to perform Fedlet Attribute Query:
355N/A II. Signing and Encryption
95N/A Following steps need to be performed on hosted IDP:
95N/A a) When creating the IDP entity metadata, make sure that you specify that
95N/A particular entity with Attribute Authority role. Also the reponse from
815N/A Attribute Authority needs to be signed. Enable signing for Attribute
176N/A b) Specify the list of attributes to be fetched in the Attribute Map
176N/A IDP Entity -> Assertion Processing -> Attribute Map
459N/A UserStatus=inetUserStatus
1182N/A Following steps need to be performed on Fedlet side:
516N/A b) The Attribute Query needs to be signed. Please follow the links
516N/A below on creating a key store and using the certificate.
516N/A Add the certificate to the "RoleDescriptor" element as shown below
516N/A xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
516N/A xsi:type="query:AttributeQueryDescriptorType"
516N/A protocolSupportEnumeration= "urn:oasis:names:tc:SAML:2.0:protocol">
203N/A <KeyDescriptor use="signing">
1190N/A "signingCertAlias" inside the AttributeQueryConfig element as follows:
314N/A <Attribute name="signingCertAlias">
314N/A d) Goto Step (1)
i.e to Hosted IDP side
1183N/A e) Delete existing fedlet metadata and obtain the standard metadata
314N/AII. Signing and Encryption
314N/A==========================
1183N/A Following steps need to be performed on hosted IDP:
314N/A a) When creating the IDP entity metadata, make sure that you specify that
435N/A particular entity with Attribute Authority role. Also the response from
435N/A Attribute Authority needs to be signed. Enable signing for Attribute
592N/A Authority role. Enable encryption for the IDP Attribute Authority
1182N/A b) Specify the list of attributes to be fetched in the Attribute Map
1182N/A IDP Entity -> Assertion Processing -> Attribute Map
435N/A UserStatus=inetUserStatus
765N/A c) Specify the Attribute Authority Mapper.
765N/A IDP Entity -> Attribute Authority -> Subject Data Store
765N/A Specify the Attribute name which contains X.509 Subject DN.
765N/A Following steps need to be performed on hosted SP:
792N/A b) For signing and encryption, please follow the links
792N/A below on creating a key store and using the certificate.
8N/A Add the certificate to the "RoleDescriptor" element as shown below
xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
xsi:type="query:AttributeQueryDescriptorType"
protocolSupportEnumeration= "urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing">
<KeyDescriptor use="encryption">
"encryptionCertAlias". If you want Assertion to be encrypted by IDP,
the NameID from Fedlet needs to be encrypted. Please specify the
value of "true" to the attribute "wantNameIDEncrypted" in
AttributeQueryConfig element as follows:
<Attribute name="encryptionCertAlias">
<Attribute name="wantNameIDEncrypted">
d) Goto Step (1)
i.e to Hosted IDP side
e) Delete existing fedlet metadata and obtain the standard metadata
Gets the list of attributes from the form whose values needs to be
fetched from IDP. Please make sure you define the correct mapping in the IDP.
Retrieves the attribute names from the previous jsp and invokes the
below method to get the attribute values and display the same.
c) Select either the "Default" or "X.509" profile. If "X.509" profile is
selected, specify the right value for the "X.509 Subject DN".
%% 8. How to perform Fedlet XACML Query
Following steps are common for all the scenarios (including Signing and
Encryption). Unlike Fedlet Attribute Query which required query signing
to be done on the Fedlet side, no such requirement is there for Fedlet
XACML Query. Signing and Encryption are optional.
Following steps need to be performed on hosted IDP:
a) When creating the IDP entity metadata, make sure that you specify that
particular entity with XACML PDP role.
b) Specify the Request Handler for SAMLv2 SOAP Binding. Log into
Configuration tab -> Global -> SAMLv2 SOAP Binding -> New
Key = /pdp (This should be the same metaAlias specified while
d) Specify the right URL policies for the resources for which the Fedlet
is issuing a XACML query. Right URL policies with right actions
(GET or POST) should be specified for the XACML query to get the
policy decisions for the resoruce.
Access Control -> Realm Name -> Policies -> New Policy
Following steps need to be performed on Fedlet side:
b) If Signing or Encryption is enabled, please make sure when you
create PDP on IDP, signing cert or encryption cert should have a
valid value. Also the updated Fedlet metadata is loaded on IDP
c) If Signing and Encryption are not enabled, skip to Step IV.
Please follow the links below on creating a key store and using the
Add the certificate to the "XACMLAuthzDecisionQueryDescriptor"
element as shown below inside "
sp.xml".
<XACMLAuthzDecisionQueryDescriptor WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing">
</XACMLAuthzDecisionQueryDescriptor>
"signingCertAlias" inside the XACMLAuthzDecisionQueryConfig element as
<Attribute name="signingCertAlias">
b) If Fedlet wants have the Authorization Decision Response signed, it
will specify the following.
1) On the Fedlet side, specify the value for
"wantXACMLAuthzDecisionResponseSigned" inside the
XACMLAuthzDecisionQueryConfig as shown below:
<Attribute name="wantXACMLAuthzDecisionResponseSigned">
c) Goto to Hosted IDP side
d) If IDP wants the XACML Query signed, it will enable the below
property on the XACML PDP tab for the IDP Entity
Authorization Decision Query Signed
e) Specify the below value for the attribute
side for this change to happen.
<Attribute name="wantXACMLAuthzDecisionQuerySigned">
f) Delete existing fedlet metadata and obtain the standard metadata
g) If Authorization Decision Response Signed is required (Step b), click
on the XACML PEP entity that was added. Enable the attribute
"Authorization Decision Response Signed".
In addition to above section, the Fedlet might want to get the Assertion
from IDP to be encrypted. It will do the following.
XACMLAuthzDecisionQueryConfig element.
<Attribute name="wantAssertionEncrypted">
b) For signing and encryption, please follow the links
below on creating a key store and using the certificate.
Add the certificate to the "XACMLAuthzDecisionQueryDescriptor"
element as shown below inside "
sp.xml".
<XACMLAuthzDecisionQueryDescriptor WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing">
<KeyDescriptor use="signing">
<KeyDescriptor use="encryption">
</XACMLAuthzDecisionQueryDescriptor>
<Attribute name="encryptionCertAlias">
d) Goto to Hosted IDP side
e) Delete existing fedlet metadata and obtain the standard metadata
f) Click on the XACML PEP entity that was added. Enable the attribute
Prompts the user to enter the Resource URL, Action (GET or POST). Fedlet
then passes this information along with other parameters (pepEntityID,
Retrieves the Resource URL from the previous jsp and invokes the
below method to get the policy decision for the Resource URL and display the
same. The decision can be either "Permit" (if the right policy decision is
provided", else "Deny" (if no policy is found) or "Indeterminate"
(if the user session has expired).