Skip to content
Install

Protect an app

Protection puts a sign-in, a password, or HTTP basic authentication in front of an app, so a staging site or an internal tool is not open to the whole internet. You add it to a domain, and requests to that domain go through Orchard’s proxy before they reach the app. Your app needs no changes.

TypeWho can reach the app
NoneAnyone.
PasswordVisitors who enter the shared password.
Username and passwordClients that send the correct HTTP basic authentication credentials.
Project membersPeople who sign in to Orchard and have access to the project: its members, the owners and admins of its organization, and superadmins.

A generated URL with the reach Private link starts with Project members. A generated URL with the reach Public link, and a custom domain, start with None.

  1. Open the app.
  2. Go to Network.
  3. In Domains, select Add protection on the domain. If the domain already has protection, select its badge.
  4. In Protection type, select a type.
  5. Enter the password, or the username and password, if the type needs them. A password must have at least 8 characters.
  6. Select Save.

To make a protected URL public, select None, then select Save.

Webhook receivers, health endpoints, and OAuth callbacks must stay reachable. If they sit behind protection, the sender receives a sign-in page and the delivery fails. Add these routes as public paths before you point a provider at the app.

  1. In the Protection dialog, find Public paths.
  2. Enter one path per line. /api also opens /api/v1. It does not open /apikeys.
  3. Select Save.

Each path on a domain has its own protection, so you can protect / and leave /docs public. Each path keeps its own sign-in, and the Protection dialog lists the paths on the domain that are still public.

A path you add to a domain that already has protection starts with the same protection. To make it public, open its Protection dialog and select None.

Orchard never treats a path as public when it is ambiguous: any path containing ;, a backslash, //, a . or .. segment, or a percent-encoded ., /, \, ; or % falls through to the normal sign-in. This holds whatever your ingress controller does with those paths. Orchard recommends that you confirm it against your own HAProxy or Traefik. With /public as a public path, each of these requests must return the sign-in redirect, or 401 for basic authentication, and never your app:

for p in '/public/..;/private' '/public/%2e%2e/private' '/public/..%2fprivate' \
'/public%2f..%2fprivate' '/public//..//private' '/public\..\private' \
'/public/%252e%252e/private' '/public/./../private' '/public/..'; do
curl -s -o /dev/null -w "%{http_code} $p\n" --path-as-is "https://app.example.com$p"
done
curl -s -o /dev/null -w "%{http_code} /public/ok\n" https://app.example.com/public/ok

Only the last request reaches the app. Run the test again after you change the ingress controller or its path-handling settings.

Scripts and CI can skip sign-in with a bypass header. After you save protection, reopen the Protection dialog to copy the header from Bypass header.

x-orchard-protection-bypass: <secret>

Orchard removes this header before the request reaches your app.

Password and Username and password work on every cluster. For Username and password, the server checks whether the cluster has the cilium.io API group and whether it may create ciliumenvoyconfigs:

  • With Cilium, Orchard adds an Envoy basic authentication filter in front of the Service. The password covers every path to that Service.
  • Without Cilium, Orchard’s protection proxy checks the credentials. The proxy protects the HTTP route, so a pod that can reach the app directly is not affected. To limit that, add a NetworkPolicy.

To force the choice, set CILIUM_ENABLED to true or false on the server.

To let people choose Project members on their own domains, set protection.orchardLogin: true in the chart. It needs FRONTEND_URL to be reachable from where the app is served. The value only controls whether people can choose this type. Turning it off does not remove protection from hosts that already use it, and generated URLs can still start with Project members.

Protection covers HTTP. Raw TCP and UDP ports do not pass through the proxy, so protection does not apply to them.