Le fichier proxy-config.xml définit les règles suivant lesquelles les demandes URI sont transférées au serveur et explique le mappage des chemins de contexte provenant du client avec l'URI de serveur.
Vous pouvez modifier le fichier proxy-config.xml dans un éditeur de texte. Enregistrez ce fichier quelque part dans le chemin d'accès aux classes pour que le servlet proxy puisse le repérer. Les modifications apportées au fichier proxy-config.xml ne sont pas dynamiques ; vous devrez redémarrer le servlet afin qu'elles soient prises en compte.
Prenons l'exemple d'un fichier d'archive d'entreprise EAR Java Platform, Enterprise Edition (Java EE) qui contient votre application Ajax. Vous utilisez le toolkit Dojo pour combiner du contenu provenant d'un autre serveur et qui renseigne sur les adresses de sociétés vendant du café. Le format des données est retourné d'un autre serveur sous forme de données JavaScript Object Notation (JSON). Vous souhaitez combiner ces données JSON avec l'application Ajax que vous développez (ce type de combinaison est souvent désigné par le terme de mashup côté client).
Entrez les lignes de code suivantes :
GET http://www.myinformation.com/location/coffee HTTP/1.1Le contenu JSON suivant est retourné :
{ "locations":{ "location":[ { "id":"Jumpin Joes Example", "city":"Anywhere", "location":"Weston Pkwy", "address":"126 Weston Pkwy, Anywhere, NC 27513", "date":"May 2nd, 2008" }, { "id":"Coffee & Crepes Example", "city":"Anywhere", "location":"Crossroads Blvd", "address":"123 Crossroads Blvd, Anywhere, NC 27518", "date":"May 3rd, 2008" } ] } }
Grâce au proxy Ajax, vous facilitez l'accès au service en ajoutant les lignes de code suivantes à votre fichier proxy-config.xml :
<?xml version="1.0" encoding="UTF-8"?> <proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/websphere/featurepack/v6.1/proxy-config" xsi:noNamespaceSchemaLocation="C:\temp\proxy-config.xsd"> <proxy:mapping contextpath="/location/coffee" url="http://www.myinformation.com"/> <proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> </proxy:policy> </proxy-rules>
contextpath est ici la racine de contexte du service accédé. L'URL est l'URL racine du service. A titre d'exemple, vous pourriez directement accéder au service dans un navigateur avec http://www.myinformation.com/location/coffee
Le chemin d'accès au proxy indiqué dans votre code dépend de la manière dont a été déployé le proxy Ajax. Voici un fragment de fichier Web.xml, utilisable pour le proxy Ajax :
<servlet-mapping> <servlet-name>ProxyServlet</servlet-name> <url-pattern>/proxymashup/*</url-pattern> </servlet-mapping>
var deferred = dojo.xhrGet( { url: "/proxy/proxymashup/location/coffee", timeout: 5000, handleAs : "text/json", headers: { "Content-Type":"text/html" }, } );
Le schéma XML du fichier proxy-config.xml est situé dans le répertoire WEB-INF/ du fichier AjaxProxy.war. Les deux schémas sont proxy-config_1.0.1.xsd et proxy-config_1.0.xsd. Le schéma proxy-config_1.0.1.xsd correspond à la version 1.0.1 et contient de nouvelles fonctions telles que le filtrage IP. Les utilisateurs peuvent continuer à utiliser des versions précédentes de proxy-config.xml qui correspondent à proxy-config_1.0.xsd.
<proxy:policy url="*" acf="none"> . . <proxy:mime-types> <proxy:mime-type>text/json</proxy:mime-type> </proxy:mime-types> . . </proxy:policy>
Si le service retourne text/html, le proxy réagira en retournant une erreur au client puisque text/html ne fait pas partie de la liste des types de contenu acceptables en provenance du serveur. Faute de spécification de <proxy:mime-types>, tous les types de contenu seront autorisés.
Pour contrôler le flux des cookies, définissez dans le fichier proxy-config.xml le nom des cookies autorisés. L'exemple suivant montre comment configurer le proxy pour qu'il ne passe que les cookies dont le nom de clé est Session-Cookie-0.
<proxy:policy url="*" acf="none"> . . <proxy:cookies> <proxy:cookie>Session-Cookie-0</proxy:cookie> </proxy:cookies> . . </proxy:policy>
<proxy:policy url="*" acf="none"> . . <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept*</proxy:header> <proxy:header>Content*</proxy:header> <proxy:header>Authorization*</proxy:header> <proxy:header>My-New-Header</proxy:header> <proxy:header>My-Other-New-Header</proxy:header> </proxy:headers> . . </proxy:policy>
Bon nombre de services peuvent nécessiter une connexion sécurisée avec SSL. En tant qu'application Web, le proxy Ajax exploite Java Secure Socket Extension (JSSE) qui est entièrement prise en charge par le produit. Consultez la documentation WebSphere® correspondante relative à la prise en charge des certificats SSL.
<proxy-meta-data> <proxy:name>unsigned_ssl_certificate_support</proxy:name> <proxy:value>true</proxy:value> </proxy-meta-data>
Lorsque unsigned_ssl_certificate_support est activé, le proxy Ajax accepte tous les certificats SSL. Dans la pratique, ce paramètre est utilisé en développement et ne doit pas être employé dans un environnement de production.
Plusieurs paramètres permettent de régler le proxy Ajax.
maxconnectionperhost est une valeur globale spécifiant le nombre maximal de connexions maintenues actives pour n'importe quelle combinaison d'hôtes ou de ports. Par défaut, la valeur est de 2. Vous pouvez augmenter cette valeur si votre application accède à plus de deux sites distants.
<proxy:meta-data> <proxy:name>maxconnectionsperhost</proxy:name> <proxy:value>2</proxy:value> </proxy:meta-data>
maxtotalconnections est le total maximum de connexions prises en charge par le proxy. La valeur par défaut est de 5. La valeur que vous choisissez doit être suffisamment élevée pour prendre en charge le nombre de connexions simultanées que vous êtes susceptible de recevoir. En pratique, prenez en compte la manière dont est configuré le conteneur Web et le nombre de connexions simultanées que prend en charge ce conteneur.
<proxy:meta-data> <proxy:name>maxtotalconnections</proxy:name> <proxy:value>5</proxy:value> </proxy:meta-data>
socket-timeout définit le délai d'attente par défaut du socket en millisecondes pendant lequel les données sont attendues une fois une connexion établie. La valeur par défaut est un valeur de délai d'attente de 0 qui est interprétée comme un délai d'attente illimité.
<proxy:meta-data> <proxy:name>socket-timeout</proxy:name> <proxy:value>5000</proxy:value> </proxy:meta-data>
Le nombre de nouvelles tentatives définit le nombre de nouvelles tentatives de socket que le proxy Ajax doit exécuter avant d'abandonner l'établissement d'une connexion. La valeur par défaut est de deux secondes.
<proxy:meta-data> <proxy:name>retries</proxy:name> <proxy:value>3</proxy:value> </proxy:meta-data>
connection-timeout définit la durée en millisecondes avant l'établissement d'une connexion. Si aucune valeur n'est indiquée, la valeur par défaut 60000 est utilisée. Si 0 est utilisé, la valeur est interprétée comme signifiant qu'aucun délai d'attente n'est appliqué.
<proxy:meta-data> <proxy:name>connection-timeout</proxy:name> <proxy:value>3000</proxy:value> </proxy:meta-data>
connection-pool-time définit la durée en millisecondes avant la tentative d'une connexion. Cela est le cas pour toutes les demandes suivantes une fois que la valeur de maxtotalconnections est dépassée. Si 0 est utilisé, la valeur est interprétée comme signifiant qu'aucun délai d'attente n'est appliqué. 0 est la valeur par défaut.
<proxy:meta-data> <proxy:name>connection-pool-timeout</proxy:name> <proxy:value>1000</proxy:value> </proxy:meta-data>
Par défaut, le proxy Ajax transmet uniquement les codes d'état HTTP supérieurs ou égaux à 200 et inférieurs à 400. Les codes d'état non compris dans cette plage sont automatiquement remplacés par une erreur de type 404 File Not Found (Fichier introuvable). La seule exception à cette règle est le code 401 (non autorisé), qui provoque une erreur de type 403 Forbidden (Interdit) sauf si l'attribut basic-auth-support est activé pour cette demande spécifique.
Vous pouvez retransmettre des codes HTTP supérieurs ou égaux à 400 avec un message en définissant le méta-paramètre forward-http-errors dans proxy-config.xml.
<proxy:meta-data> <proxy:name>forward-http-errors</proxy:name> <proxy:value>true</proxy:value> </proxy:meta-data>
Le proxy Ajax peut être configuré pour se connecter à un autre proxy avant d'accéder au réseau. La connexion via proxy en pass-through peut s'avérer nécessaire si le proxy Ajax doit traverser un pare-feu avant d'accéder au réseau. Le proxy Ajax prend en charge l'authentification Basic.
L'exemple suivant illustre la configuration d'un pare-feu de proxy fictif. passthru_host est un paramètre requis. Les autres éléments, tels passthru_type, passthru_username et passthru_password sont des paramètres facultatifs. Le paramètre passthru_type indique le type d'authentification utilisé. Le type par défaut est BASIC. DIGEST et NTLM peuvent également être utilisés. NTLM requiert des paramètres supplémentaires passthru_hostname et passthru_domain. Les paramètres passthru_port et passthru_realm sont également facultatifs. Si aucun paramètre passthru_port n'est spécifié, 80 sera utilisée par défaut pour le port. Si aucun paramètre passthru_realm n'est spécifié, les droits d'accès sont envoyés pour la totalité des tentatives d'authentification. En environnement de production, vous aurez intérêt à spécifier passthru_realm pour empêcher la présentation du nom et du mot de passe utilisateur pour toutes les demandes d'authentification.
<proxy-meta-data> <proxy:name>passthru_type</proxy:name> <proxy:value>BASIC</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_host</proxy:name> <proxy:value>9.17.237.132</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_port</proxy:name> <proxy:value>3128</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_realm</proxy:name> <proxy:value>MyRealm</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_username</proxy:name> <proxy:value>username</proxy:value> </proxy-meta-data> <proxy-meta-data> <proxy:name>passthru_password</proxy:name> <proxy:value>password</proxy:value> </proxy-meta-data>
L'authentification de base peut être activée à l'aide de l'attribut basic-auth-support pour une règle dans le fichier proxy-config.xml. Par exemple :
<proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1"> <proxy:mapping contextpath="/proxy/*" /> <proxy:policy url="*" acf="none" basic-auth-support="true"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> </proxy:policy> </proxy-rules>
Dans cet exemple, le proxy Ajax retransmet l'état HTTP et les informations d'en-tête au service cible et au client. Si basic-auth-support n'est pas défini et que le proxy Ajax reçoit une requête 401, il mappe alors la requête avec un code HTTP 403 : Forbidden (Interdit).
Remarque : Actuellement, le mécanisme d'authentification de base est la seule méthode d'authentification HTTP prise en charge par le proxy.
Le filtrage IP du proxy Ajax permet de créer des listes blanches ou des listes noires d'adresses IP afin de protéger les services auxquels le proxy Ajax peut se connecter. La liste noire contient les adresses IP de service auxquelles les clients ne sont pas autorisé à se connecter, tandis que la liste blanche contient les adresses IP auxquelles le proxy Ajax peut aussi se connecter.
proxy:ipfilter définit les adresses IP à filtrer. proxy:allow définit une liste blanche d'adresses IP ou d'une plage d'adresses IP. proxy:deny définit une liste noire d'adresses IP ou d'une plage d'adresses IP.
Par exemple :<proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1"> <proxy:mapping contextpath="/proxy/*" > <proxy:ipfilter> <proxy:deny>9.6.0.0/255.255.0.0</proxy:deny> <proxy:allow>9.6.1.0/255.255.255.0</proxy:allow> <proxy:deny>9.6.1.4</proxy:deny> </proxy:ipfilter> </proxy:mapping> <proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> </proxy:policy> </proxy-rules>
CWXJX1000E: The specified target hosts IP-address is prohibited by rule.
Toutefois le proxy Ajax accéderait à l'adresse 9.6.1.5 ou 9.6.1.120 mais refuserait l'accès à l'adresse 9.6.1.4.
Un autre exemple commence par mettre en liste noire toutes les adresses IP mais ajoute des plages IP supplémentaires. Dans cet exemple, l'élément de code suivant bloque toutes les adresses IP : *.*.*.*. Les adresses IP comprises dans la plage de 98.137.80.1 à 98.137.254 sont prises en charge.
<proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1"> <proxy:mapping contextpath="/rss/economy" url="http://rss.news.yahoo.com"> <proxy:ipfilter> <proxy:deny>*.*.*.*</proxy:deny> <proxy:allow>98.137.80.0/255.255.255.0</proxy:allow> </proxy:ipfilter> </proxy:mapping> <proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> </proxy:policy> </proxy-rules>
Lorsque vous ajoutez de nouvelles règles de filtrage, vous pouvez les combiner de plusieurs façons, mais le proxy Ajax les gère toujours dans l'ordre dans lequel elles ont été définies. Cela signifie que la dernière règle correspondante est toujours appliquée, quelles que soient les règles d'autorisation et de déni qui la précèdent.