[Sandbox] Add guide to document tunnel auth#31229
Draft
aron-cf wants to merge 4 commits into
Draft
Conversation
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Use getProcess() with a stable processId before startProcess() so the Worker fetch handler does not spawn a duplicate server on every request. Also wait for the port to be ready before creating the tunnel.
- Simplify env var bullet to CLOUDFLARE_API_TOKEN and link to Tunnels. - Reorder steps so Access auth (service token, application) is set up before the tunnel is created. - Drop the public-hostname interim paragraph and the editorialising ', which is rarely what an automation client wants' clause. - Reframe Application domain as: create the policy first, then add more domains to the same application.
Contributor
There was a problem hiding this comment.
5 style issues need addressing before merge.
LOW — protect-tunnels-with-access.mdx:55 — Use 'refer to' instead of 'see'.
LOW — protect-tunnels-with-access.mdx:81 — Use '(Optional)' instead of 'Optional:'.
LOW — protect-tunnels-with-access.mdx:112 — Use 'Refer to' instead of 'See'.
LOW — protect-tunnels-with-access.mdx:116 — Use 'Refer to' instead of 'See' and 'refer to' instead of 'see'.
MEDIUM — protect-tunnels-with-access.mdx — Wrap the multi-step procedure in <Steps> per the procedures style guide.
LOW — expose-services.mdx:18 — Use 'refer to' instead of 'see'.
| ``` | ||
| </TypeScriptExample> | ||
|
|
||
| `startProcess` resolves when the process starts, not when it is listening. In real code, wait for the port to be ready before calling `tunnels.get()` — see [Expose services](/sandbox/guides/expose-services/) for an example. |
Contributor
There was a problem hiding this comment.
Use 'refer to' instead of 'see':
Suggested change
| `startProcess` resolves when the process starts, not when it is listening. In real code, wait for the port to be ready before calling `tunnels.get()` — see [Expose services](/sandbox/guides/expose-services/) for an example. | |
| `startProcess` resolves when the process starts, not when it is listening. In real code, wait for the port to be ready before calling `tunnels.get()` — refer to [Expose services](/sandbox/guides/expose-services/) for an example. |
| - **Action**: `Service Auth` (see [policy actions](/cloudflare-one/access-controls/policies/#service-auth)). If you use `Allow` here, Access will redirect unauthenticated requests to an identity provider login page instead of returning an error, which is rarely what an automation client wants. | ||
| - **Include**: `Service Token` → the token created in step 2. | ||
|
|
||
| Optional: add a second `Allow` policy (for example, `Emails ending in @your-company.com`) so engineers can hit the URL in a browser via the identity provider flow for debugging. |
Contributor
There was a problem hiding this comment.
Use '(Optional)' instead of 'Optional:':
Suggested change
| Optional: add a second `Allow` policy (for example, `Emails ending in @your-company.com`) so engineers can hit the URL in a browser via the identity provider flow for debugging. | |
| (Optional) Add a second `Allow` policy (for example, `Emails ending in @your-company.com`) so engineers can hit the URL in a browser via the identity provider flow for debugging. |
|
|
||
| ### Single custom header | ||
|
|
||
| If the calling system can only set one header (for example, a SaaS integration that exposes a single `Authorization` field), configure the Access application to read both values from one header. See [Authenticate with a single header](/cloudflare-one/access-controls/service-credentials/service-tokens/#authenticate-with-a-single-header). |
Contributor
There was a problem hiding this comment.
Use 'Refer to' instead of 'See':
Suggested change
| If the calling system can only set one header (for example, a SaaS integration that exposes a single `Authorization` field), configure the Access application to read both values from one header. See [Authenticate with a single header](/cloudflare-one/access-controls/service-credentials/service-tokens/#authenticate-with-a-single-header). | |
| If the calling system can only set one header (for example, a SaaS integration that exposes a single `Authorization` field), configure the Access application to read both values from one header. Refer to [Authenticate with a single header](/cloudflare-one/access-controls/service-credentials/service-tokens/#authenticate-with-a-single-header). |
|
|
||
| ### Session cookie reuse | ||
|
|
||
| If your Access application has at least one `Allow` policy in addition to Service Auth (see step 3), Access returns a `CF_Authorization` cookie on the first authenticated request, and subsequent requests on the same hostname can send the cookie instead of the headers. Service-Auth-only applications do not honor the cookie — every request must carry the headers. See [Authorization cookie](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/) and [Subsequent requests](/cloudflare-one/access-controls/service-credentials/service-tokens/#subsequent-requests). |
Contributor
There was a problem hiding this comment.
Use 'Refer to' instead of 'See' and 'refer to' instead of 'see':
Suggested change
| If your Access application has at least one `Allow` policy in addition to Service Auth (see step 3), Access returns a `CF_Authorization` cookie on the first authenticated request, and subsequent requests on the same hostname can send the cookie instead of the headers. Service-Auth-only applications do not honor the cookie — every request must carry the headers. See [Authorization cookie](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/) and [Subsequent requests](/cloudflare-one/access-controls/service-credentials/service-tokens/#subsequent-requests). | |
| If your Access application has at least one `Allow` policy in addition to Service Auth (refer to step 3), Access returns a `CF_Authorization` cookie on the first authenticated request, and subsequent requests on the same hostname can send the cookie instead of the headers. Service-Auth-only applications do not honor the cookie — every request must carry the headers. Refer to [Authorization cookie](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/) and [Subsequent requests](/cloudflare-one/access-controls/service-credentials/service-tokens/#subsequent-requests). |
|
|
||
| :::note[Alternative: quick tunnels] | ||
| If you only need a public URL for development or a `.workers.dev` deployment, [`sandbox.tunnels`](/sandbox/api/tunnels/) returns a `*.trycloudflare.com` URL without DNS setup. For production, follow this guide and use `exposePort()` with a custom domain. | ||
| If you only need a public URL for development or a `.workers.dev` deployment, [`sandbox.tunnels`](/sandbox/api/tunnels/) returns a `*.trycloudflare.com` URL without DNS setup. For production, follow this guide and use `exposePort()` with a custom domain. To require authentication on a tunnel before requests reach the sandbox, see [Protect tunnels with Cloudflare Access](/sandbox/guides/protect-tunnels-with-access/). |
Contributor
There was a problem hiding this comment.
Use 'refer to' instead of 'see':
Suggested change
| If you only need a public URL for development or a `.workers.dev` deployment, [`sandbox.tunnels`](/sandbox/api/tunnels/) returns a `*.trycloudflare.com` URL without DNS setup. For production, follow this guide and use `exposePort()` with a custom domain. To require authentication on a tunnel before requests reach the sandbox, see [Protect tunnels with Cloudflare Access](/sandbox/guides/protect-tunnels-with-access/). | |
| If you only need a public URL for development or a `.workers.dev` deployment, [`sandbox.tunnels`](/sandbox/api/tunnels/) returns a `*.trycloudflare.com` URL without DNS setup. For production, follow this guide and use `exposePort()` with a custom domain. To require authentication on a tunnel before requests reach the sandbox, refer to [Protect tunnels with Cloudflare Access](/sandbox/guides/protect-tunnels-with-access/). |
Contributor
|
Posted a review on PR #31229 and applied labels What changed
Issues flagged
No build breakers, broken links, or invalid frontmatter were found. The |
- Add an APIRequest example showing how to PUT the Access application with an updated destinations array to add a hostname programmatically. - Wrap the verify and header-pair curl snippets in the CURL component to match the convention used elsewhere in the docs.
Contributor
Contributor
|
Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This adds a guide for authenticating Sandbox SDK tunnels. Or, more specifically configuring Cloudflare Access on Cloudflare Tunnel resources created by the Sandbox SDK.
Documentation checklist