Skip to main content
Skip table of contents

Reverse proxy in HCMS CSK

[]

Warning: The reverse proxy is NOT part of the HCMS Client Starter Kit, because this is usually part of the infrastructure, especially in a cloud environment. See popular implementations below.

Why reverse proxy

Reverse proxy is often confusingly called "load balancer". In the aforementioned setup, the reverse proxy performs several important functions, including:

  • TLS/SSL termination: HTTPS protocol is used for clients to connect to the Server via proxy
    • This means that there is only one place which needs to be configured with correct HTTPS certificate and other HTTPS settings (allowed ciphers, for example).
  • One domain for all JavaScript code, all cookies and all requests, regardless of which application the request go to.
    • This means that there is no need for CORS headers and all cookies work with SameSite=Strict flag (which is the default in all up-to-date browsers, see Mozilla documentation).
  • Load balancing and fault tolerance
    • Each service can be actually run multiple times to spread load and (even more importantly) make sure that the application works even if one process fails. For this reason, 2 instances of each service is a recommended minimum for production use.

How reverse proxy handles different requiests

The reverse proxy supports "path-based routing": requests are forwarded to one of the backends depending on the path part of the request URL (see above). It routes HTTP requests by a few simple rules:

  • All paths starting with /hcms/ are passed to the HCMS service.
    • This is basically just a REST API that provides access to the data from censhare Server.
  • All other requests are passed to the HCMS Client service ("middleware").
    • This middleware has its own REST API, but more importantly it provides base HTML pages and all the javascript code that makes the actual application.

Types of HTTP communication

There are four types of HTTP requests and each of them must be allowed by the network infrastructure.

  • A) Web Browser to HCMS: REST API used to obtain data from censhare server, usually in a structured form (JSON) or media (images, videos).
    • Various HTTP methods are supported, including PUT, POST and DELETE.
    • Some very limited data are available even without authorization. Basically just a public logo on the login page.
    • Authorized by a cookie named access_token which contains a valid JWT token.
      • The token is actually created by the middleware and frontend then sets the cookie via special HCMS endpoint /hcms/v1.0/auth/cookie/set?access_token=
      • The cookie name is actually not hardcoded in the HCMS and must be configured. This configuration step is part of both guides: aws and standalone
        authorization create --jwt sampleportal1 --cookie access_token --cookie-http-only true --secret <secret>
      • Token has a limited validity time and frontend code makes sure that it obtains and sets a new one before the old one expires. Failure to do so is interpreted as "logout".
    • Warning: In current browsers, requests made from javascript code are allowed only if the request origin (ie the javascript file) is from the very same domain!
      • This behavior can be overridden by a special configuration option that provides CORS headers. The option is an attribute called allowedOrigins on the api element in the configuration XML. This option is not available in the commandline tool.
    • Warning: In current browsers, the cookie is actually sent with the request only if the request origin (ie the javascript and/or html) is from the very same domain!
      • This behavior can be overridden by a special flag SameSite=None set on the cookie. See lower how to do that when setting up dev environment.
  • B) Web Browser to the HCMS Client "middleware": serves the web application itself (HTML, JavaScript, CSS) and also provides some REST API (login, registration, etc).
    • Most of the web application requests just serve plain files and don't need any authorization (html, javascript, css, icons, etc).
    • Some endpoints are REST
    • Authorized by a cookie named access_token which contains a valid JWT token.
      • Exactly the same cookie as for the HCMS. As long as only one domain is used, the cookie can be even shared.
      • It sets its own cookie in the login endpoint.
      • The same caveats apply in this case too. If necessary, both CORS and SameSite can be reconfigured by setting environment variable DISABLE_BROWSER_SECURITY=true
  • C) Middleware to HCMS: principally the same as Web Browser to HCMS.
    • Authorized by a Authorization: Bearer header instead of cookie.
    • Uses exactly the same endpoints as the A (browser-hcms) requests, including the real public application domain) is used. This ensures that any generated links (which are quite common in the REST API) are usable in both contexts.
      • This means that unless some special configuration is used, the external interface of the Reverse Proxy / Load Balancer is used. This is actually desired if the HCMS is a cluster of several instances.
      • Warning: In some cloud infrastructure setups, internal network is strictly separated from the external one (either by routing or by a firewall), making external interface of the Reverse Proxy inaccessible. This usually manifests as "timeout" or "no route to host" errors.
        • This is quite common pitfall on AWS.
        • Aside the obvious solution (reconfiguring network routing and/or firewall), this can be also solved by using an internal balancer and DNS resolver override. Such a setup is quite advanced, though.
  • D) Webhooks: special endpoints provided by the middleware to validate data change requests from the frontend.
    • These webhooks are needed because data change requests (including media upload and personal data change) are invoked directly from the frontend and it's quite easy to modify the data in browser. HCMS passed all data from such a request and receives reply saying if that request is a correct, allowed one.
    • No special authorization is necessary.
    • Warning: the validation endpoint also uses the real public domain, so the same issue (unreachable network) as in C is possible. Solution is also the same.

Reverse proxy popular implementations

Some of the most common implementations are:

In the end, the correct solution depends on the already existing infrastructure, and HCMS Client is strictly agnostic and does not prescribe using any particular one. The most important feature is that the proxy acts in the HTTP layer.

Warning: If you don't have any kind of balancer / reverse proxy in your infrastructure and lack knowledge/experience to set up one, implementing a full HCMS Client project without direct involvement of censhare might not be a good choice for you.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close