Legacy --oauth flags moved to Traffic Policy: preserving allowlist semantics during migration

Short answer

Place the OAuth action as the first terminating rule in your Traffic Policy. Rules are evaluated in order, and the first matching terminating action wins, so anything placed after the OAuth rule only ever sees requests that already passed authentication and the email/domain allowlist. That ordering is what reproduces the legacy --oauth behavior, where unauthenticated traffic never reached the upstream app.

The mapping, with caveats

The legacy flags translate conceptually as follows:

• --oauth <provider> → an oauth action with the provider field set
• --oauth-allow-emails → the allowed-emails list on that same action
• --oauth-allow-domains → the allowed-domains list on that same action

Where the legacy flags had fixed, implicit semantics, the Traffic Policy makes the order explicit — which is both the power and the risk. If you previously combined OAuth with other flags (e.g., an IP restriction), you must now decide deliberately whether that rule runs before OAuth (blocking disallowed IPs before the login challenge) or after. Putting a terminating rule before the OAuth action changes effective behavior versus the legacy flags.

Version boundary: Traffic Policies require ngrok agent v3. On agents older than 3.0, the policy configuration is unavailable and the legacy flags must be kept (or the agent upgraded). The exact per-flag coverage across early 3.x releases is something I cannot confirm without checking the current migration guide — treat that as the one detail worth verifying against the docs for your specific agent version before cutover.

Minimal verification

ngrok version   # confirm 3.x before relying on Traffic Policy

Then test the policy directly: an unauthenticated curl -i against the tunnel hostname should return a redirect to the provider login (or a 401/403), and your upstream app should log nothing. A request from a non-allowlisted account, after authenticating, should be denied at the edge as well. If either request reaches the app, the OAuth rule is not first or not terminating.

Should the app re-check authorization?

For your stated goal — gating an integration-test app without embedding OAuth credentials — edge enforcement is sufficient. The app never sees unauthenticated requests, so duplicating the check adds complexity without adding security.

The exception is when the app needs to know who the user is or enforce finer-grained rules than an email/domain list. In that case, don't redo the OAuth handshake; consume the identity headers ngrok injects into authenticated requests (user email, access token) and authorize from those. Treat those headers as trustworthy only because the edge strips spoofed copies — another reason the OAuth rule must come first and terminate.

Bottom line

OAuth action first, terminating; any pre-auth filters (like IP restrictions) consciously placed before it; app-level checks only for identity-aware logic, using ngrok's injected headers rather than a second OAuth flow. Confirm your agent is v3 and validate with one unauthenticated request before declaring the migration done.