====== DocWay4 - Metodi di Autenticazione ======

Il sistema di autenticazione di tomcat prevede l'utilizzo di moduli aggiuntivi per permettere diversi tipi di autenticazione.

La struttura modulare di questo sistema permette di utilizzare diversi sottosistemi. Viene a questo punto definito un [[http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html|Realm]] a cui è possibile assegnare il modulo desiderato: da quelli compresi nell'installazione di Tomcat, a quelli che possono essere scaricati dal web o addirittura implementati per soluzioni personalizzate.

I moduli di autenticazione attualmente utilizzati da noi sono:

  * <color darkblue>[[utenti:docway:docway4:metodi_autenticazione#Autenticazione di base|Autenticazione di base]], tramite db xml su disco (tomcat-users.xml)</color>
  * <color darkblue>[[utenti:docway:docway4:metodi_autenticazione#autenticazione_ldap|Autenticazione LDAP]], tramite directory su protocollo ldap</color>
  * <color darkblue>Autenticazione mysql, autenticazione SQL (manuale in elaborazione)</color>

In alternativa è possibile disattivare il sistema di autenticazione di Tomcat e utilizzare un proxy come Apache Web Server o IIS per fornire il servizio di autenticazione.
Questa pratica è poco utilizzata poiché Tomcat ha già molti moduli equivalenti a quelli per Apache WS e generalmente si decide di risparmiare risorse non impiegando IIS come proxy.

Tuttavia viene ancora utilizzato per integrazioni con ambienti Microsoft il seguente sistema:

  * <color darkblue>[[utenti:docway:docway4:metodi_autenticazione|Autenticazione Active Directory]], tramite un isapi per IIS</color>

===== Autenticazione di base =====

L'autenticazione di base di Apache Tomcat è un sistema proprietario di controllo delle credenziali tramite un database interno. Questo database è contenuto all'interno del file xml tomcat-users.xml nella cartella conf di Tomcat (ad es. /opt/apache-tomcat-7.0.52/conf).

__L'autenticazione base di Tomcat riassume in modo molto semplice ed essenziale la politica di ACL di Tomcat che prevede tre campi:__
  * Utente
  * Password
  * Ruolo

La limitazione dei diritti di ogni ruolo viene poi definita all'interno del file web.xml di ogni singola applicazione.

Un esempio di tomcat-users.xml può essere il seguente:

<code xml>

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="admjspuser"/>
  <role rolename="jspuser"/>
  <role rolename="manager-gui"/>
  <role rolename="admin"/>
  <user username="admin" password="37c93139d9fb08245b0eb90874912bf0" fullName="" roles="admin,admjspuser,jspuser,manager-gui"/>
  <user username="protocollista" password="37c93139d9fb08245b0eb90874912bf0" fullName="Utente base" roles="jspuser"/>
  <user username="responsabile" password="37c93139d9fb08245b0eb90874912bf0" fullName="Utente amministrativo" roles="admjspuser,jspuser",/>
</tomcat-users>

</code>

Come si può notare dall'esempio si tratta di un semplice DB in xml:

  * **tomcat-users** - elemento radice, deve essere presente e tutti i dati devono essere contenuti all'interno.
  * **role** – indica una dichiarazione di un ruolo, l'elemento è facoltativo in quanto tomcat crea questi elementi automaticamente dopo la prima lettura del file
  * **user** – elemento che definisce un utente
  * **username** – si tratta del nome utente per effettuare l'accesso
  * **password** – password di accesso con cifratura MD5
  * **roles** – ruolo assegnato all'utente

I ruoli preimpostati per un installazione di docway sono i seguenti:

  * **admin** - ruolo generico amministratore docway/tomcat
  * **manager-gui** – ruolo per l'accesso all'applicazione manager di tomcat
  * **admjspuser** – ruolo per l'accesso all'interfaccia amministratore di docway (docwayadm)
  * **jspuser** – ruolo per l'accesso semplice a tomcat.

Nonostante alcuni ruoli possano intersecarsi, è importante specificare esplicitamente nell'utente tutti i ruoli di cui si ha bisogno. In pratica l'amministratore avrà tutti i ruoli, il protocollista solo jspuser. 
E' inoltre consigliato l'utilizzo dei soli ruoli admjspuser e jspuser per gli utenti che non hanno formazione/mansioni tecniche.

Per la maggior parte degli ambienti è sufficiente specificare jspuser per tutti gli utenti, admjspuser per il responsabile del protocollo e admin,manager-gui,admjspuser per i tecnici.


==== Creazione del file tomcat-users.xml tramite script ====

E' possibile creare un nuovo file tomcat-user.xml in qualsiasi modo, basta seguire le specifiche precedenti.

Un possibile modo di creazione, che non prevede login con spazi e usa password iniziali da cambiare al primo accesso o per ambienti di test, potrebbe essere il seguente script bash:

<code bash|create_tomcat-users.sh>
  #!/bin/bash
  export nomefile="${1}"
  echo "<tomcat-users>
    <role rolename=\"manager-gui\"/> 
    <role rolename=\"admjspuser\"/> 
    <role rolename=\"admin\"/> 
    <role rolename=\"jspuser\"/> "
  # Rimuovere la riga seguente nel caso si voglia rimuovere l'utente admin 3di
  echo "<user username=\"admin\" password=\"21232f297a57a5a743894a0e4a801fc3\" roles=\"manager-gui,admin,admjspuser,jspuser\"/>”
  for i in `cat $nomefile`; do
     export $i
     password=`echo -n "${i}12345"|md5sum`
     echo "<user username=\"${i}\" password=\"${password}" roles=\"jspuser\"/>"
  done
  echo "</tomcat-users>"
</code>
Lo script prevede come parametro un file di testo che comprende tutti gli utenti uno per riga. Un esempio di esecuzione potrebbe essere:

  nomescript fileutenti.txt > tomcat-users.xml

E' necessario ora aggiungere i ruoli per gli utenti amministratori con un editor e assicurarsi che le password vengano modificate. E' possibile anche impostare l'applicativo per fare in modo che al primo accesso venga richiesta la modifica delle password automaticamente.

==== Caricamento dei nuovi utenti ====

Prima di caricare il nuovo file è necessario fermare il servizio tomcat:

  /etc/init.d/tomcat7 stop

Sovrascrivere il file esistente con quello appena creato:

  cp ~/tomcat-users.xml /opt/apache-tomcat-7.0.52/conf

Riavviare tomcat:

  /etc/init.d/tomcat7 start

Nello stesso modo è possibile effettuare le modifiche direttamente sul file nel caso di variazioni.

===== Autenticazione LDAP  =====

Il servlet container Tomcat supporta diverse fonti di autenticazione: oltre alla autenticazione di default, è possibile delegare l'autenticazione ad un'altra risorsa, quale un server LDAP.

La documentazione ufficiale sul sito di [[http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html|Apache Tomcat]] contiene una panoramica generale delle opzioni di collegamento, mentre a [[http://wiki.apache.org/tomcat/JNDI_HowTo|questa pagina]] sono riportati alcuni esempi pratici di utilizzo.

A seguire forniremo i valori da inserire sui campi interrogati da Tomcat per utilizzare la fonte LDAP come metodo di autenticazione.

Configurazione di esempio di una struttura LDAP:

<code ldif Utenti.ldif>
  dn: uid=admin,ou=docway,dc=net
  objectClass: inetOrgPerson
  uid: admin
  sn:  app
  cn: Amministratore
  userPassword: test
  
  dn: uid=protocollista,ou=docway,dc=net
  objectClass: inetOrgPerson
  uid: protocollista
  sn:  app
  cn: Utente Base
  userPassword: test
  
  dn: uid=responsabile,ou=docway,dc=net
  objectClass: inetOrgPerson
  uid: responsabile
  sn:  app
  cn: Utente Amministrativo
  userPassword: test
</code>

<code ldif Ruoli.ldif>
  dn: cn=admin,ou=docway,dc=net
  objectClass: groupOfUniqueNames
  cn: admin
  uniqueMember: uid=admin,ou=docway,dc=net
  
  dn: cn=manager-gui,ou=docway,dc=net
  objectClass: groupOfUniqueNames
  cn: manager-gui
  uniqueMember: uid=tomcat,ou=docway,dc=net 
  uniqueMember: uid=admin,ou=docway,dc=net
    
  dn: cn=admjspuser,ou=docway,dc=net
  objectClass: groupOfUniqueNames
  cn: admjspuser
  uniqueMember: uid=responsabile,ou=docway,dc=net 
  uniqueMember: uid=admin,ou=docway,dc=net

  dn: cn=jspuser,ou=docway,dc=net
  objectClass: groupOfUniqueNames
  cn: jspuser
  uniqueMember: uid=protocollista,ou=docway,dc=net 
  uniqueMember: uid=admin,ou=docway,dc=net
</code>

<code ldif Gruppi.ldif>
  dn: ou=docway,dc=net
  objectClass: organizationalUnit
  ou: docway
</code>

Questa Semplice configurazione associa ad ogni utente determinati roles:

admin: **jspuser, admin, manager-gui, aooadmjspuser, admjspuser**

responsabile: **aooadmjspuser, admjspuser, jspuser**

protocollista: **jspuser**

tutti raccolti nel gruppo **docway**

L'esatta specifica del metodo di autenticazione da utilizzare può essere specificata in due modi:

  - specifica nel file server.xml, alla quale ci si può poi riferire dall'interno del file di contesto dell'applicazione;
  - specifica direttamente nel file di contesto dell'applicazione

Un esempio di configurazione all'interno del contesto per DocWay4 può essere la seguente: all'interno della directory conf/Catalina/localhost/ di apache-tomcat sostituire il file DocWay4.xml con il seguente:

**Installazioni Linux**

<code xml>

<Context path="/DocWay4" docBase="/opt/3di.it/docway4/DocWay4" debug="0" privileged="true">


<Realm   className="org.apache.catalina.realm.JNDIRealm"
        connectionURL="ldaps://ldaphost:636"
        userPattern="uid={0},ou=docway,dc=net"
        roleBase="ou=docway,dc=net"
        roleName="cn"
        roleSearch="(uniqueMember={0})"
/>
         <!--
	  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
	    allow="127.0.0.1,localhost"/>
	  -->
  
</Context>
</code>

**installazioni windows**

<code xml>

<Context path="/DocWay4" docBase="e:\3di.it\docway4\DocWay4" debug="0" privileged="true">


<Realm   className="org.apache.catalina.realm.JNDIRealm"
        connectionURL="ldaps://ldaphost:636"
        userPattern="uid={0},ou=docway,dc=net"
        roleBase="ou=docway,dc=net"
        roleName="cn"
        roleSearch="(uniqueMember={0})"
/>
          <!--
	  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
	    allow="127.0.0.1,localhost"/>
	  -->
  
</Context>
</code>

Gli esempi sopra riportati sono adeguati ad uno scenario nel quale:

  - il server LDAP non richiede autorizzazione per il bind (assenza di attributi che indichino un nome utente e una password);
  - il nome utente (login name) è contenuto esso stesso nel distinguished name (dn) degli elementi dell'albero della directory (esempio: uid=utente_docway,ou=docway,dc=net);
  - il nome del/dei ruolo/i è contenuto nel campo cn sotto ou=docway,dc=net e riportato nell'attributo uniqueMember di un elemento di tipo utente con l'intero distinguished name ({0} in questo caso è l'intero dn).

Per una realtà nella quale le informazioni per la login degli utenti ed i loro ruoli sono più strutturati, si può utilizzare una configurazione tipo la seguente (sono omessi i dettagli relativi al context poiché irrilevanti per questo esempio):

<code xml>
<Context [...]>
<Realm   className="org.apache.catalina.realm.JNDIRealm"
        connectionURL="ldaps://ldaphost:636"
        alternateURL="ldaps://ldapsecondaryhost:636"
        connectionName="cn=bindUser,ou=docway,dc=net"
        connectionPassword="youllneverguessit"
        userBase="ou=Utenti-docway,ou=docway,dc=net"
        userSubtree="true"
        userSearch="(loginName={0})"
        roleBase="ou=Gruppi-docway,ou=docway,dc=net"
        roleName="cn"
        roleSearch="(member={0})"
/> 
</Context>
</code>

In questo secondo esempio, la realtà delineata è la seguente:

  - Esiste un secondo server LDAP (**alternateURL**), al quale potersi rivolgere per l'autenticazione;
  - i parametri **connectionName** e **connectionPassword** indicano le credenziali (in questo caso, l'utente è specificato mediante un distinguished name) per effettuare il bind al server LDAP;
  - gli elementi che contengono le informazioni degli utenti sono sotto il ramo ou=Utenti-docway,ou=docway,dc=net, anche in altre ou ivi contenute (parametro **userSubtree="true"**);
  - l'attributo nel quale ricercare la login specificata dagli utenti nella maschera di login all'interno di un elemento utente è loginName (parametro **userSearch**);
  - i ruoli sono presenti sotto il ramo ou=Gruppi-docway,ou=docway,dc=net (parametro **roleBase**);
  - il nome del ruolo è da ricercarsi nel suo common name (**roleName="cn"**);
  - infine, il nome del ruolo è anche contenuto nell'attributo member all'interno di un elemento utente (**roleSearch="(member={0})"**), per effettuare un controllo incrociato.

==== Considerazioni ====

La configurazione sopra riportata è da ritenersi un esempio; in scenari con già una alberatura LDAP costituita 
andranno modificati i valori. Tuttavia i gruppi e le risorse sono necessari per il corretto funzionamento della applicazione.

===== Autenticazione tramite Active Directory =====

E' possibile in alternativa all'autenticazione tomcat o ldap usufruire del servizio Active Directory per gestire l'accesso al protocollo. Ovviamente è necessario inserire l'utenza anche in acl con il corrispettivo utente nella sezione "login".

==== Requisiti ====

Per utilizzare le utenze di Active Directory di Windows sulla macchina windows che ospita l'applicativo o su una macchina windows separata((questo è necessario nel caso la macchina che ospita l'applicativo abbia un sistema operativo differente)) (frontend) è necessario:
  * Avere IIS versione 6 o superiore già installato nel sistema
  * Utilizzare una macchina Windows che sia nel dominio desiderato di Active Directory ma che non sia un Domain Controller.

==== Configurazione di Tomcat ====

Per configurare correttamente Tomcat per collegarsi con IIS in modo da sfruttare i suoi meccanismi di autenticazione, è necessario cambiare le impostazioni di Tomcat in modo da indicargli di non occuparsi dell'autenticazione degli utenti, poiché se ne occuperà qualcun altro a monte (IIS nel nostro caso).
Nello specifico si tratta di:

  - disabilitare l'utilizzo dell'autenticazione Tomcat (qualunque tipo sia stato configurato) da parte dell'applicazione DocWay4;
  - disabilitare l'autenticazione di tipo Tomcat dal connettore AJP, utilizzato per connettere IIS con Tomcat

Le azioni da eseguire sono:
  - sostituire il file docway4/DocWay4/WEB-INF/web.xml con docway4/DocWay4/WEB-INF/web.xml_AD
  -  aprire il file server.xml nella conf/ di Tomcat e modificare l'elemento riguardante AJP aggiungendo l'attributo **tomcatAuthentication** e impostandolo a **false**, nel seguente modo:

<code xml>
    <!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" tomcatAuthentication="false" />
</code>

==== Configurazione di Internet Information Services (IIS) ====

=== Requisiti ===

  * Windows Server con tecnologia IIS  
  * Comunicazione di rete diretta con il server in cui si trova Apache Tomcat (se non risiede sulla macchina stessa)
  * Applicazione MSXML installata sul server ((Solitamente la versione corretta è già installata con IIS7+, viene fornita una versione compatibile con IIS 6 nel pacchetto di installazione))
  * Il server deve essere parte dello stesso dominio Active Directory dei client ((In alcuni casi è possibile utilizzare anche domini in trust, se vengono configurati correttamente i client))
  * Il server NON deve essere un domain controller.

=== Requisiti minimi ===

  * Windows Server 2003 con IIS 6 o superiore
  * Internet Explorer 9 o superiore, Google Chrome o Mozilla Firefox ((vedere [[http://kb.mozillazine.org/Network.automatic-ntlm-auth.trusted-uris|le opzioni di configurazione]] da abilitare)) nel lato client, per usufruire dell'autenticazione integrata di Windows (NTLM).

=== Consigliati ===
  * Windows Server 2008 con IIS 7 o superiore
  * Internet Explorer 9 o superiore, Google Chrome o Mozilla Firefox ((vedere [[http://kb.mozillazine.org/Network.automatic-ntlm-auth.trusted-uris|le opzioni di configurazione]] da abilitare)) nel lato client, per usufruire dell'autenticazione integrata di Windows (NTLM).

== Link utili ==

  * [[http://tomcat.apache.org/tomcat-7.0-doc/config/ajp.html|Documentazione su AJP]]
  * [[http://wiki.apache.org/tomcat/Tomcat_and_IIS_Howto|Wiki Tomcat sull'integrazione con IIS7+]]

=== Configurazione IIS versione 6 ===

E' possibile accedere alla configurazione di IIS tramite il pannello //Strumenti di Amministrazione//.

Nella sezione siti web sotto //Sito predefinito// creare una nuova directory virtuale dandogli il nome //DocWay4//, e farla puntare all'omonima directory in <color #004000>e:\3di.it\docway4\</color>:

{{:documentazione_3di:alias.jpg|Configurazione directory virtuale - Alias}}
{{:documentazione_3di:percorso.jpg|Configurazione directory virtuale - Percorso}}

{{:documentazione_3di:diritti.jpg|Configurazione directory virtuale - Diritti}}

<color #505050>Attenzione: è possibile utilizzare una condivisione di rete alla risorsa xway, nel caso si trovi su un altro server</color>

  * <color darkblue>**Creare la directory virtuale xway**</color>

Inoltre è necessario configurare nelle proprietà:

  * <color darkblue>**Impostare livello di protezione: "bassa" (in inglese "MSSharePointAppPool")**</color>
  * <color darkblue>**Togliere accesso all'utente anonimo**</color>
  * <color darkblue>**Abilitare nel campo autenticazione solo questi due campi: //Autenticazione integrata di Windows// e //Autenticazione di base (password non crittografata)//**</color>

Successivamente è necessario creare le directory virtuali //engine// con diritti di esecuzione ISAPI:

{{:documentazione_3di:engines.jpg|Configurazione directory virtuale - Engine}}
{{:documentazione_3di:isapi_create.jpg|Configurazione directory virtuale - Diritti ISAPI}}

Devono essere create nella sezione <color #004000>xway\application\xdocway</color> con il percorso <color #004000>e:\3di.it\docway3\www\isapi\docway3\bin</color> e nella sezione <color #004000>xway\base\acl</color> con il percorso <color #004000>e:\it-3di\docway3\www\isapi\acl\bin</color>

<color #505050>Attenzione: la cartella www e il suo contenuto deve necessariamente trovarsi sullo stesso server in cui si trova IIS, nel caso sarà necessario copiarle in locale</color>

  * <color darkblue>**Creare le directory virtuali engine con i diritti di esecuzione ISAPI**</color>

Successivamente è necessario aggiungere alla sezione Estensioni servizio web le librerie dll utilizzate:

  * <color #004000>www\isapi\acl\bin\hcprot.dll</color>
  * <color #004000>www\isapi\acl\bin\hcadm.dll</color>
  * <color #004000>www\isapi\docway3\bin\hcadm.dll</color>
  * <color #004000>www\isapi\docway3\bin\hcprot.dll</color>
utilizzando un nome indicativo del servizio formito (es: docway) e abilitare il checkbox finale "//consenti....//".
  * <color darkblue>**Inserire le librerie nelle estensioni consentite**</color>

<color #505050>Attenzione: il server che ospita IIS non deve essere un domain controller. Esiste qualche policy di base (o bug) che blocca l'accesso agli utenti ad IIS sul domain controller a meno che non si utilizzi l'utente fittizio AUTHENTICATED USERS. Questo genera buchi nella sicurezza.</color>

  * <color darkblue>**Proseguire con il capitolo Configurazioni aggiuntive**</color>

== Configurazione IIS versione 7 ==

Windows Server 2008 ha una gestione modulare dei componenti e di base le funzioni necessarie non sono installate. Per attivarle accedere all'interfaccia di gestione del server e selezionare il ruolo "WEB SERVER". Quando viene richiesto quali componenti attivare, aggiungere cgi, isapi, autenticazione integrata e autenticazione di base.

Una volta installato IIS creare una nuova directory virtuale dandogli il nome //xway//, e farla puntare all'omonima directory in <color #004000>e:\3di.it\docway3\</color>:

{{:documentazione_3di:addxway.jpeg|Creazione directory virtuale - Menu}}
{{:documentazione_3di:addxway2.jpeg|Creazione directory virtuale - UI}}

  * <color darkblue>**Creare la directory virtuale xway**</color>

Successivamente è necessario creare le applicazioni //engine//:

{{:documentazione_3di:addapp.jpeg|Configurazione applicazione Engine - Menu}}
{{:documentazione_3di:addapp2.jpeg|Configurazione applicazione Engine (xdocway) - UI}}
{{:documentazione_3di:addapp3.jpeg|Configurazione applicazione Engine (acl) - UI}}

Devono essere create nella sezione <color #004000>xway\application\xdocway</color> con il percorso <color #004000>e:\3di.it\docway3\www\isapi\docway3\bin</color> e nella sezione <color #004000>xway\base\acl</color> con il percorso <color #004000>e:\it-3di\docway3\www\isapi\acl\bin</color>

  * <color darkblue>**Creare le applicazioni engine per xdocway e acl**</color>

Di base IIS 7 non consente l'esecuzione di isapi a 32 bit (come hcprot.dll). Questa funzionalità deve essere attivata nel seguente modo:
Accedere a {{:documentazione_3di:apppool.jpeg|Application Pools Menu}} e selezionare {{:documentazione_3di:defapppool.jpeg|Default Application Pool}} nel menu a destra scegliere {{:documentazione_3di:defapppooladvsett.jpeg|Default Application Pool - Advanced Settings}}, apparirà la seguente finestra:

{{:documentazione_3di:defapppooladvsett_detail.jpeg|Default Application Pool - Advanced Settings Detail}}

In questa tabella modificare il valore //Enable 32-bit Applications// in TRUE.

  * <color darkblue>**Abilitare le isapi a 32 bit**</color>
<color #505050>Attenzione: se si abilita questa impostazione del pool di applicazioni di default le isapi a 32 bit funzioneranno, tuttavia non sarà comunque possibile mischiare applicazioni a 32 bit e applicazioni a 64 nello stesso pool. Se avete già altre applicazioni a 64 bit installate è necessario creare un'altro pool altrimenti smetteranno di funzionare.</color>

Sempre nel {{:documentazione_3di:defapppool.jpeg|Default Application Pool}} disabilitare l'esecuzione di codice .NET, poiché interferisce in alcuni casi con l'esecuzione delle isapi. Selezionare {{:documentazione_3di:defapppoolbassett.jpeg|Default Application Pool - Basic Settings}}, apparirà la finestra:

{{:documentazione_3di:defapppoolbassett_detail.jpeg|Default Application Pool - Basic Settings Detail}}

Nella tendina con etichetta //.NET Framework Version// selezionare <color #004000>No Managed Code</color>

  * <color darkblue>**Disablitare .NET Framework**</color>
Spostarsi su {{:documentazione_3di:defwebsite.jpeg|Default Web Site}} nel menu a sinistra e selezionare il pulsante {{:documentazione_3di:handler_mappings.jpeg|Handler Mappings}}, nel menu a destra aprire la voce {{:documentazione_3di:edit_fea_perm.jpeg|Edit Feature Permission}}. Comparirà una finestra:

{{:documentazione_3di:handler_mappings_detail.jpeg|Edit Feature Permission detail}}

Selezionare come nella foto tutti i diritti di esecuzione.

  * <color darkblue>**Attivare i diritti di esecuzione delle isapi**</color>
Tornare su {{:documentazione_3di:defwebsite.jpeg|Default Web Site}} e selezionare il pulsante {{:documentazione_3di:auth.jpeg|Authentication}}, si accederà alla sezione relativa:

{{:documentazione_3di:auth_detail.jpeg|Authentication detail}}

Disabilitare l'autenticazione anonima e abilitare l'autenticazione di base e l'autenticazione Windows come da immagine.
  * <color darkblue>**Abilitare l'autenticazione integrata**</color>
Spostarsi nella sezione superiore nel menu a sinistra dove compare il nome del server e selezionare il pulsante Isapi and CGI restrictions.

Comparirà una finestra con un elenco delle isapi consentite. Inserire i seguenti percorsi come da immagine:
  * <color #004000>www\isapi\acl\bin\hcprot.dll</color>
  * <color #004000>www\isapi\acl\bin\hcadm.dll</color>
  * <color #004000>www\isapi\docway3\bin\hcadm.dll</color>
  * <color #004000>www\isapi\docway3\bin\hcprot.dll</color>

{{:documentazione_3di:isapicgirestr_detail.jpeg|Isapi and Cgi Restrictions detail}}

Assicurarsi che la casella di spunta sia selezionata.

  * <color darkblue>**Consentire le isapi di Docway**</color>

  * <color darkblue>**Proseguire con il capitolo Configurazioni aggiuntive**</color>

== Configurazioni aggiuntive  ==

E' necessario configurare i file hc.ini nelle cartelle <color #004000>e:\3di.it\docway3\www\isapi\docway3\bin</color> e <color #004000>e:\it-3di\docway3\www\isapi\acl\bin</color>, modificando il valore //host// nel caso il server che ospita tomcat non sia lo stesso su cui si trova IIS.

   * <color darkblue>**Configurare opportunamente hc.ini**</color>

E' necessario riavviare il servizio di IIS per applicare la configurazione.
   * <color darkblue>**Riavviare il "Servizio di pubblicazione sul World Wide Web"**</color>

E' necessario impostare i diritti sul filesystem nelle cartelle delle isapi <color #004000>e:\3di.it\docway3\www</color>, in modo che siano leggibili dagli utenti che utilizzeranno l'autenticazione IIS. Per farlo solitamente si aggiungono 2 gruppi di utenti locali nel server:

• <color #004000>**docwayusers**</color> in cui dovranno essere inseriti i protocollisti

• <color #004000>**docwayadm**</color> in cui dovranno essere inseriti gli utenti con possibilità di accedere all'applicativo con credenziali degli altri utenti

Il gruppo docwayadm dovrà avere accesso in lettura e in esecuzione a entrambe le cartelle e a tutti i files contenuti, il gruppo docwayusers a tutti i file tranne hcadm.dll.

Aggiungere inoltre nell'intero albero www gli utenti locali di servizio di IIS (solo per la versione 6) con diritto //Controllo completo//:

  * utente IWAM_<nomemacchina>
  * gruppo IIS_WPG

<color #505050>ATTENZIONE: Per abilitare il logging all'interno del file hc.log sia nella cartella isapi\docway3 sia nella cartella isapi\acl è necessario impostare i diritti di scrittura sui file hc.log e hc.loc per entrambi i gruppi docwayadm e docwayprot. Il file hc.log non è soggetto a restrizioni di dimensione, per questo motivo per evitare di saturare il disco nel tempo, si sconsiglia di attivare il logging se non per motivi di debug.</color>

  * <color darkblue>**Impostare i diritti del filesystem sulle cartelle isapi**</color>

==== Configurazione di Internet Information Services (IIS) - Docway4 e connettore AJP ====

Windows Server 2008 ha una gestione modulare dei componenti e di base le funzioni necessarie non sono installate. Per attivarle accedere all'interfaccia di gestione del server e selezionare il ruolo “WEB SERVER”. Quando viene richiesto quali componenti attivare, aggiungere cgi, isapi, autenticazione integrata e autenticazione di base.

Download connettore (64 bit): [[http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/windows/|link]]

1- <color blue>Creare la  directory **tomcat_iis_connector**; la directory deve contenere i seguenti file:</color>
  * **isapi_redirect.dll** (scaricata dal link precedente)
  * **isapi_redirect.properties** con il seguente contenuto:

<code>
# Configuration file for the Jakarta ISAPI Redirector

# The path to the ISAPI Redirector Extension, relative to the website
# This must be in a virtual directory with execute privileges
extension_uri=/jakarta/isapi_redirect.dll

# Full path to the log file for the ISAPI Redirector
log_file=E:\tomcat_iis_connector\isapi_redirect.log

# Log level (debug, info, warn, error or trace)
log_level=error

# Full path to the workers.properties file,
worker_file=E:\tomcat_iis_connector\workers.properties

# Full path to the uriworkermap.properties file
worker_mount_file=E:\tomcat_iis_connector\uriworkermap.properties

rewrite_rule_file=E:\tomcat_iis_connector\rewrites.properties
</code>

  * **workers.properties** con il seguente contenuto:

<code>
# workers.properties.minimal -
#
# This file provides minimal jk configuration properties needed to
# connect to Tomcat.
#
# The workers that jk should create and work with.
#
worker.list=ajp13,wlb,jkstatus

#
# Defining a worker named worker1 and of type ajp13.
# Note that the name and the type do not have to match.
#
worker.ajp13w.type=ajp13
worker.ajp13w.host=localhost
worker.ajp13w.port=8009
worker.wlb.type=lb
worker.wlb.balance_workers=ajp13w
worker.jkstatus.type=status
</code>


  * **uriworkermap.properties** con il seguente contenuto:

<code>
# uriworkermap.properties - IIS
#
# This file provides mappings for the workers
# defined in workermap.properties.minimal.
# The general syntax for this file is:
# [URL]=[Worker name]
/docway/*=wlb
/DocWay4/*=wlb
</code>

  * **rewrite.properties** che può essere lasciato vuoto.

2- <color blue>Aggiungere il path dell'isapi al server IIS</color>

Aprire IIS Manager, posizionarsi sul server e cliccare su **ISAPI and CGI Restrictions**; dal menù **Actions** selezionare **Add** e aggiungere il path dell'isapi avendo cura di selezionare il checkbox **Allow extension path to execute**

{{ :documentazione_3di:installazione_docway4:iis04.png |}}

3- <color blue>Create nuova Application Pool denominata **jakarta**</color>

Posizionarsi sul server e aggiungere una nuova **Application Pool** denominata **jakarta** e configurata come da immagine:

{{ :documentazione_3di:installazione_docway4:iis05.png |}}

Verificare che nelle **Advanced Settings** dell'Application Pool appena creata le applicazioni a 32 bit siano disabilitate:

{{ :documentazione_3di:installazione_docway4:iis03.png |}}

4- <color blue>Aggiungere il filtro ISAPI al Default Web Site</color>

Posizionarsi sul **Default Web Site** e cliccare sul menù **ISAPI Filter**; aggiungere un nuovo filtro come da immagine:

{{ :documentazione_3di:installazione_docway4:iis06.png |}}

5- <color blue>Creare una **Virtual Directory** denominata **jakarta**</color>

Posizionarsi sul Default Web Site a aggiungere una nuova **Virtual Directory** denominata **jakarta** come da immagine (NB: scrivere jakarta il lover case):

{{ :documentazione_3di:installazione_docway4:iis07.png |}}

Posizionarsi sulla virtual directory jakarta appena creata e selezionare il menù **Handler Mappings**; dalle Actions selezionare **Edit Feature Permission** e selezionare tutte le opzioni presenti (Read, Script, Execute):

{{ :documentazione_3di:installazione_docway4:iis09.png |}}

6- <color blue>Creare una **Virtual Directory** denominata **DocWay4**</color>

Posizionarsi sul Default Web Site a aggiungere una ulteriore **Virtual Directory** denominata **DocWay4** come da immagine (NB: scrivere DocWay4 rispettando le maiuscole e le minuscole):

{{ :documentazione_3di:installazione_docway4:iis08.png |}}

Nel Physical Path inserire il percorso completo fino alla directory DocWay4 dell'installazione: ad esempio **E:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\DocWay4**.

Posizionarsi sulla virtual directory DocWay4 appena creata e selezionare il menù **Handler Mappings**; dalle Actions selezionare **Edit Feature Permission** e selezionare tutte le opzioni presenti (Read, Script, Execute):

{{ :documentazione_3di:installazione_docway4:iis10.png |}}

7- <color blue>Abilitare l'autenticazione integrata</color>

Posizionarsi sul Default Web Site e selezionare il menù **Authentication**; abilitare le modalità di autenticazone **Basic Authentication** e **Windows Authenitcation** e __disabilitare__ **Anonymous Authentication** coma da immagine:

{{ :documentazione_3di:installazione_docway4:iis11.png |}}

8- <color blue>Riavviare il servizio IIS</color>

9- <color blue>Assegnare permessi al gruppo IIS_USERS</color>

Assegnare i permessi al gruppo **IIS_IUSRS** sulle directory:
  * **DocWay4**
  * **tomcat_iis_connector**

<WRAP important round centeralign>
**Assicurarsi di aver impostato il web.xml dell'applicazione per autenticarsi su AD.**

**Assicurarsi di aver seguito le indicazioni in questo [[http://wiki.3di.it/doku.php?id=documentazione_3di:installazione_docway4:autenticazione_tomcat&#configurazione_di_tomcat|paragrafo]] **
</WRAP>

==== Configurare i limiti di download (e upload) ====

Nel caso non si riescano a scaricare allegati superiori ai 25MB, è necessario effettuare l'override della proprietà "maxRequestLength" a valori più alti.
Per fare ciò, modificare il file web.config relativo al sito di docway aggiungendo i seguenti elementi:
<code xml>
<configuration>
[...]
  <system.web>
    <httpRuntime maxRequestLength="XXXXX" executionTimeout="600" />
  </system.web>
[...]
  <system.webServer>
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="YYYYYY" />
      </requestFiltering>
    </security>
  </system.webServer>
[...]
</configuration>
</code>
dove XXXXXX e YYYYYY sono, rispettivamente, la massima dimensione di download ed upload consentiti (in byte).

==== Accorgimenti lato client ====

=== Impostazioni specifiche per Internet Explorer (IE) ===

Per poter utilizzare l'autenticazione integrata di Windows, è necessario che all'interno dell'area di sicurezza in cui si trova il sito del protocollo, sia abilitata la voce: //accedi automaticamente  con nome utente e password correnti//. Dato che questa impostazione è attivata di default unicamente nell'area "Intranet Locale", si consiglia di non attivare l'opzione per le altre aree (per motivi di sicurezza), ma di collocare manualmente il sito in quest'area.

**Per inserire il sito del protocollo nell'area "Intranet Locale" in Internet Explorer:**
  - <color darkblue>**Aprire Internet Explorer, andare nel menù "Strumenti" e cliccare "Opzioni Internet":**</color> \\ \\ \\ {{:documentazione_3di:manuale_utente_docway3_titulus3:ie-intranet00.png?nolink|}} \\ \\ \\ \\
  - <color darkblue>**Cliccare sulla scheda "Protezione":**</color> \\ \\ \\ {{:documentazione_3di:manuale_utente_docway3_titulus3:ie-intranet01.png?nolink|}} \\ \\ \\ \\
  - <color darkblue>**Selezionare "Intranet locale" e cliccare sul pulsante "Siti":**</color> \\ \\ \\ {{:documentazione_3di:manuale_utente_docway3_titulus3:ie-intranet02.png?nolink|}} \\ \\ \\ \\
  - <color darkblue>**Cliccare sul bottone "Avanzate" nella finestra che viene aperta:**</color> \\ {{:documentazione_3di:manuale_utente_docway3_titulus3:ie-intranet03.png?nolink|}} \\ \\ \\ \\ 
  - <color darkblue>**Scrivere l'URL del sito di DocWay nell'apposita casella di testo (dove è scritto http://esempio.com), assicurarsi che non sia selezionata la voce "Richiedi verifica server (https:) per tutti i siti dell'area" e cliccare sul bottone "Aggiungi":**</color> \\ \\ \\  {{:documentazione_3di:manuale_utente_docway3_titulus3:ie-intranet04.png?nolink|}} \\ \\ \\ \\ 
  - <color darkblue>**Il sito di DocWay dovrebbe ora comparire nell'elenco di siti web associati all'intranet locale:**</color>

<color #505050>Attenzione: di base, se il protocollo si trova all'interno della stessa rete fisica della macchina client si troverà nell'area "Intranet", altrimenti si troverà nell'area "Internet". E' possibile verificare in quale aree di sicurezza si trova il sito del protocollo rispetto al client osservando quanto scritto nella barra di stato di Internet Explorer (icona in basso a destra)</color>

Il link differirà da quello base di tomcat in questo modo:
  http://[host]/xway/application/xdocway/engine/hcprot.dll

oppure

  http://[host]/xway/base/acl/engine/hcprot.dll

E' possibile comunque indicare le variabili aggiungendo "?variable=valore" al termine dell'indirizzo.