OAuth Traffic Policy on Endpoints
Sometimes you don't want everyone to be able to access the app at your Endpoints.
This guide will walk you through protecting your apps with OAuth authentication via Traffic Policy. All you need is the ngrok agent CLI.
1. Pick your provider
Decide which OAuth identity provider you want to use. If you don't have an OAuth application configured yet, you can use any of the following providers out of the box:
- GitHub
- GitLab
- Microsoft
- Twitch
This guide will use Google OAuth.
If you use any of the above providers without configuring your own OAuth application, your endpoint will use ngrok's managed OAuth application. This means you won't be able to customize the provider's authentication behavior.
2. Create a traffic policy file
The following is an example Traffic Policy file that executes the 'oauth' traffic policy action on every request to your endpoint.
Create this traffic policy file in the same directory where you run your ngrok agent, or add its contents to your ngrok.yml agent config file as shown below.
Loading…
3. Restart your endpoint with the policy attached
If you saved your Traffic Policy in a local file like oauth.yml, add the --traffic-policy-file flag to your ngrok command when starting your agent as shown in the following example.
Loading…
4. Verify in a browser
Open your app's URL (for example https://myapp.ngrok.app).
You should be immediately redirected to the Google sign-in page, and after authenticating you'll land back on your app.
Explore more and fine-tune with Traffic Policy
Traffic Policy is a composable CEL-based configuration language that lets you match, filter, and control traffic to your endpoints without touching your app code. Learn more about the building blocks of Traffic Policy.
Now that you've added auth to your endpoint, here are some optional ways to fine tune other parts of your auth setup aside from strictly how to handle logins. Depending on your goal, you’ll either configure session behavior in your traffic policy YAML, or trigger runtime behavior in your app using special /ngrok/* URLs. See the following tables for details.
Table 1: Configurable Properties (traffic_policy settings)
| Behavior | Traffic Policy Config to Add |
|---|---|
| Shorten session timeout | idle_session_timeout: "15m" |
| Limit total session time | max_session_duration: "1h" |
| Periodically recheck identity | userinfo_refresh_interval: "10m" |
| Use your own OAuth app | Set client_id, client_secret, scopes + register https://idp.ngrok.com/oauth2/callback with your provider |
| Namespace sessions | auth_id: "my-login" (used in cookies & login/logout routing) |
Note: When configuring a custom OAuth app, while specifying client_id and client_secret, ensure that the redirect URI https://idp.ngrok.com/oauth2/callback is registered with your OAuth provider. This is essential for the OAuth flow to function correctly.
Table 2: Runtime Interactions (handled in your app logic via URL routes)
| Action | What to do in your app |
|---|---|
| Force a user to re-login | Redirect to /ngrok/login?auth_id=my-login |
| Log a user out | Redirect to /ngrok/logout?auth_id=my-login |
| Start session from scratch | Chain logout → login: redirect to /ngrok/logout?auth_id=my-login, then to /ngrok/login?auth_id=my-login |
Traffic Policy Examples:
This section includes two examples of how to apply these additional auth lifecycle options, depending on your traffic policy setup.
What these examples do:
- If a user visits
/ngrok/logout, ngrok first destroys their session (built-in behavior), then your redirect action sends them straight to the login URL. - Any session inactive for 15 minutes or longer will auto-expire and trigger a re-login flow when the user returns.
- After an hour (regardless of activity), users are forced to re-authenticate (
max_session_duration).
Loading…
Now you can restart your endpoint with the updated traffic policy file or config.
If you saved your Traffic Policy in a local file like oauth.yml, add the --traffic-policy-file flag to your ngrok command when starting your agent as shown in the following example.
Loading…
If you need assistance with specific configurations or further customization, feel free to ask our Support team at support@ngrok.com.
Bring your own OAuth application
Though this guide uses ngrok's managed Google OAuth application, you can also use your own OAuth application. See the following guides to get started with your preferred provider: