a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster------------------------------------------------------------------------------
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterREADME file for the .NET Fedlet
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster------------------------------------------------------------------------------
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterCopyright (c) 2009-2010 Sun Microsystems Inc. All Rights Reserved
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterThe contents of this file are subject to the terms
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterof the Common Development and Distribution License
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster(the License). You may not use this file except in
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fostercompliance with the License.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterYou can obtain a copy of the License at
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterhttps://opensso.dev.java.net/public/CDDLv1.0.html or
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterSee the License for the specific language governing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterpermission and limitations under the License.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterWhen distributing Covered Code, include this CDDL
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterHeader Notice in each file and include the License file
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterIf applicable, add the following below the CDDL Header,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosterwith the fields enclosed by brackets [] replaced by
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Fosteryour own identifying information:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster"Portions Copyrighted [year] [name of copyright owner]"
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark CraigPortions Copyright 2012-2013 ForgeRock AS
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 1. Contents of this directory
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 2. What is currently supported
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 3. How to configure and deploy the Fedlet for .NET
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 4. How to use the Sample Application to test your deployment
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 5. How to integrate with existing application after Single Sign-on
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 6. How to enable support for multiple Identity Providers
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 7. How to enable Identity Provider Discovery Service
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 8. How to enable the Windows Event Log for debugging
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 9. How to enable Signing of Requests/Responses
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster %% 10. Subtle differences between Java and .NET Fedlet
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 1. Contents of this directory
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster This README file provides information on the Fedlet for .NET without a
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster pre-configured Identity Provider (IDP) and Fedlet (SP) metadata. Manual
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster steps are needed to set up the Fedlet for .NET to work with a remote IDP.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster | |- Fedlet.dll The DLL to deploy in the bin/ folder of
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster | your application.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster |- conf Folder containing template metadata files
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster | for use by the Fedlet for .NET applications.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster |- SampleApp The sample application to demonstrate
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster | connectivity between the remote IDP and
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster | the Fedlet (SP).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster |- readme.txt This README file. The file shows how to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster install, configure, and use the Fedlet.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 2. What is currently supported
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster The Fedlet.dll currently supports IDP and SP initiated Single Sign On (SSO)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster with POST and Artifact binding. Multiple IDP and IDP Discovery are also
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster supported with the aforementioned SSO. In addition, IDP and SP initiated
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Single Logout Out is also supported. These features are made available by
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster providing ASP.NET developers an API and an example sample application to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster retrieve an AuthnResponse from their IDP. Details are described in
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Section 5 below.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 3. How to configure and deploy the Fedlet for .NET
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster The Fedlet.dll contains all the necessary bits for the Fedlet provide
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ASP.NET developers an interface to a light-weight SAMLv2 Service Provider
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster API. These developers can use the API to initiate single sign on to an
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Identity Service Provider and receive an HTTP-POST in their application to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster retrieve useful information provided in the AuthnResponse.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Steps to configure and deploy the Fedlet for .NET:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster a) Extract the asp.net/ folder within the Fedlet-unconfigured.zip to a
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster temporary directory.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster b) Within the conf/ folder, edit the template files by changing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the following tags:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster FEDLET_COT : Replace with the name of your circle of trust.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster FEDLET_ENTITY_ID : Replace with the name of the entity id for your Fedlet.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster FEDLET_DEPLOY_URI : Replace with the url of the Fedlet.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster IDP_ENTITY_ID : Replace with the name of the entity id of the remote
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Identity Provider.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster c) Copy the edited files above to your application's App_Data/ folder.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster d) Obtain the standard metadata XML file from your IDP, name it idp.xml,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster and place in your application's App_Data/ folder. If your IDP is
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig an OpenAM deployment, this can be exported by accessing the export
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster URL. For example:
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig http://idp.example.com:8080/openam/saml2/jsp/exportmetadata.jsp
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster e) Provide the Fedlet metadata XML file "sp.xml" to your IDP. The
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster metadata must be imported to the IDP machine and must be associated
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig with the same Circle of Trust as the IDP. If your IDP is an OpenAM
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster deployment, use the Register Remote Service Provider workflow
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster available from the Common Tasks page to import your Fedlet's
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster f) Configuration is now complete.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster g) Copy the Fedlet.dll from the bin/ folder to your application's bin/
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster By having the Fedlet artifacts deployed specifically in the App_Data/ and
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster bin/ folder of your hosted application, multiple instances of the Fedlet with
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster its own configuration can be co-deployed in the same Internet Information
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Server (IIS).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster NOTE REGARDING MODIFICATIONS TO SAMLv2 METADATA:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Be sure to convey information regarding any changes made in the service
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster provider metadata to the identity provider so it can make the corresponding
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster changes to its own configuration. A modified sp.xml file may be sent to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the identity provider but any modifications made to sp-extended.xml should
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster be conveyed to the identity provider using a different method. Once the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster identity provider receives the appropriate standard and extended metadata
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig values, it can make the changes using the OpenAM console. Information on
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig customizing SAMLv2 providers using the OpenAM console is available in the
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig OpenAM documentation.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * SAMLv2 Service Provider Customization link:
cee9725efd021d635ce2d0e1712ce1b015ac6887Mark Craig http://openam.forgerock.org/doc/admin-guide/index.html#configure-sp
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster * SAMLv2 Identity Provider Customization link:
cee9725efd021d635ce2d0e1712ce1b015ac6887Mark Craig http://openam.forgerock.org/doc/admin-guide/index.html#configure-idp
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig If the identity provider is using a product other than OpenAM,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster they would make the changes according to their product's documentation.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 4. How to use the Sample Application to test your deployment
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster The Sample Application could be used to test your deployment of the Fedlet
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster for your .NET applications.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Steps to deploy the Sample Application:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster a) Install the Sample Application on your Service Provider
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster i) Navigate to the asp.net/ folder extracted from the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Fedlet-unconfigured.zip as described in Section 3 above.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ii) Copy over the metadata files edited in Section 3 above and place
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster into the SampleApp/App_Data folder.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster - The following files should have been copied over:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster idp.xml, idp-extended.xml, sp.xml, sp-extended.xml, fedlet.cot
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster - The files in the existing sample application were configured
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster for idp.example.com and sp.example.com and are expected to be
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster replaced for your installation.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster iii) Within Internet Information Server, create a virtual directory
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster with the SampleApp/ folder found within the unzipped folder.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster - IIS 6 has Add Virtual Directory. Be sure to have Read and
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Script permissions set for the application.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster - IIS 7 has Add Application with no additional options required
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster to be altered.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster b) Try out the Sample Application.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster i) Open the SampleApp in your browser. For example:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ii) Click the link to perform the IDP initiated SSO.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster iii) Enter in your credentials (such as demo / changeit ).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster iv) After the form submission, you should be at the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster fedletapplication.aspx page with access to the AuthnResponse
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster information.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 5. How to integrate with existing application after Single Sign-on
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster The Sample Application described above demonstrates possible usage by
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ASP.NET developers. Once the application has the necessary artifacts
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster installed, a specific URI is required to receive the HTTP-POST containing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the SAMLv2 response after successful authentication by the IDP. The
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster following example shows how the developer would retrieve this information:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster AuthnResponse authnResponse = null;
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ServiceProviderUtility spu = new ServiceProviderUtility(Context);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster authnResponse = spu.GetAuthnResponse(Context);
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster catch (Saml2Exception se)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster // invalid AuthnResponse received
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster catch (ServiceProviderUtilityException spue)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster // issues with deployment (reading metadata)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster If a SAML response was received the authnResponse object will be populated
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster with the assertion information. The sample application demonstrates how to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster retreive attributes and sujbect information from this object.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 6. How to enable support for multiple Identity Providers
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster To configure a second Identity Provider with this Fedlet:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster a) Get the standard metadata XML file for the new Identity Provider, name
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the XML file as "idp2.xml" and copy it to the App_Data/ folder.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster b) Decide on the circle-of-trust (COT) the new Identity Provider would
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster belong. This IDP could be added to an existing COT (e.g. "fedlet.cot")
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster or a new COT.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster i) To add the Identity Provider to an existing COT, edit the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster corresponding COT file (e.g. "fedlet.cot") within the App_Data/
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster folder, and append the new IDP entity ID (specified by the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster "entityID" attribute in the "idp2.xml" metadata file) to the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster value of "sun-fm-trusted-providers" attribute using "," as the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ii) To add to a new circle-of-trust:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster - Create a new file named "fedlet2.cot" and place within the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster App_Data/ folder. Use the existing fedlet.cot as a template,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster but change the value of attribute "cot-name" to the actual name
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster of the new COT (e.g. "cot2"), and include both the new IDP
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster entity ID and the Fedlet entity ID as value for
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster "sun-fm-trusted-providers" attribute (two entity IDs separated
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster - Edit the sp-extended.xml file, add the new COT name to the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster value of "cotlist" attribute. For example:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <Attribute name="cotlist">
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <Value>saml2cot</Value>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <Value>cot2</Value>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster </Attribute>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster c) Create a new "idp2-extended.xml" file as the extended metadata for the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster new Identity Provider. Use the existing idp-extended.xml as a template
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster but change the "entityID" to the new IDP entity ID, change the value
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster for "cotlist" attribute to the COT name if a new COT is created for
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Note: Make sure the second IDP is a remote IDP by setting the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster "hosted" attribute in the EntityConfig element to "false".
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster d) Send the .NET Fedlet metadata XML file (i.e. "sp.xml" within the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster App_Data/ folder) to the second IDP, import the metadata in the remote
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster IDP and add it to the same circle-of-trust as the IDP.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Repeat the same steps for the third, fourth, ... and [X]th IDP, using
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster idpX.xml/idpX-extended.xml/fedletX.cot as standard meta/extended meta/COT
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster name for the new IDP. Restart the Application Pool associated with your
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster .NET application to make the change effective.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster If you have performed the above with the Sample Application, returning to the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster default page will now provide you with a list of IDPs to perform single sign
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 7. How to enable Identity Provider Discovery Service
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster When the .NET Fedlet is configured with multiple Identity Providers in a
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster COT, it could additionally be configured to use an IDP Discovery Service to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster determine the preferred IDP.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster In order to leverage this functionality, you first need to have the Identity
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Provider Discovery Service set up and deployed before performing the steps
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig listed below. If you installed the OpenAM WAR, the IDP Discovery Service is
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster already bundled with the product. Alternately, you could follow the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster documented process in creating a separate WAR for just the IDP Discovery
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig Service. Please refer to the OpenAM documentation on how to set up and use
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the IDP Discovery Service. After configuring this service, take note of the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster reader service URL (URL to find out the preferred IDP) and the writer service
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster URL (URL to write the preferred IDP), they are needed in the steps below. If
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig you are using OpenAM, the reader service URL is typically:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <protocol>://<host>:<port>/deploy_uri/saml2reader
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig (for example: http://discovery.common.com/openam/saml2reader)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Likewise, the writer service URL is typically:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <protocol>://<host>:<port>/deploy_uri/saml2writer
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig (for example: http://discovery.common.com/openam/saml2writer)
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster To configure the .NET Fedlet to support IDP discovery:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster a) Edit the COT file (e.g. "fedlet.cot"), and set the value for attribute
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster "sun-fm-saml2-readerservice-url" to the SAML2 reader service URL
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig (e.g. http://discovery.common.com/openam/saml2reader), set the value
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster for attribute "sun-fm-saml2-writerservice-url" to the SAML2 writer
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig service URL (e.g. http://discovery.common.com/openam/saml2writer).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster b) Restart the Application Pool associated with your .NET application to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster make the change effective.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster c) Setup IDP discovery on each of your remote IDPs. If the IDP is an
c982ed7c45fa4e64e4743faaa318fcc7e5f707f0Mark Craig OpenAM server instance, you need go to the administration console,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster find the COT for the IDP and .NET Fedlet, and specify the SAML2 reader
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster service URL and SAML2 writer service URL, and Save.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster d) If you have performed the above with the Sample Application and have
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster configured it with multiple Identity Providers, returning to the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster default page will now provide you a link to "use the IDP Discovery
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster i) If no IDP has been established as the preferred IDP,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster clicking on this link will arbitrarily redirect you to one of the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster configured IDPs for authentication. Once authenticated, this IDP
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster will be designated as the preferred IDP by the discovery service.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ii) If an IDP has already been established as the preferred IDP,
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster clicking on this link will again redirect you to this IDP for
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster authentication.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 8. How to enable the Windows Event Log for debugging
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Since the .NET Fedlet does not require an installer, minimal manual steps are
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster required to enable log messages to be written to the Windows Event Log. The
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster steps below require edits to the Windows Registry so please take necesary
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster precautions as described in the Microsoft Knowledge Base article referenced
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster To configure the .NET Fedlet to write to the Windows Event Log:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster a) The instructions for enabling a .NET application to write events to the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Windows Event Log are described at the following Microsoft Help and
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Support article:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster http://support.microsoft.com/default.aspx?scid=kb;en-us;329291
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Following these instructions, add a new key under
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster with "Fedlet" as the key.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster b) Edit the <appSettings/> element within your .NET application's
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Web.config file to specify the .NET Fedlet log level. The key to add
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster is called "fedletLogLevel" and the possible values are "info",
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster "warning", and "error". An example for enabling "info" level logging
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster is shown below:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <appSettings>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <add key="fedletLogLevel" value="info"/>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster </appSettings>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster c) Restart the Application Pool associated with your .NET application to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster make the change effective.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Current implementation will log AuthnRequests and AuthnResponses with the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster "info" log level for successful SAML exchanges and AuthnResponses that are
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster not successful with "warning" log level. Log messages for "error"
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster are not currently used since errors are thrown as exceptions (except for
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the Saml2Exception captured with the "warning" log level noted above).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 9. How to enable Signing of Requests/Responses
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Since the .NET Fedlet does not require an installer, additional manual steps
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster are required to enable signing of outgoing requests and responses to the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster identity provider.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster To configure the .NET Fedlet to sign outgoing requests and responses:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster a) Import your X509 certificate to the Personal folder within the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Local Computer account using the Certificates Snap-in for the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Microsoft Management Console. See the following information on basic
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster usage of this snap-in:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster http://msdn.microsoft.com/en-us/library/ms788967.aspx
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster b) Specify a friendly name for this certificate by viewing the Properties
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster dialog and entering a value. Note this value for step d) below.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster c) Set the appropriate permissions to allow read access to the certificate
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster for the user account used by Internet Information Server (IIS) as
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster described at the aformentioned article. For example, using the menu in
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the aforementioned snap-in above, navigate to:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Action > All Tasks > Manage Private Keys
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster From here, specify Allow Read permissions for the user acccount running
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster IIS (commonly NETWORK SERVICE).
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster d) Update the .NET Fedlet's extended metadata (sp-extended.xml) to specify
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the friendly name specified in step b) as the value for the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster signingCertAlias attribute. For example:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <Attribute name="signingCertAlias">
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <Value>MyFedlet</Value>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster </Attribute>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster e) Update the .NET Fedlet's metadata (sp.xml) to include the key
cee9725efd021d635ce2d0e1712ce1b015ac6887Mark Craig descriptor for the signing key. Please follow the links
cee9725efd021d635ce2d0e1712ce1b015ac6887Mark Craig below on creating a key store and using the certificate.
07e7dcd4d7f52b182ecc8bc086fb9b8369bf1d93Mark Craig http://openam.forgerock.org/doc/admin-guide/index.html#change-signing-key
cee9725efd021d635ce2d0e1712ce1b015ac6887Mark Craig http://openam.forgerock.org/doc/dev-guide/index.html#fedlet-signing-encryption
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster For the Windows environment, use the Certificates Snap-in for the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Microsoft Management Console used earlier to now export the public key
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster of your certificate in Base64 encoding to be included in the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster KeyDescriptor XML block. The sp.xml should have a KeyDescriptor as the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster first child element within the SPSSODescriptor and look similar to the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <KeyDescriptor use="signing">
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <ds:X509Data>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster <ds:X509Certificate>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterMIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterbGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterBgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterAQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of\+
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterRkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterJs0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FosterQzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan FostercGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster/FfwWigmrW0Y0Q==
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster </ds:X509Certificate>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster </ds:X509Data>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster </ds:KeyInfo>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster </KeyDescriptor>
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster f) Restart the Application Pool associated with your .NET application to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster make the change effective.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster To test the configuration, use the provided sample application and perform
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the steps as described above. Afterwards, access "exportmetadata.aspx" to
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster generate the .NET Fedlet's metadata and optionally have it signed by passing
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster the "sign=true" query string parameter. For example:
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster http://sp.example.com/SampleApp/exportmetadata.aspx?sign=true
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster The .NET Fedlet is now able to sign requests and responses to the identity
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster provider with the appropriate changes to the configured metadata.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster AuthnRequest
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Set AuthnRequestsSigned attribute within the sp.xml metadata file or the
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster WantAuthnRequestsSigned within the idp.xml metadata file to true.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster ArtifactResolve
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Set wantArtifactResolveSigned attribute within the idp-extended.xml
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster metadata file to true.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster LogoutRequests
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Set wantLogoutRequestSigned attribute within the idp-extended.xml
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster metadata file to true.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster LogoutResponse
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Set wantLogoutResponseSigned attribute within the idp-extended.xml
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster metadata file to true.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster%% 10. Subtle differences between Java and .NET Fedlet
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Beyond the obvious differences of language and deployment, there are subtle
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster differences between the Java Fedlet and the .NET Fedlet. Those differences
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster are described below.
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster SP Extended Metadata - relayStateUrlList attribute
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster In the .NET Fedlet, the values for this optional attribute are expected
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster to be written as regular expressions. More information about .NET
a688bcbb4bcff5398fdd29b86f83450257dc0df4Allan Foster Framework Regular Expressions is available at: