Datei WEB-INF/proxy-config.xml


Die Datei proxy-config.xml definiert die Richtlinie, nach der die Weiterleitung von URI-Anforderungen über den Proxy unterstützt wird, und legt fest, wie Inhaltspfade vom Client dem URI auf einem Server zugeordnet werden.

Sie können die Datei "proxy-config.xml" mit einem Texteditor ändern. Speichern Sie diese Datei an einer Position im Klassenpfad, die das Proxy-Servlet finden kann. Änderungen an der Datei "proxy-config.xml" sind nicht dynamisch. Sie werden erst wirksam, nachdem Sie das Servlet neu gestartet haben.

Beispielsyntax

Stellen Sie sich eine Java-EE-Datei (JavaTM Platform, Enterprise Edition) vor, die Ihre Ajax-basierte Anwendung enthält. Sie verwenden Dojo Toolkit, um Inhalte zu kombinieren, die von einem anderen Server stammen und Positionsinformationen zu Cafés enthalten. Das Datenformat wird von einem anderen Server in Form von JSON-Daten (JavaScriptTM Object Notation) zurückgegeben. Kombinieren Sie die JSON-Daten, die von der von Ihnen entwickelten Ajax-basierten Anwendung zurückgegeben werden. Dieser Vorgang wird auch als clientseitige Kombination bezeichnet.

Geben Sie die folgenden Codezeilen ein:

GET http://www.myinformation.com/location/coffee HTTP/1.1
Der folgende JSON-Inhalt wird zurückgegeben:
{
   "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"
         } ]
   }
}

Über den AJAX-Proxy können Sie den Service verfügbar machen, indem Sie der Datei proxy-config.xml die folgenden Codezeilen hinzufügen:

<?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>

Die contextpath-Angabe steht für das Kontextstammverzeichnis des Service, auf den zugegriffen wird. Der URL ist der Stamm-URL des Service. Sie könnten den Service beispielsweise in einem Browser direkt über den URL "http://www.myinformation.com/location/coffee" aufrufen.

Der Pfad für den Zugriff auf den Proxy in Ihrem Code hängt davon ab, wie der AJAX-Proxy implementiert ist. Sehen Sie sich das folgende XML-Fragment aus einer Datei "web.xml" an, das für den Ajax-Proxy verwendet werden könnte:

	<servlet-mapping>
		<servlet-name>ProxyServlet</servlet-name>
		<url-pattern>/proxymashup/*</url-pattern> 		
	</servlet-mapping>	
Im obigen Beispiel ist ProxyServlet das Servlet für den Ajax-Proxy. <url-pattern> ist die Servlet-Zuordnung zu /proxymashup/*. Wenn das Kontextstammverzeichnis der WAR-Datei beispielsweise /proxy lautet, verwenden Sie den folgenden Code für den Zugriff auf den Service über Dojo:
var deferred = dojo.xhrGet( {
                             url: "/proxy/proxymashup/location/coffee",
                             timeout: 5000,            
                             handleAs : "text/json",
                             headers: { "Content-Type":"text/html" },          
                             } );
                  

XML-Schema

Die XML-Schemas für die Datei "proxy-config.xml" befinden sich im Verzeichnis WEB-INF/ für die Datei "AjaxProxy.war". Die Schemas heißen "proxy-config_1.0.1.xsd" und "proxy-config_1.0.xsd". Das Schema "proxy-config_1.0.1.xsd" entspricht der Version 1.0.1 und enthält neue Features wie z. B. IP-Filter. Benutzer können weiterhin vorherige Versionen der Datei "proxy-config.xml" verwenden, die dem Schema "proxy-config_1.0.xsd" entsprechen.

MIME-Typen filtern

Der MIME-Typ (Multipurpose Internet Mail Extensions) steuert die Medientypen, die der Proxy vom Service akzeptiert. Wenn Sie im vorherigen Beispiel sicherstellen möchten, dass nur der Inhaltstyp text/json an den Client zurückgegeben wird, können Sie der Datei proxy-config.xml den folgenden Eintrag hinzufügen:
<proxy:policy url="*" acf="none">
    .
    .
    <proxy:mime-types>
       <proxy:mime-type>text/json</proxy:mime-type>
    </proxy:mime-types>
    .
    .
	</proxy:policy>

Wenn der Service text/html zurückgibt, sendet der Proxy mit einer Fehlerbedingung an den Client, da "text/html" nicht als gültiger Inhaltstyp vom Service aufgelistet ist. Wenn <proxy:mime-types> nicht angegeben ist, werden alle Inhaltstypen zugelassen.

Cookies filtern

Sie können den Ajax-Proxy verwenden, um den Fluss von Cookies an den Client über eine Cookie-Richtlinie zu steuern. Nur Cookies, die dem Wert in der Cookie-Richtlinie entsprechen, können über den Ajax-Proxy weitergeleitet werden. Wenn keine Cookierichtlinie angegeben ist, kann kein Cookie über den Ajax-Proxy weitergeleitet werden.

Wenn Sie Cookies steuern möchten, definieren Sie den zulässigen Cookie-Namen in der Datei "proxy-config.xml". Das folgende Beispiel zeigt, wie Sie den Proxy so konfigurieren können, dass nur Cookies mit dem Cookie-Schlüsselnamen Session-Cookie-0 übergeben werden.

<proxy:policy url="*" acf="none">
    .
    .
    <proxy:cookies>
       <proxy:cookie>Session-Cookie-0</proxy:cookie>
    </proxy:cookies>
    .
    .
	</proxy:policy>

HTTP-Header filtern

Standardmäßig lässt der Ajax-Proxy die Übergabe der folgenden HTTP-Header an den Client zu: User-Agent, Accept*, Content*, Authorization*. Der Stern (*) ist ein Platzhalterzeichen. Alle anderen Header werden vom Ajax-Proxy gelöscht, bevor die Anforderung an den Service übergeben wird. Gewöhnlich reichen diese Header für die meisten Anwendungen aus. Sie können einen eigenen Satz zulässiger HTTP-Header definieren, indem Sie die folgende Konfiguration in die Proxy-Konfigurationsdatei einfügen:
<proxy:policy url="*" acf="none">
    .
    .
    <proxy:headers>
       <proxy:header>User-Agent</proxy:header>
       <proxy:header&gtAccept*</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>

HTTP-Methoden filtern

Im vorherigen Beispiel ist der Ajax-Proxy so konfiguriert, dass nur GET-Anforderungen vom Client akzeptiert werden. Bei POST- und anderen HTTP-Methodenforderungen wird eine Fehlerbedingung an den Client zurückgegeben. Der Ajax-Proxy unterstützt GET-, POST-, PUT-, HEAD- und DELETE-Anforderungen. Sie müssen mindestens eine unterstützte HTTP-Methode angeben.

Unterstützung für SSL

Eine Reihe von Services können eine sichere Socket-Verbindung voraussetzen, die SSL verwendet. Als Webanwendung nutzt der Ajax-Proxy JavaTM Secure Socket Extension (JSSE) und wird vollständig vom Produkt unterstützt. Informationen zur Unterstützung von SSL-Zertifikaten finden Sie in der entsprechenden WebSphere®-Dokumentation.

Nicht signierte SSL-Zertifikate verwenden

Standardmäßig unterstützt der Ajax-Proxy keine nicht signierten Zertifikate. Sie empfangen eine SSL-Ausnahme mit der Nachricht Unrecognized SSL handshake. Wenn Sie nicht signierte SSL-Zertifikate für Test- oder Entwicklungszwecke verwenden müssen, können Sie die folgende Option in der Datei "proxy-config.xml" aktivieren:
    <proxy-meta-data>
        <proxy:name>unsigned_ssl_certificate_support</proxy:name>
        <proxy:value>true</proxy:value>
    </proxy-meta-data>

Wenn die Option "unsigned_ssl_certificate_support" aktiviert ist, akzeptiert der Ajax-Proxy jedes SSL-Zertifikat. In der Praxis ist diese Einstellung für die Entwicklung vorgesehen und wird in einer Produktionsumgebung gewöhnlich nicht verwendet.

Konfigurationsoptionen

Der Ajax-Proxy kann mit verschiedenen Parametern optimiert werden.

maxconnectionsperhost

Der Parameter "maxconnectionsperhost" ist ein globaler Wert, der die maximale Anzahl an Verbindungen angibt, die für eine Host/Port-Kombination aufrechterhalten werden. Der Standardwert für diesen Parameter ist 2. Sie können diesen Wert erhöhen, wenn Ihre Anwendung auf mehr als zwei ferne Sites zugreift, um Inhalt abzurufen.

<proxy:meta-data>
   <proxy:name>maxconnectionsperhost</proxy:name>
       <proxy:value>2</proxy:value>
</proxy:meta-data>

maxtotalconnections

Der Parameter maxtotalconnections gibt die maximale Anzahl an Verbindungen an, die insgesamt vom Proxy unterstützt werden. Der Standardwert ist 5. Der von Ihnen ausgewählte Wert muss hoch genug sein, um die Anzahl gleichzeitiger Verbindungsanforderungen zu unterstützen, die Sie empfangen. In der Praxis müssen Sie die Konfiguration des Webcontainers und die maximal vom Container unterstützte Anzahl gleichzeitiger Verbindungen berücksichtigen.

<proxy:meta-data>
   <proxy:name>maxtotalconnections</proxy:name>
   <proxy:value>5</proxy:value>
</proxy:meta-data>

socket-timeout

Das Socket-Zeitlimit definiert das Standard-Socket-Zeitlimit in Millisekunden für das Warten auf Daten, wenn eine Verbindung hergestellt wurde. Der Standardzeitlimitwert ist "0" und bedeutet, dass keine zeitliche Begrenzung besteht.

<proxy:meta-data>
   <proxy:name>socket-timeout</proxy:name>
   <proxy:value>5000</proxy:value>
</proxy:meta-data>

retries

Der Parameter "retries" definiert die Anzahl der Socket-Wiederholungen, die der Ajax-Proxy ausführen soll, bevor er die Verbindungsversuche einstellt. Die Standardeinstellung sieht vor, dass zwei Verbindungsversuche unternommen werden.

<proxy:meta-data>
   <proxy:name>retries</proxy:name>
   <proxy:value>3</proxy:value>
</proxy:meta-data>

connection-timeout

Das Verbindungszeitlimit definiert den Zeitraum vor dem Herstellen einer Verbindung in Millisekunden. Ist kein Versionswert angegeben, wird der Standardwert "60000" verwendet. Wird der Wert "0" verwendet, bedeutet das, dass kein Zeitlimit verwendet wird.

<proxy:meta-data>
   <proxy:name>connection-timeout</proxy:name>
   <proxy:value>3000</proxy:value>
</proxy:meta-data>

connection-pool-timeout

Der Parameter "connection-pool-time" definiert den Zeitraum vor dem Herstellen einer Verbindung in Millisekunden. Dies ist der Fall für alle nachfolgenden Anforderungen, sobald "maxtotalconnections" überschritten ist. Wird der Wert "0" verwendet, bedeutet das, dass kein Zeitlimit verwendet wird. 0 ist auch der Standardwert.

<proxy:meta-data>
   <proxy:name>connection-pool-timeout</proxy:name>
   <proxy:value>1000</proxy:value>
</proxy:meta-data>

forward-http-errors

Standardmäßig leitet der Ajax-Proxy nur HTTP-Statuscodes größer-gleich 200 und kleiner 400 weiter. Bei Statuscodes, die nicht in diesem Bereich liegen, wird automatisch die Fehlermeldung "404 Datei nicht gefunden" ausgegeben. Die einzige Ausnahme stellt der Code 401 (Nicht berechtigt) dar, der die Fehlernachricht "403" (Untersagt) auslöst, es sei denn, das Attribut "basic-auth-support" ist für diese spezielle Anforderung zugelassen.

Sie können HTTP-Codes größer-gleich 400 mit einer Nachricht weiterleiten, indem Sie den Parameter "forward-http-errors" in der Datei "proxy-config.xml" definieren.

<proxy:meta-data>
   <proxy:name>forward-http-errors</proxy:name>
   <proxy:value>true</proxy:value>
</proxy:meta-data>

Verbindung zu einem anderen Proxy herstellen

Der Ajax-Proxy kann so konfiguriert werden, dass er vor dem Zugriff auf das Netz eine Verbindung zu einem anderen Proxy herstellt. Die Verbindung zu einem Durchgriffs-Proxy kann erforderlich sein, wenn der Ajax-Proxy eine Firewall überwinden muss, um auf das Netz zuzugreifen. Der Ajax-Proxy unterstützt die einfache Basisauthentifizierung.

Das folgende Beispiel zeigt die Konfiguration einer fiktiven Proxy-Firewall. Der Parameter "passthru_host" ist ein erforderlicher Parameter. Andere Parameter wie "passthru_type", "passthru_username" und "passthru_password" sind optionale Parameter. Der Parameter "passthru_type" bezeichnet den verwendeten Authentifizierungstyp. Der Standardtyp ist BASIC. Alternativ können DIGEST und NTLM verwendet werden. NTLM erfordert die zusätzlichen Parameter "passthru_hostname" und "passthru_domain". Die Parameter "passthru_port" und "passthru_realm" sind auch optional. Wenn kein Parameter "passthru_port" angegeben ist, wird der Standardport 80 verwendet. Wenn der Parameter "passthru_realm" nicht angegeben ist, werden die Berechtigungsnachweise bei allen Authentifizierungsversuchen gesendet. Geben Sie den Parameter "passthru_realm" in einer Produktionsumgebung an, um zu verhindern, dass der Benutzername und das Kennwort für alle Authentifizierungsanforderungen präsentiert werden.

	<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>

Basisauthentifizierung aktivieren

Die Basisauthentifizierung kann mit dem Attribut basic-auth-support für eine Richtlinie in der Datei "proxy-config.xml" aktiviert werden. Beispiel:

<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>

Im Beispiel leitet der Ajax-Proxy die Informationen zu HTTP-Status und HTTP-Header an den Zielservice und den Zielclient weiter. Wenn "basic-auth-support" nicht definiert ist und der Ajax-Proxy eine Anforderung des Typs 401 empfängt, wird die Anforderung dem HTTP-Code "403" (Untersagt) zugeordnet.

Anmerkung: Gegenwärtig ist der Basisauthentifizierungsmechanismus die einzige Authentifizierungsmethode, die vom Proxy unterstützt wird.

IP-Adressen filtern

Mit der IP-Filterung des Ajax-Proxys können Sie IP-Adressen in Whitelists oder Blacklists aufführen, um Services, zu denen der Ajax-Proxy eine Verbindung herstellt, zu schützen. Die Blacklist enthält Service-IP-Adressen, zu denen keine Verbindung hergestellt werden darf, während die Whitelist IP-Adressen von Services enthält, zu denen der Ajax-Proxy eine Verbindung herstellen kann.

"proxy:ipfilter" definiert die zu filternden IP-Adressen. "proxy:allow" definiert die Whitelist für eine IP-Adresse oder einen Adressenbereich. "proxy:deny" definiert eine Blacklist für eine IP-Adresse oder einen IP-Adressenbereich.

Beispiel:
<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>

In diesem Beispiel führt der Ajax-Proxy folgende Filteroperationen durch: In diesem Fall würde der Proxy den Zugriff auf die IP-Adresse 9.6.2.5 oder 9.6.120.7 also nicht zulassen und mit der angegebenen Nachricht antworten:
CWXJX1000E: The specified target hosts IP-address is prohibited by rule.

Der Ajax-Proxy würde auf 9.6.1.5 oder 9.6.1.120 zugreifen, den Zugriff auf 9.6.1.4 jedoch verweigern.

Ein weiteres Beispiel beginnt damit, dass alle IP-Adressen auf eine schwarze Liste gesetzt werden und weitere IP-Bereiche hinzugefügt werden. In diesem Beispiel blockiert das folgende Codeelement alle IP-Adressen: *.*.*.*. IP-Adressen im Bereich von 98.137.80.1 bis 98.137.254 werden unterstützt.

<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>

Wenn Sie neue Filterregeln hinzufügen, können Sie sie auf verschiedene Weise kombinieren, der Ajax-Proxy verarbeitet sie jedoch immer in der Reihenfolge, in der sie definiert sind. Das bedeutet, dass die letzte Abgleichsregel immer wirksam ist, unabhängig von vorher definierten Zulassungs- und Verweigerungsregeln.


Nutzungsbedingungen | Feedback