Authentication with ngrok

Not every app fits the standard auth model of user registration, login forms, and password resets. Maybe you’re running a quick demo, working with a legacy system you can’t modify, or just need to lock something down fast.

ngrok’s Traffic Policy system lets you add authentication to any endpoint in minutes and without touching your application code.

Let’s walk through how to use Traffic Policy for Basic Auth, OAuth, OpenID Connect, and JWT validation.

What is Traffic Policy?

Traffic Policy is ngrok’s configuration language for managing traffic in ngrok’s cloud. You write rules in YAML that filter, validate, and route requests before they reach your upstream service. Each rule has:

• Expressions that match specific conditions (like checking a header or email domain)
• Actions that execute when conditions match (like denying access or validating a JWT)

You can chain multiple rules together. For authentication, this means you can validate tokens, restrict access by email domain, and add rate limiting all in one policy file.

HTTP Basic Auth

The simplest form of authentication prompts visitors for a username and password before granting access.

Create a YAML file (policy.yaml) with the following Traffic Policy rule:

1on_http_request:⋯2  - actions:⋯3      - type: basic-auth⋯4        config:⋯5          credentials:⋯6            - USERNAME1:PASSWORD17            - USERNAME2:PASSWORD2

Start an agent endpoint with that policy:

ngrok http 3000 --url https://<YOUR_DOMAIN> --traffic-policy-file /path/to/policy.yaml

Basic Auth is great for one-off demos or sharing local work with a co-worker. For production, move to a more secure method.

OAuth 2.0

OAuth lets users log in with their existing credentials from providers like Google, GitHub, or Microsoft. They don’t need to use a password, you don’t have to manage them, and ngrok manages the provider infrastructure so you don’t have to set one up yourself.

1on_http_request:⋯2  - actions:⋯3      - type: oauth⋯4        config:⋯5          provider: google

When a user accesses your endpoint, they’re redirected to Google to authenticate, then back to your app. ngrok passes identity information as headers:

1Ngrok-Auth-User-Email: user@example.com2Ngrok-Auth-User-Id: 1025286123459980489473Ngrok-Auth-User-Name: Jane Developer

To restrict access to specific email domains, add an expression that denies requests authenticated with any email that does not end with your-company.com:

1on_http_request:⋯2  - actions:⋯3      - type: oauth⋯4        config:⋯5          provider: google6  - expressions:⋯7      - "!actions.ngrok.oauth.identity.email.endsWith('your-company.com')"8    actions:⋯9      - type: deny

You can add multiple domain checks or allow specific email addresses for contractors.

OpenID Connect

For corporate or internal identity providers (Okta, Auth0, Azure AD), use OpenID Connect (OIDC).

First, configure your IdP with https://idp.ngrok.com/oauth2/callback as a sign-in redirect URI. Then create your Traffic Policy:

1on_http_request:⋯2  - actions:⋯3      - type: openid-connect⋯4        config:⋯5          issuer_url: "<YOUR_ISSUER_URL>"6          client_id: "<YOUR_CLIENT_ID>"7          client_secret: "<YOUR_CLIENT_SECRET>"8          scopes:⋯9            - openid10            - profile11            - email

Your endpoint is now protected by your corporate identity provider.

JWT validation

For API-to-API authentication, validate JSON Web Tokens (JWTs) in ngrok’s cloud before requests reach your service.

1on_http_request:⋯2  - actions:⋯3      - type: jwt-validation⋯4        config:⋯5          issuer:⋯6            allow_list:⋯7              - value: https://your-auth-provider.com/8          audience:⋯9            allow_list:⋯10              - value: your-api-audience11          http:⋯12            tokens:⋯13              - type: access_token⋯14                method: header15                name: Authorization16                prefix: "Bearer "17          jws:⋯18            allowed_algorithms:⋯19              - RS25620            keys:⋯21              sources:⋯22                additional_jkus:⋯23                  - https://your-auth-provider.com/.well-known/jwks.json

Invalid tokens get rejected before hitting your backend. You can also combine JWT validation with rate limiting keyed to the token for per-consumer limits.

Get started

To add authentication to your endpoints:

1. Create a free ngrok account
2. Add your authtoken with ngrok config add-authtoken <token>
3. Write a Traffic Policy file with your auth rules
4. Start your endpoint with --traffic-policy-file

Explore the docs for each auth action:

• Basic Auth
• OAuth
• OIDC
• JWT Validation

For additional access control, you can also use IP restrictions to allowlist trusted sources or mTLS for certificate-based authentication on TLS endpoints.

Questions? Find us in the ngrok/ngrok repo on GitHub, or email support@ngrok.com.