<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="config-passage-production" xml:lang="fr">

<info>
<link type="guide" xref="configuration" group="config-passage-production"/>
<link type="seealso" xref="configuration-avancee"/>
  <desc>Nom du serveur, certificats HTTPS et SAML.</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>Passage en production</title>

<note style="warning">
  <p>
Rappel: l'image ISO d'installation du portail est livré avec des paramètres et certificats de test. Elle fonctionne dans la fédération de test du CRU/Renater car elle y a été déclarée. <em>Pour passer en production il faut modifier ces paramètres et certificats puis déclarer le service dans la fédération choisie.</em>	
  </p>
</note>

<p>Par défaut, le portail est livré avec des paramètres de tests. Son nom est univnautes.entrouvert.lan, le serveur HTTPS associé possède un certificat auto-signé (donc invalide par défaut sur les navigateurs), le certificat SAML est un certificat associé au nom univnautes.entrouvert.lan dans la fédération de test de Renater.</p>

<p>En production, il faut donc modifier tout cela, idéalement dans cet ordre :</p>

<steps>
  <item><p>donner un nom dans le domaine DNS de l'établissement (par exemple eduspot.univ-paris42.fr)</p></item>
  <item><p>placer un certificat valide sur le serveur HTTPS correspondant, obtenu auprès du CRU/Renater via le RSSI, valide pour le nom choisi précédemment</p></item>
  <item><p>créer un nouveau certificat SAML</p></item>
  <item><p>déclarer les métadonnées SAML finale (associant le nom choisi et le certificat SAML) auprès de la fédération CRU/Renater</p></item>
</steps>

<p>Vous trouverez ci-dessous les détais pour chaque étape.</p>

<section id="choix-nom">
  <title>Choix du nom du portail (DNS forwarder)</title>
  <p>Par défaut, le portail s'appelle univnautes.entrouvert.lan, il est associé à l'adresse IP 10.42.0.1 par le forwarder DNS local (10.42.0.1 étant l'adresse IP de l'interface LAN). En production, il faut changer ce nom dans la DNS.</p>
<p>Pour cela, se rendre dans Services/DNS Forwarder et ajouter le nom dans les overrides, en lui associant l'IP 10.42.0.1 (ou l'IP de l'interface LAN, si vous l'avez changée).</p>
</section>

<section id="certificat-https">
  <title>Certificat et clé HTTPS</title>
  <p>Par défaut, le portail est accessible en HTTPS et utilise un certificat et une clé de test. Cela donne des messages d'alerte voire d'erreur sur les navigateurs.</p>
<p>Pour modifier le certificat HTTPS du portail, il faut se rendre sur la page Services/Captive Portal et y indiquer :</p>

<list>
  <item><p>HTTPS server name : le nom du serveur (celui qui est déclaré dans le certificat)</p></item>
  <item><p>HTTPS certificate : le certificat au format PEM ;</p></item>
  <item><p>HTTPS private key : la clé privée associée, au format PEM ;</p></item>
  <item><p>HTTPS intermediate certificate : le certificat de l'AC émettrice (en cas de certificat auto-signé de test, recopier le certificat), au format PEM.</p></item>
</list>

<note>
<p>Lorsque ces paramètres sont modifiés, le service cp_univnautes est automatiquement relancé pour prendre en compte les modifications.</p>
</note>

</section>

<section id="certificat-saml">
  <title>Certificat et clé SAML 2.0</title>
  <p>Sur l'onglet Univnautes dans la page Services/Captive portal, on indique :</p>
  <list>
    <item><p><em>SAML Private Key</em> : clé privée</p></item>
    <item><p><em>SAML Signing Key (Certificate)</em> : certificat (clé publique)</p></item>
  </list>

<note>
  <p>
     l'outil <em>System/Cert Manager</em> peut être utilisé pour générer la clé et le certificat SAML. Ils n'ont pas besoin d'être signés par une autorité reconnue.
  </p>
</note>

<note>
  <p>Lorsque ces paramètres sont modifiés, le service <em>cp_univnautes</em> est automatiquement relancé pour prendre en compte les modifications.
  </p>
</note>
</section>

<section id="declaration">
  <title>Déclaration des métadonnées dans la fédération</title>
  <p>Une fois le service relancé avec les nouvelles données SAML, les métadonnées XML du portail sont accessibles sur la page https://nom_du_portail/authsaml2/metadata</p>

<note style="warning">
  <p><em>nom_du_portail</em> doit être le nom choisi pour le serveur HTTPS). Il s'agit d'un fichier XML, qui peut être téléchargé et lu avec un éditeur de texte.</p>
</note>  

<p>Ces données du service doivent être enregistrées dans la fédération.</p>

<p>Pour les tests, chacun peut utiliser la fédération de test https://federation.renater.fr/test/enregistrement. Sur l'interface d'enregistrement d'un fournisseur de service (SP), il faut entrer les données une à une :</p>

<list>
  <item><p>Intitulé du service : Portail Captif Univnautes - Université xyz</p></item>
  <item><p>URL du service : https://nom_du_portail</p></item>
  <item><p>URL de vos méta données : <em>n'indiquez rien ici !</em> En effet l'URL du portail n'est pas joignable sur Internet ; il faut donc renseigner les paramètres ci-dessous un par un :</p></item>
  <item><p>entityID : https://nom_du_portail/authsaml2/metadata</p></item>
  <item><p>URL du service AssertionConsumerService SAML 1.0 : vide (notre fournisseur ne travaille qu'en SAML 2.0)</p></item>
  <item><p>URL du service AssertionConsumerService SAML 2.0 : https://nom_du_portail/authsaml2/singleSignOnPost</p></item>
  <item><p>Certificat X.509 : copié-collé du champ SAML Signing Key (Certificate) de la page Services/Captive Portal/Univnautes, en <em>retirant les première et dernière lignes</em> contenant les <code>-----BEGIN CERTIFICATE-----</code> et <code>-----END CERTIFICATE-----</code></p></item>
</list>

</section>

<section id="forcer-rechargement">
  <title>Forcer le rechargement des metadonnées et whitelist</title>
  <p>Les métadonnées et la whitelist sont téléchargées chaque heure. Cependant, il peut être utile de les actualiser immédiatement ces données. Pour cela, deux techniques :</p>

<list>
  <item><p>soit depuis la console (en direct ou en ssh), taper : <cmd># univnautes-update-metadata.sh</cmd></p></item>
  <item><p>soit depuis l'interface web d'administration, se rendre sur la page Services / Captive portal, sur l'onglet Univnautes et cliquer sur le bouton <code>Save</code> en bas de page, sans modifier de paramètre. Cela recharge whitelist IP et metadonnées.</p></item>
</list>

<p>Dans les deux cas, pour vérifier, se rendre dans Status / System Logs sur l'onglet Portal Auth : vous devez voir une ligne du genre <cmd>update-metadata: Loaded 117 providers</cmd>.</p>

</section>

</page>
