<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! CCPL HEADER START
  !
  ! This work is licensed under the Creative Commons
  ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
  ! To view a copy of this license, visit
  ! http://creativecommons.org/licenses/by-nc-nd/3.0/
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! src/main/resources/legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
  ! If applicable, add the following below this CCPL HEADER, with the fields
  ! enclosed by brackets "[]" replaced with your own identifying information:
  !      Portions Copyright [yyyy] [name of copyright owner]
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2012 ForgeRock AS
  !    
-->
<chapter xml:id='chap-fedlet-dotnet'
 xmlns='http://docbook.org/ns/docbook'
 version='5.0' xml:lang='en'
 xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'
 xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Using Fedlets in .NET Applications</title>
 <indexterm>
  <primary>Fedlets</primary>
  <secondary>.NET</secondary>
 </indexterm>
 <para>This chapter explains how to use the Fedlet in your .NET application.
 You must configure the OpenAM .NET Fedlet to work with the identity provider.
 Before creating the Fedlet, therefore, set up a Hosted Identity Provider in
 OpenAM.</para>

 <procedure xml:id="install-dotnet-fedlet">
  <title>To Install the .NET Fedlet as a Demo Application</title>

  <para>Before you start, create the hosted identity provider, and the Circle
  of Trust to which you plan to add the Fedlet. You can perform these steps
  using the Create Hosted Identity Provider wizard on the Common Tasks page of
  the OpenAM console. The .NET Fedlet demo requires a signing key for the
  Identity Provider. For evaluation, use the <literal>test</literal>
  certificate installed with OpenAM.</para>

  <para>Follow these steps to configure and install the .NET Fedlet demo
  application.</para>

  <step>
   <para>Unzip the <filename>Fedlet-unconfigured.zip</filename> file, and
   copy the contents of the <filename>Fedlet-unconfigured\asp.net\</filename>
   folder to a working directory.</para>
   <variablelist>
    <varlistentry>
     <term><filename>bin\</filename></term>
     <listitem>
      <para>This folder contains the <filename>Fedlet.dll</filename> library,
      that you copy to your application's <filename>bin\</filename>
      folder.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>conf\</filename></term>
     <listitem>
      <para>This folder contains the templates you edit to prepare your Fedlet
      configuration, including the identity provider and Fedlet (SP) metadata
      for federation. The completed configuration files belong in your
      application's <filename>App_Data\</filename> folder.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>readme.txt</filename></term>
     <listitem>
      <para>This file describes how to set up and configure .NET Fedlets.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><filename>SampleApp\</filename></term>
     <listitem>
      <para>This folder contains the demo application.</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </step>
  <step>
   <para>Edit the template files in the <filename>SampleApp\App_Data\</filename>
   folder based on where you deploy the Fedlet demo application, and on how your
   identity provider is configured.</para>
   <itemizedlist>
    <listitem>
     <para>Edit <filename>fedlet.cot</filename> to set
     <literal>cot-name</literal> to the name of the Circle of Trust, and to set
     <literal>sun-fm-trusted-providers</literal> to include the entity ID of
     the identity provider, and the entity ID of the Fedlet service
     provider.</para>
    </listitem>
    <listitem>
     <para>Edit <filename>sp.xml</filename> and
     <filename>sp-extended.xml</filename> to configure the entity IDs, URLs,
     and Circle of Trust names to correspond to your sample application.</para>
    </listitem>
   </itemizedlist>
  </step>
  <step>
   <para>Export the identity provider metadata from OpenAM, and copy the
   resulting <filename>idp.xml</filename> and
   <filename>idp-extended.xml</filename> metadata to the Fedlet
   <filename>SampleApp\App_Data\</filename> folder.</para>
   <screen>$ ssoadm
 create-metadata-templ
 --entityid "http://idp.example.com:8080/openam"
 --adminid amadmin
 --password-file /tmp/pwd.txt
 --identityprovider /idp
 --meta-data-file idp.xml
 --extended-data-file idp-extended.xml
 --idpscertalias test

Hosted entity configuration was written to idp-extended.xml.
Hosted entity descriptor was written to idp.xml.</screen>
  </step>
  <step>
   <para>Register the Fedlet with OpenAM as a remote service provider using the
   <filename>sp.xml</filename> and <filename>sp-extended.xml</filename>
   metadata.</para>
   <screen>$ ssoadm
 import-entity
 --adminid amadmin
 --password-file /tmp/pwd.txt
 --cot fedlet-cot
 --meta-data-file sp.xml
 --extended-data-file sp-extended.xml

Import file, sp.xml.
Import file, sp-extended.xml.</screen>
  </step>
  <step>
   <para>Deploy the demo application in Internet Information Server.</para>
   <note>
    <para>IIS must be installed with ASP.NET and additional application
    support necessary for web applications beyond static web sites. The
    additional support is not necessarily installed by default when you
    activate IIS as a Windows feature.</para>
   </note>
  </step>
  <step>
   <para>Try the demo application links to run Fedlet initiated single sign
   on using HTTP POST binding and HTTP Artifact binding.</para>
   <para>If you are using the embedded directory as a user store, you can
   authenticate to OpenAM using the <literal>demo</literal> user whose password
   is <literal>changeit</literal>.</para>
  </step>
 </procedure>
</chapter>

