client-proxy.md

Layman behind client proxy

It is common use case that Layman is queried not directly, but using client proxy. The client proxy reads session cookie from the request, substitutes the cookie for authentication header, sends the request to the Layman, and returns result to user agent. This approach is used in Layman Test Client and HSLayers client, and it is mentioned also in OAuth2 documentation.

The client proxy used with Layman always adds prefix to URL path of each request. Without client proxy, URL path of request to REST API looks like /rest/path/to/endpoint. When client proxy is used, the URL path changes to /<client-proxy-prefix>/rest/path/to/endpoint.

Imagine request e.g. to GET Publications sent through client proxy, e.g. /layman-client-proxy. URL path of such request sent by user agent will be /layman-client-proxy/rest/publications and the response will look like

[
  {
    "workspace": "my_workspace",
    "publication_type": "layer",
    "name": "my_layer",
    "url": "https://mylaymandomain.com/rest/publications",
    ...
  },
  ...
]

By default, Layman will not adjust URLs in its response to contain also URL path prefix of the client proxy (/layman-proxy in above example). If you prefer to adjust URLs in Layman responses to contain also URL path prefix of the client proxy (or even host and protocol), you need to send also X-Forwarded HTTP headers with the request.

X-Forwarded HTTP headers

Layman supports three optional X-Forwarded HTTP headers, whose values will be used in some URLs in Layman responses:

• X-Forwarded-Proto: The value will be used as protocol in some URLs, and it is required to be http or https.
• X-Forwarded-Host: The value will be used as host in some URLs, and it is required to match regular expression ^(?=.{1,253}(?:\:|$))(?:(?!-)[a-z0-9-_]{1,63}(?<!-)(?:\.|(?:\:[0-9]{1,5})?$))+$.
• X-Forwarded-Prefix: The value will be used as prefix in some URL paths, and it is required to match regular expression ^(?:/[a-z0-9_-]+)*$.

For example, consider there is layman running at https://enjoychallenge.tech/rest and client proxy running at https://laymanproxy.com/layman-client-proxy. If you send request to your Layman proxy https://laymanproxy.com/layman-client-proxy/rest/publications with HTTP headers

X-Forwarded-Host=laymanproxy.com
X-Forwarded-Prefix=/layman-client-proxy

then response will change to

[
  {
    "workspace": "my_workspace",
    "publication_type": "layer",
    "name": "my_layer",
    "url": "https://laymanproxy.com/layman-client-proxy/rest/publications",
    ...
  },
  ...
]

Currently, value of X-Forwarded headers affects following URLs:

• GET Publications, GET Layers, GET Maps, GET Workspace Layers and GET Workspace Maps
  • url key
• POST Workspace Layers and POST Workspace Maps
  • url key
• GET Workspace Layer and PATCH Workspace Layer
  • url key
  • wms.url key
  • wfs.url key
  • style.url key
  • thumbnail.url key
  • metadata.comparison_url key
• GET Workspace Map and PATCH Workspace Map
  • url key
  • file.url key
  • thumbnail.url key
  • metadata.comparison_url key
• GET Workspace Map File
  • some URLs of each internal layer:
    • url key
    • protocol.url key
    • each legends key if its HTTP protocol and netloc corresponds with url or protocol.url
    • style key if its HTTP protocol and netloc corresponds with url or protocol.url
  • NOTE: If client proxy protocol, host, or URL path prefix was used in URLs in uploaded file, then such values are also replaced with values according to X-Forwarded header values. Default values are used for requests without X-Forwarded headers (protocol is the one from LAYMAN_CLIENT_PUBLIC_URL, host is LAYMAN_PROXY_SERVER_NAME, and path prefix is empty string).
• DELETE Workspace Layers, DELETE Workspace Maps, DELETE Workspace Layer and DELETE Workspace Map
  • url key
• OGC endpoints
  • Headers X-Forwarded-For, X-Forwarded-Path, Forwarded and Host are ignored
  • WMS endpoints
    • all requests URLs
    • all legend URLs
  • WFS endpoints
    • all operations URLs

Values of X-Forwarded headers does not affect responses of GET Workspace Layer Metadata Comparison and GET Workspace Map Metadata Comparison intentionally, in order to keep URLs in canonical form.