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.
Protection types
Section titled “Protection types”| Type | Who can reach the app |
|---|---|
| None | Anyone. |
| Password | Visitors who enter the shared password. |
| Username and password | Clients that send the correct HTTP basic authentication credentials. |
| Project members | People 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.
Set protection
Section titled “Set protection”- Open the app.
- Go to Network.
- In Domains, select Add protection on the domain. If the domain already has protection, select its badge.
- In Protection type, select a type.
- Enter the password, or the username and password, if the type needs them. A password must have at least 8 characters.
- Select Save.
orchard domain protection set <domain-id> --mode orchardThe --mode flag accepts none, password, or orchard. For password, add --password. To set Username and password, use the dashboard.
To make a protected URL public, select None, then select Save.
Exclude public paths
Section titled “Exclude public paths”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.
- In the Protection dialog, find Public paths.
- Enter one path per line.
/apialso opens/api/v1. It does not open/apikeys. - Select Save.
Protect a domain with several paths
Section titled “Protect a domain with several paths”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"donecurl -s -o /dev/null -w "%{http_code} /public/ok\n" https://app.example.com/public/okOnly the last request reaches the app. Run the test again after you change the ingress controller or its path-handling settings.
Skip protection from scripts
Section titled “Skip protection from scripts”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.
How operators enable each type
Section titled “How operators enable each type”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.
Limitations
Section titled “Limitations”Protection covers HTTP. Raw TCP and UDP ports do not pass through the proxy, so protection does not apply to them.
Related resources
Section titled “Related resources”- Manage domains and HTTPS - Add the custom domains that protection applies to.
- Turn on bot protection - Add a Cloudflare Turnstile challenge to sign-in pages and password-protected apps.