Route to Services Based on OIDC Authentication

With ngrok, you can use OpenID Connect to do more than authenticate requests—you can also use the data returned by your OIDC provider to route requests to specific upstream services. This pattern allows you to grant credentialed users and remote devices access to services on your internal ngrok network without maintaining a complex routing topology. Example use cases include internal management UIs or API services.

Set up your OIDC provider

You can use any provider with the openid-connect Traffic Policy action. You’ll need the base URL of your Open ID provider, and, in most cases, a client ID and secret.These are referred to as $ISSUER_URL, $CLIENT_ID, and $CLIENT_SECRET.

Start endpoints for your services

Start an internal Agent Endpoint, replacing $PORT based on where one of your upstream services listen. You can also use one of the SDKs or the Kubernetes Operator.

ngrok http $PORT --url https://service-one.internal

Start a second Agent Endpoint for another service you want to route to, replacing $OTHER_PORT with the port for this service.

ngrok http $OTHER_PORT --url https://service-two.internal

Repeat the process for as many services as you need to route to.

Reserve a domain

Navigate to the Domains section of the ngrok dashboard and click New + to reserve a free static domain like or a custom domain you already own.This guide refers to this domain as $NGROK_DOMAIN from here on out.

Create a Cloud Endpoint

Navigate to the Endpoints section of the ngrok dashboard, then click New + and Cloud Endpoint.In the URL field, enter the domain you just reserved to finish creating your Cloud Endpoint.

Enforce OIDC authentication and routing with Traffic Policy

While viewing your new Cloud Endpoint in the dashboard, copy the policy below and paste it into the Traffic Policy editor, replacing $ISSUER_URL, $CLIENT_ID, and $CLIENT_SECRET with the appropriate values.

on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: "$ISSUER_URL"
          client_id: "$CLIENT_ID"
          client_secret: "$CLIENT_SECRET"
          scopes:
            - openid

  - expressions:
      - actions.ngrok.oidc.identity.name == 'Bob'
    actions:
      - type: forward-internal
        config:
          url: https://service-one.internal
  - expressions:

      - actions.ngrok.oidc.identity.name == 'Alice'
    actions:
      - type: forward-internal
        config:
          url: https://service-two.internal

What’s happening here? This policy first requires OIDC authentication on every request using your issuer URL, client ID, and client secret.If you authenticate successfully, this policy then filters your request based on the name as returned from your OIDC provider and routes your request to a specific service.

Try out your endpoints

Visit the domain you reserved either in the browser or in the terminal using a tool like curl. You should see the app or service at the port connected to your internal Agent Endpoint.

What’s next?

Explore other authentication methods like OAuth, Basic Auth, JWT validation, or SAML (early access).
Learn about other routing options beyond OIDC identity, like routing by path, header, or geographic location.
Read the guides on securing access to remote devices or site-to-site connectivity for more comprehensive setups involving Service Users, scoped auth tokens, and mTLS.
View your traffic in Traffic Inspector.

Getting Started

Use Cases

Examples

Connectivity

Traffic Policy

Observability

Network

Resources

Identity & Access

Route to Services Based on OIDC Authentication

Set up your OIDC provider

Start endpoints for your services

Reserve a domain

Create a Cloud Endpoint

Enforce OIDC authentication and routing with Traffic Policy

Try out your endpoints

What’s next?

Set up your OIDC provider

Start endpoints for your services

Reserve a domain

Create a Cloud Endpoint

Enforce OIDC authentication and routing with Traffic Policy

Try out your endpoints

​What’s next?

What’s next?