<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="idp-installation-configuration" xml:lang="fr">

<info>
<link type="guide" xref="fournisseur-d-identite" group="idp-installation-configuration"/>
  <desc>Installation et configuration du fournisseur d'identité.</desc>
  <revision pkgversion="20120605" version="1.0" date="10-06-2012" status="final"/>
  <credit type="author">
    <name>Thomas Noël</name>
    <email>tnoël@entrouvert.com</email>
  </credit>
  <credit type="maintainer">
    <name>Pierre Cros</name>
    <email>pcros@entrouvert.com</email>
  </credit>
</info>

<title>Installation et configuration</title>

<p>Le fournisseur d'identité (IdP) est intégré au portail captif Univnautes depuis sa version du 16 septembre 2011. Pour en disposer, il suffit d'installer ou de mettre à jour la solution.</p>
<note>
  <p>
    Le fournisseur d'identité (IdP) n'est pas activé par défaut.
  </p>
</note>

<section id="etape1">
  <title>Étape 1 : Ouvrir le port 4443/tcp</title>
  <p>L'IdP intégré propose un service en HTTPS sur le port 4443/tcp du portail captif, sur toutes ses interfaces (LAN et WAN). Pour préparer l'activation de l'IdP intégré, il faut donc ouvrir l'accès à ce port. Sur Univnautes/pfSense, il faut :</p>

<list>
  <item><p>se rendre sur la page <em>Firewall / Rules / LAN</em></p></item>
  <item><p>juste en dessous de la première ligne concernant le port 8443, ajouter une ligne qui ouvre le port 4443/tcp. Potur cela, une technique simple :</p>
   <list>
     <item><p>copier la ligne concernant 8443/tcp (en cliquant sur le petit icone "+" adjacent) :</p>
          <figure>
          <title>Règles du firewall</title>
          <media type="image" mime="image/png" src="figures/open4443.1.png" ></media>
          </figure>
     </item>
     <item><p>modifier le port cible à 4443, et la description, puis cliquer sur Save en bas de page :</p>
          <figure>
          <title>Règles du firewall</title>
          <media type="image" mime="image/png" src="figures/open4443.2.png" ></media>
          </figure>
     </item>
   </list>
</item>
</list>

<note style="tip">
  <p>Comme après toute modification sur les régles du firewall de pfSense, il faudra ensuite cliquer sur le bouton "Apply Changes" en haut de page pour que les changements soient pris en compte.</p>
</note>

<note>
  <p>La modification décrite ci-dessus permet à tous les utilisateurs du réseau local (i.e. les clients derrière le portail captif) d'accéder à l'IdP. Si ce dernier doit pouvoir être accessible depuis d'autres réseaux, il faut ajouter des règles correspondante dans le pare-feu, sur l'interface WAN le cas échéant. Suivre pour cela la <link href="http://doc.pfsense.org/index.php/Firewall_Rule_Basics">documentation de pfSense</link>.</p>
</note>

</section>

<section id="etape2">
  <title>Étape 2 : Création des utilisateurs</title>

<note style="warning">
  <p>L'IdP authentifie les utilisateurs de pfSense possédant le privilège «Univnautes IdP - account» (et uniquement ceux-ci).</p>
</note>

<p>Une bonne pratique est de créer un ou plusieurs groupes avec ce privilège, et de placer les utilisateurs dans ces groupes. Il est ainsi aisé de désactiver l'accès à l'IdP pour tout un groupe, en retirant le privilège au groupe.</p>

<section id="creation-groupe">
  <title>Création d'un groupe « idp »</title>
  <list>
    <item><p>Se rendre dans <em>System / User management</em> sur l'onglet <em>Groups</em>. Cliquer sur le bouton « + » en bas à droite de la liste et ajouter un groupe nommé « idp ». Cliquer sur le bouton <code>save</code>, cela ramène à la liste des groupes.</p></item>
    <item><p>Editer alors le groupe créé en cliquant sur l'icône « e » à droite de sa ligne. Sur la page d'édition, dans la section <em>Assigned Privileges</em>, ajouter le privilège « Univnautes IdP - account ». Cliquer sur <code>save</code> pour revenir à la liste des groupes.</p></item>
  </list>
</section>

<section id="ajout-utilisateur">
  <title>Ajout d'un utilisateur</title>
  <list>
    <item><p>Se rendre dans <em>System / User management</em> sur le premier onglet <em>Users</em>. Cliquer sur le bouton « + » en bas à droite de la liste et ajouter un utilisateur en définissant ses paramètres :</p>
    <list>
      <item><p>son nom de connexion (dans la suite de ce document, ce sera « test »)</p></item>
      <item><p>son mot de passe, à répéter deux fois pour éviter les fautes de frappe</p></item>
      <item><p>son nom complet (en évitant si possibles les caractère « ésotériques »)</p></item>
      <item><p>la date d'expiration du compte, le cas échéant</p></item>
      <item><p>et l'ajouter dans le groupe «idp» précédemment créé</p></item>
    </list>
    </item>
    <item><p>Cliquer sur le bouton <code>save</code>, cela ramène à la liste des utilisateurs.</p></item>
  </list>

  <p>C'est parce qu'il est placé dans le groupe «idp» possèdant le privilège d'accès à l'IdP que l'utilisateur pourra s'y authentifier.</p>

<note>
  <p>
En éditant l'utilisateur (petit icône « e » à droite de sa ligne), on peut voir les privilèges dont il dispose dans la section « Effective Privileges ».
  </p>
</note>

<figure>
  <title>Gestion des utilisateurs</title>
  <media type="image" mime="image/png" src="figures/users.png" >
  </media>
</figure>

</section>

</section>

<section id="etape3">
  <title>Étape 3 : Ajout des clés SAML</title>
  <p>Pour sécuriser le système, il faut déclarer une paire de clés pour l'IdP, une privée et une publique (sous forme d'un certificat x509). Une clé auto-signée suffit parfaitement (avec openssl, voire par exemple <link href="http://www.linux-france.org/prj/edu/archinet/systeme/ch24s03.html">cette documentation</link> pour produire la paire de clés).</p>

<p>Ces clés doivent être déclarées sur la page <em>Services / Captive Portal</em> au niveau de l'onglet Univnautes, dans la section <em>SAML 2.0 Local Identity Provider</em> :</p>

<figure>
  <title>Ajout des clés SAML</title>
  <media type="image" mime="image/png" src="figures/saml.png" >
  </media>
</figure>

</section>

<section id="etape4">
  <title>Étape 4 : Activation du service IdP</title>
  <p>Pour activer l'IdP :</p>
  <list>
    <item><p>se rendre sur la page <em>Services / Captive Portal</em></p></item>
    <item><p>aller sur l'onglet <em>Univnautes</em></p></item>
    <item><p>au niveau de la section <em>SAML 2.0 Local Identity Provider</em> cocher la case <em>Enable local IdP</em> (voire la copie d'écran ci-dessus)</p></item>
    <item><p>cliquer sur le bouton <code>Save</code> en bas de la page</p></item>
  </list>

<p>Après quelques secondes (au maximum 10) le service IdP est visiblement lancé sur la page <em>Status / Services</em>.</p>

<figure>
  <title>Liste des services</title>
  <media type="image" mime="image/png" src="figures/services.png" >
  </media>
</figure>

</section>

<section id="etape5">
  <title>Étape 5 (optionnelle) : ajout d'une entrée DNS spécifique</title>
  <p>Par défaut, l'IdP sera disponible sous le même nom que le portail captif (en général <em>eduspot.univ-paris42.fr</em>), sur le port 4443. Il est cependant possible d'afficher l'IdP sous un autre nom. Pour cela, il suffit que l'entrée DNS correspondante pointe vers l'adresse LAN (ou WAN) de la machine Univnautes.</p>
  <p>Cette entrée DNS peut être gérée sur la DNS de l'établissement, ce qui est préférable si l'IdP est destiné à être utilisé par plusieurs portails Univnautes. Mais l'entrée DNS peut aussi être déclarée uniquement sur le réseau local du ou des portails ; dans ce cas, il faut l'indiquer en bas de la section <em>Services / DNS Forwarder</em> (voir la <link href="http://doc.pfsense.org/index.php/DNS_Forwarder">documentation de pfSense</link>).</p>
<note>
  <p>Il n'est pas possible de placer l'IdP sur le port HTTPS classique 443, celui-ci étant déjà occupé par le portail captif. L'URL de l'IdP sera donc toujours de la forme http://nom.de.machine:4443/.</p>
</note>  

</section>

<section id="etape6">
  <title>Étape 6 : Gestion des métadonnées</title>
  <p>Une fois l'IdP activé, ses métadonnées sont accessibles sur l'URL : https://nom.de.machine:4443/idp/saml2/metadata</p>

<figure>
  <title>Métadata</title>
  <media type="image" mime="image/png" src="figures/metadata.png" >
  </media>
</figure>

<note style="warning">
  <p>L'ajout de l'IdP dans la liste présentée sur le portail captif n'est pas automatique ! Lire ci-dessous la manipulation à effectuer pour cela.</p>
</note>  

<p>Pour que l'IdP soit visible dans la liste des établissements sur le portail captif, il faut l'ajouter au métadonnées locales. Il faut donc :</p>
<list>
  <item><p>afficher les metadonnées de l'IdP en allant sur https://nom.de.machine:4443/idp/saml2/metadata</p>
  <note style="warning">
    <p>Attention, les navigateurs Firefox et assimilés n'affichent pas complètement les données XML ! Pour les afficher totalement avant de faire le copier-coller, demandez au navigateur d'afficher le code source de la page (par exemple en tapant sur Ctrl-U)</p>
  </note>  
  </item>
  <item><p>en copier le contenu (par Ctrl-C) de <em>&lt;ns0:EtntityDescriptor...&gt;</em> jusqu'à la fin (attention avec Firefox : il le faire depuis le code source de la page !).</p></item>
  <item><p>aller sur la page <em>Services / Captive Portal</em>, à l'onglet <em>Univnautes</em></p></item>
  <item><p>coller les metadonnées (Ctrl-V) dans la zone de texte <em>Federation: local metadata (SPs and IdPs)</em>, juste au dessus de la dernière ligne <em>&lt;/EntitiesDescriptor&gt;</em>.</p>
  <figure>
    <title>Copier / Coller les metadata</title>
    <media type="image" mime="image/png" src="figures/metadata-cutpaste.png" >
    </media>
  </figure>
  </item>
  <item><p>cliquer sur <code>Save</code> en bas de page</p></item>
</list>

<p>Quelques secondes plus tard, l'IdP est visible dans la liste sur le portail captif.</p>

  <figure>
    <title>Liste des IdP</title>
    <media type="image" mime="image/png" src="figures/idplist.png" >
    </media>
  </figure>

  <section id="nommer-idp">
    <title>Nommer l'IdP</title>
    <p>Les métadonnées de l'IdP intégré ne contiennent pas de joli nom", et l'IdP se trouve affiché sous forme de son URL dans la liste... C'est moche !</p>
    <p>Pour choisir un nom pour l'IdP, il faut modifier les métadonnées et ajouter une section Organization, par exemple à la fin :</p>
    <code><![CDATA[
    (...)
    </ns0:IDPSSODescriptor>
      <Organization>
        <OrganizationName>UN NOM LISIBLE</OrganizationName>
      </Organization>
    </ns0:EntityDescriptor>
    ]]></code>

    <p>Sur l'interface d'administration, cela donne :</p>

    <figure>
      <title>Nom de l'IdP</title>
      <media type="image" mime="image/png" src="figures/idpname.png" >
      </media>
    </figure>    
  </section>

  <section id="test-local">
    <title>Cas d'un test local (hors fédération)</title>
    <p>L'IdP intégré à Univnautes va chercher la liste des SP dans la fédération.</p>
    <p>Si vous êtes en mode de test local (c'est-à-dire si votre portail captif n'est pas déclaré dans une fédération) alors vous devez également indiquer les métadonnées du portail captif dans les métadonnées locales (toujours par copier-coller).</p>
    
  </section>

</section>

<section id="fin">
  <title>Fin</title>
  <p>Une fois ces opérations effectuées, l'IdP est visible dans la liste et fonctionnel.</p>
  <p>Vous pouvez alors jouer avec la création/modification d'utilisateurs (menu <em>System / User managment</em>) pour définir votre politique d'accès.</p>
</section>

</page>
