Skip to main content
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.

​
1. Set up your OIDC provider

You can use any provider with the oidc Traffic Policy action. You’ll need the base URL of your Open ID provider, and, in most cases, a client ID and secret. We’ll refer to these as $ISSUER_URL, $CLIENT_ID, and $CLIENT_SECRET.

​
2. 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 our 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.

​
3. Reserve a domain

Navigate to the Domains section of the ngrok dashboard and click New + to reserve a free static domain like https://your-service.ngrok.app or a custom domain you already own. We’ll refer to this domain as $NGROK_DOMAIN from here on out.

​
4. 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.

​
5. 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.

​
6. 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?