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 at our 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 that visitors for a username and password before granting access.

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

on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - USERNAME1:PASSWORD1
            - USERNAME2:PASSWORD2

Start an agent endpoint with that policy:

ngrok http 3000 --url=<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 authenticate 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.

on_http_request:
  - actions:
      - type: oauth
        config:
          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:

Ngrok-Auth-User-Email: user@example.com
Ngrok-Auth-User-Id: 102528612345998048947
Ngrok-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:

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
  - expressions:
      - "!actions.ngrok.oauth.identity.email.endsWith('your-company.com')"
    actions:
      - 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:

on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: "<YOUR_ISSUER_URL>"
          client_id: "<YOUR_CLIENT_ID>"
          client_secret: "<YOUR_CLIENT_SECRET>"
          scopes:
            - openid
            - profile
            - 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.

on_http_request:
  - actions:
      - type: jwt-validation
        config:
          issuer:
            allow_list:
              - value: https://your-auth-provider.com/
          audience:
            allow_list:
              - value: your-api-audience
          http:
            tokens:
              - type: access_token
                method: header
                name: Authorization
                prefix: "Bearer "
          jws:
            allowed_algorithms:
              - RS256
            keys:
              sources:
                additional_jkus:
                  - 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. Write a Traffic Policy file with your auth rules
3. 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 on Discord, in the ngrok/ngrok repo on GitHub, or email support@ngrok.com.