Skip to main content

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:

  • Google
  • GitHub
  • GitLab
  • LinkedIn
  • Microsoft
  • Twitch

This guide will use Google OAuth.

note

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)

BehaviorTraffic Policy Config to Add
Shorten session timeoutidle_session_timeout: "15m"
Limit total session timemax_session_duration: "1h"
Periodically recheck identityuserinfo_refresh_interval: "10m"
Use your own OAuth appSet client_id, client_secret, scopes + register https://idp.ngrok.com/oauth2/callback with your provider
Namespace sessionsauth_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)

ActionWhat to do in your app
Force a user to re-loginRedirect to /ngrok/login?auth_id=my-login
Log a user outRedirect to /ngrok/logout?auth_id=my-login
Start session from scratchChain 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: