Skip to main content

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.

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.

Loading…

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

Loading…

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 still viewing your new cloud endpoint in the dashboard, copy and paste the policy below into the Traffic Policy editor, replacing $ISSUER_URL, $CLIENT_ID, and $CLIENT_SECRET with the appropriate values.

Loading…

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

← Back to other examples

Want to contribute to the examples gallery?