A service proxy can be deployed on front of a Web server, Web Service or a REST resource. It conceals the server and offers the same interface as the target server to its clients.

Can be used in

router

Syntax

<serviceProxy name="string"
  port="integer"
  method="[*,POST,PUT,GET,DELETE,TRACE,OPTIONS]"
  host="[string,*]"
  blockRequest="[true,false]"
  blockResponse="[true,false]"
  ip="[ip]">
  <path />?
  <ssl />?
  <request>
    [interceptors]*
  </request>
    [interceptors]*
  <response>
	[interceptors]*
  </response>
  <localhost />?
  <target />?
</serviceProxy>

<serviceProxy name="string"
  port="integer"
  method="[*,POST,PUT,GET,DELETE,TRACE,OPTIONS]"
  host="[string,*]"
  blockRequest="[true,false]"
  blockResponse="[true,false]"
  ip="[ip]">
  <path />?
  <ssl />?
  <request>
    [interceptors]*
  </request>
    [interceptors]*
  <response>
	[interceptors]*
  </response>
  <localhost />?
  <target />?
</serviceProxy>

Sample

<serviceProxy port="80">
  <response>
    <transform xslt="customer2person.xsl" />
  </response>
  <target host="www.thomas-bayer.com" port="80" />
</serviceProxy>

<serviceProxy port="80">
  <response>
    <transform xslt="customer2person.xsl" />
  </response>
  <target host="www.thomas-bayer.com" port="80" />
</serviceProxy>

Attributes

Name	Required	Default	Description	Examples
host	false	not set	A space separated list of hostnames. If set, Membrane will only consider this rule, if the "Host" header of incoming HTTP requests matches one of the hostnames. The asterisk '*' can be used for basic globbing (to match any number, including zero, characters).	predic8.de *.predic8.de
ip	false	not set	If present, binds the port only on the specified IP. Useful for hosts with multiple IP addresses.	127.0.0.1
method	false	*	If set, Membrane will only consider this rule, if the method (GET, PUT, POST, DELETE, etc.) header of incoming HTTP requests matches. The asterisk '*' matches any method.	GET
name	false	By default, a name will be automatically generated from the target host, port, etc.	The name as shown in the Admin Console.	-
port	false	80	The port Membrane listens on for incoming connections.	8080

Child Elements

Element	Description	Cardinality
abort	Plugins are usually applied to requests and responses. In case of errors, the flow returns and handleAbort() is called on plugins going back the chain. By nesting plugins into an you can limit their application to abort flows only. On plugins nested in handleResponse() is called not handleAbort() in order to allow normal processing.	0..*
accessControl	Applies access control rules to incoming requests based on the peer address.	0..*
accessLog	Writes exchange metrics into a Log4j appender	0..*
acmeHttpChallenge	See the documentation of the `<acme />` element for usage details.	0..*
adminApi	Provides a JSON-based Admin API (health, apis, calls, exchange details, suggestions, ws) backed by the ExchangeStore.	0..*
adminConsole	Displays up-to-date statistics, recent exchanges and, by default, allows live modification of Membrane's configuration.	0..*
analyser	Analyses XML bodies and stores extracted root element + SOAP operation metadata in Exchange properties (request/response).	0..*
apiDocs	Publishes an overview of all OpenAPI-enabled proxies and serves Swagger UI under /api-docs/ui/*.	0..*
apiKey	Validates API keys extracted from incoming requests and looks up permissions (scopes) via configured key stores. Extractors can read the keys from HTTP headers, query parameters and may other message part. When validation succeeds, the interceptor adds an `ApiKeySecurityScheme` with the resolved scopes to the `Exchange`. Scopes can be checked in later plugins using the SpEL function `hasScope("...")`. On missing or invalid keys, a Problem Details response is generated (401 for missing, 403 for invalid) unless `required="false"` is set.	0..*
balancer	Performs load-balancing between several nodes. Nodes sharing session state may be bundled into a cluster. May only be used as interceptor in a serviceProxy or api.	0..*
basicAuthentication	Blocks requests which do not have the correct RFC 1945 basic authentication credentials (HTTP header "Authentication: Basic ....").	0..*
beautifier	Beautifies request and response bodies. Supported are the Formats: JSON, JSON5, XML, TEXT	0..*
cache	Don't use, this does NOT implement valid HTTP caching.	0..*
call	Calls an external endpoint	0..*
chain	A Chain groups multiple interceptors into reusable components, reducing redundancy in API configurations.	0..*
choose	Enables conditional branching. Evaluates {@link Case} elements in order and runs the first matching flow. If no case matches, an optional trailing {@link Otherwise} is executed. The "otherwise" element must be the last element of the list.	0..*
clamav	Delegates virus checks to an external Virus Scanner.	0..*
clusterNotification	Receives control messages to dynamically modify the configuration of a {@link LoadBalancingInterceptor}.	0..*
cors	Cross-Origin Resource Sharing (CORS) plugin that enables secure cross-origin HTTP requests.	0..*
counter	Returns a simple HTML page and counts how often it was requested (increments per request).	0..*
destination	Sets the destination URL for the exchange. This overrides any previous destination.	0..*
dispatching	This interceptor adds the destination specified in the target element to the list of destinations of the exchange object. It must be placed into the transport to make Service Proxies Work properly. It has to be placed after the ruleMatching interceptor. The ruleMatching interceptor looks up a service proxy for an incoming request and places it into the exchange object. The dispatching interceptor needs the service proxy to get information about the target.	0..*
echo	Returns the flow of plugins and copies the content of the request into a new response. The response has a status code of 200. Useful for testing.	0..*
exchangeStore	Adds the current state of HTTP requests and responses to an "exchange store".	0..*
flowInitiator	Initiates an OAuth2 login flow by redirecting to oauth2 (FlowContext).	0..*
for	Iterates over a collection extracted from the `Exchange` and applies its nested interceptors for each element. The current element is exposed in the exchange under the property key `"it"`.	0..*
formValidation	Using the formValidation interceptor you can validate the input of HTML forms.	0..*
global	The global chain applies plugins to all endpoints, enabling centralized features such as global user authentication, logging, and other cross-cutting concerns.	0..*
graphQLProtection	Check GraphQL-over-HTTP requests, enforcing several limits and/or restrictions. This effectively helps to reduce the attack surface.	0..*
greaser	Randomly applies greasing strategies to request/response messages (rate 0..1) to stress-test parsers (e.g., JSON/XML).	0..*
groovy	Executes a Groovy script. The script can access and manipulate data from the request and response. Use this or the Javascript plugin to extend the functions of Membrane by scripting. See: example/groovy for working samples	0..*
headerFilter	Removes message headers matching a list of patterns. The first matching child element will be acted upon by the filter.	0..*
httpClient	The httpClient sends the request of an exchange to a Web Server using the HTTP protocol. Usually it will be globally used inside the transport. However, it is also possible to use it inside a proxy to give the proxy an individual configuration for its outgoing HTTP connection that is different from the global configuration in the transport.	0..*
idempotency	Prevents duplicate request processing based on a dynamic idempotency key.	0..*
if	if allows conditional execution of nested interceptors.	0..*
index	The index feature lists available proxys at a simple Web page. To use this feature just add a serviceProxy containing the index element. Of course you can protect the service proxy by using SSL or Username and Password.	0..*
interceptor	Wraps an interceptor provided as Spring bean (refid) or as nested interceptor (child element) and delegates all calls.	0..*
javascript	Executes a Javascript. The script can access and manipulate data from the request and response. Use this or the Groovy plugin to extend the functions of Membrane by scripting. See the samples in examples/javascript.	0..*
json2Xml	Converts JSON message bodies into XML. The converter wraps the JSON document into a root element. The name of the root element is configurable. If unset, JSON objects default to "root" and JSON arrays default to "array". This interceptor reads the JSON body, converts it into XML and updates the message body and Content-Type header. The resulting XML is always UTF-8 encoded and starts with an XML prolog.	0..*
jsonProtection	Enforces restrictions on JSON request bodies to protect against JSON-based attacks and resource exhaustion. Validates against configurable limits to prevent attacks such as:	0..*
jwtAuth	Validates a JWT on requests (signature via JWKS, required exp/sub) and exposes claims in exchange properties ("jwt").	0..*
kubernetesValidation	Kubernetes Integration is still experimental.	0..*
limit	Limits the maximum length of a HTTP message body.	0..*
log	Logs request and response messages. The messages will appear either on the console or in a log file depending on the log configuration.	0..*
login	The login interceptor can be used to restrict and secure end user access to an arbitrary web application.	0..*
ntlm	Performs NTLM authentication when the upstream responds with WWW-Authenticate: NTLM by replaying the request with NTLM headers.	0..*
oauth2authserver	OAuth2/OIDC authorization server endpoints (auth/token/userinfo/revocation/.well-known) with session + consent/login UI.	0..*
oauth2Resource2	Allows only authorized HTTP requests to pass through. Unauthorized requests get a redirect to the authorization server as response. This interceptor does Session Management and can thereby translate Session IDs to OAuth2/OIDC Access Tokens. Beyond regular OIDC-compliant authorization servers, this interceptor can also be used with Azure B2C.	0..*
openapiPublisher	The openapiPublisher serves OpenAPI documents	0..*
openapiValidator	Validator for OpenAPI documents	0..*
openTelemetry	Creates an OpenTelemetry span for each HTTP request passing through. Sends the tracing data to the speficied OpenTelemetry collector. See also examples/monitoring-tracing/opentelemetry for a demo, including screenshots.	0..*
paddingHeader	Adds an X-Padding header with random characters to pad message size (request/response).	0..*
path	Explanation:	0..1
prometheus	Exposes some of Membrane's internal metrics in the Prometheus format. See also examples/monitoring-tracing/prometheus for a demo, including a screenshot.	0..*
rateLimiter	The rateLimiter plugin limits the number of requests of a client in a period of time. As a default the client requests are grouped by client-Ip address and then counted. There are lots of possibilities to group the requests using the keyExpression. The requests can even be counted from different clients together.	0..*
regExReplacer	Runs a regular-expression-replacement on either the message body (default) or all header values.	0..*
replace	Replaces a JSON value at the configured JSONPath with a static string.	0..*
request	Interceptors are usually applied to requests and responses. By nesting interceptors into a Element you can limit their application to requests only.	0..*
response	Interceptors are usually applied to requests and responses. By nesting interceptors into a plugin you can limit their application to responses only.	0..*
rest2Soap	Converts REST requests into SOAP messages.	0..*
return	Terminates the exchange flow. The returned response is determined in the following order:	0..*
reverseProxying	Rewrites the scheme, hostname and port in the "Location" header in HTTP responses, as well as in the "Destination" header in HTTP requests. The rewriting reflects the different schemes, hostnames and ports used to access Membrane vs. the target HTTP server.	0..*
rewriter	Rewrites or redirects the path of incoming requests based on a mapping.	0..*
ruleMatching	Selects and assigns the matching proxy rule for incoming requests; optionally adds/extends X-Forwarded-* headers.	0..*
setBody	sets the content of the HTTP message body to the specified value. The value can be a static string, or it can be dynamically generated by an expression. Different languages such as SpEL, Groovy, XMLPath or JsonPath are supported. setBody does not support conditional processing or loops. When you need these features, resort to the template plugin instead.	0..*
setCookies	Adds one or more Set-Cookie headers to the HTTP response for session handling, user preferences, or tracking purposes. Supports computing expiry, setting standard attributes like Domain and Path, and building a compliant cookie string. Useful for enriching responses with configurable cookies directly at gateway level without backend involvement.	0..*
setHeader	Set HTTP header on the current message.	0..*
shadowing	Clones incoming requests and sends them asynchronously to one or more shadow targets (main exchange continues unchanged).	0..*
shutdown	Shutdown interceptor.	0..*
soap2Rest	Converts SOAP messages into REST requests.	0..*
soapBody	Renders a SOAP body for legacy integration	0..*
soapStackTraceFilter	The soapStackTraceFilter removes SOAP stack traces from message bodies.	0..*
ssl	Configures inbound or outbound SSL connections.	0..1
static	Sets the message body to static content. The body is either provided inline as text content or loaded from a file/URL. If pretty is enabled, the formatted result is cached and reused until the interceptor is (re)initialized.	0..*
statisticsCSV	Writes statistics (time, status code, hostname, URI, etc.) about exchanges passing through into a CSV file (one line per exchange).	0..*
statisticsJDBC	Writes statistics (time, status code, hostname, URI, etc.) about exchanges passing through into a database (one row per exchange).	0..*
statisticsProvider	Serves request statistics as JSON from a JDBC-backed store. Supports paging (offset/max) and sorting (sort/order) via query parameters.	0..*
target	The destination where the service proxy will send messages to. Use the target element if you want to send the messages to a target. Supports dynamic destinations through expressions.	0..1
tcp	Allow HTTP protocol upgrades to the TCP protocol. After the upgrade, the connection's data packets are simply forwarded and not inspected.	0..*
template	Renders the body content of a message from a template. The template can produce plain text, Json or XML. Variables in the template are substituted with values from the body, header, query parameters, etc. If the extension of a referenced template file is .xml it will use XMLTemplateEngine otherwise StreamingTemplateEngine. Have a look at the samples in examples/templating. When the `contentType` is a JSON variant (e.g., `application/json`), the engine automatically escapes all inserted values. For example, in the JSON templating example, executing `curl "localhost:2000/?answer=20"` returns `{ "answer" : "20" }`. The quotes surrounding the value 20 are added by the auto-escaping mechanism to ensure the output remains a valid string. This feature significantly mitigates security risks by preventing inadvertent JSON injection attacks.	0..*
throttle	The throttle feature can slow down traffic to thwart denial of service attacks.	0..*
time	Measures the end-to-end processing time of the child interceptor flow and logs an aligned summary. If an OpenTelemetry parent Span is present on the {@link Exchange}, a child sub-span is created around the measured section so timing data is exported to OTel as well.	0..*
transform	The transform feature applies an XSLT transformation to the content in the body of a message. After the transformation the body content is replaced with the result of the transformation.	0..*
userFeature	Handles features that are user-configured in proxies.xml .	0..*
webServer	Serves static files based on the request's path.	0..*
webServiceExplorer	Serves an HTML “web service explorer”.	0..*
webSocket	Allow HTTP protocol upgrades to the WebSocket protocol. After the upgrade, the connection's data packets are simply forwarded and not inspected.	0..*
wsdlPublisher	The wsdlPublisher serves WSDL files (and attached XML Schema Documents), if your backend service does not already do so.	0..*
wsdlRewriter	The wsdlRewriter rewrites endpoint addresses of services and XML Schema locations in WSDL documents.	0..*
xml2Json	Converts an XML message body to JSON.	0..*
xmlContentFilter	The xmlContentFilter removes certain XML elements from message bodies. The elements are described using an XPath expression.	0..*
xmlProtection	Prohibits XML documents to be passed through that look like XML attacks on older parsers. Too many attributes, too long element names are such indications. DTD definitions will simply be removed.	0..*