SOP 004: Configure Traffic Policy (Authentication) ​
Fresh| Field | Value |
|---|---|
| SOP ID | SOP-004 |
| Version | 1.0 |
| Status | Active |
| Last Updated | 2026-02-13 |
Purpose ​
Add authentication and security policies to your ngrok endpoints using Traffic Policy.
Prerequisites ​
Procedure ​
Option A: Google OAuth via Config File ​
- Open the ngrok config file:
bash
ngrok config edit- Add the following below your authtoken:
yaml
endpoints:
- name: secure-app
url: YOUR_DOMAIN
traffic_policy:
on_http_request:
- actions:
- type: oauth
config:
provider: google
upstream:
url: 8080
protocol: http1- Start the endpoint by name:
bash
ngrok start secure-appVisitors must log in with a Google account before accessing your app.
Option B: Basic Auth via Policy File ​
- Create
traffic-policy.yml:
yaml
on_http_request:
- actions:
- type: basic-auth
config:
credentials:
- admin:secretpassword
- user2:anotherpassword- Start with the policy file:
bash
ngrok http 80 --traffic-policy-file traffic-policy.ymlAuthtoken ACLs ​
Restrict what an agent can do at the token level:
| ACL Pattern | Description |
|---|---|
bind:foo.ngrok.app | Only create endpoint on specific domain |
bind:*.example.com | Only subdomains of example.com |
bind:foo=bar | Labeled endpoint with specific label |
bind:app=* | Labeled endpoints with wildcard |
bind:* | Listen on all endpoints (default) |
Configure ACLs when provisioning authtokens at dashboard.ngrok.com/authtokens.
Verification Checklist ​
- [ ] Config file syntax is valid (
ngrok config check) - [ ] Endpoint starts without errors
- [ ] Authentication prompt appears when accessing the URL
- [ ] Valid credentials grant access
- [ ] Invalid credentials are rejected
Troubleshooting ​
| Issue | Solution |
|---|---|
| YAML syntax error | Use ngrok config check to validate |
| OAuth not redirecting | Ensure traffic_policy indentation is correct |
| Basic auth not working | Check credentials format is user:password |
| 403 Forbidden | Check ACL permissions on the authtoken |