Basic Auth

Overview

This modules enforces HTTP Basic Authentication in front of your endpoints. Requests with a valid username and password will be sent to your upstream service, all others will be rejected with a 401 Unauthorized response.

Example Usage

Allow requests from two different users, each with a different password.

Agent CLI

Loading…

Agent Config

Loading…

SSH

Loading…

Go

Loading…

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithBasicAuth

Javascript

Loading…

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#basic_auth
• https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#basicAuth

Python

Loading…

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.basic_auth
• https://ngrok.github.io/ngrok-python/index.html#full-configuration

Rust

Loading…

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/config/struct.HttpTunnelBuilder.html#method.basic_auth

Kubernetes Controller

info

This module is not supported by the ngrok Kubernetes Operator.

Behavior

This module enforces HTTP Basic Auth as defined by RFC 7617.

Requests with a valid username and password are sent to the upstream application. All other requests receive an HTTP 401 response.

Multiple Credentials

You may specify multiple username/password credential pairs. A request is allowed if it matches any of the configured credentials.

Loading…

Realm

The HTTP Basic Auth realm is always 'ngrok'. It may not be configured.

Basic Auth on Upstream Service

If your upstream service also enforces HTTP Basic Auth, it is not recommended to use this module with it. Instead, you should choose to either not use this module or to disable http basic auth enforcement on your upstream service. If you absolutely must use HTTP Basic Auth on both your ngrok endpoint and your upstream service, you have two options:

1. Ensure that the username/password credentials enforced by ngrok and those enforced by the upstream service are identical. If you don't, no requests will ever be successful because they will always be rejected by either your ngrok endpoint or the upstream service.

2. Use the Request Headers module to rewrite the authorization header to the value expected by the upstream service. For example, if you want to accept requests with credentials of "username:password, but the upstream service expects credentials of "Aladdin:open sesame", you could use the following command. Keep in mind that you need to base64 encode the username and password for the upstream service.

Loading…

Reference

Configuration

Parameter	Description
Credentials	A list of username/password pairs specified as 'username:password'. Passwords must be at least 8 characters and more than 128 characters.

Upstream Headers

This module does not add any upstream headers.

Errors

Code	HTTP Status	Error
no ngrok error code	401	This error is returned if a request is disallowed.

Events

This module does not populate any fields in events. When this module is enabled, it populates the following fields in the http_request_complete.v0 event:

Fields
basic_auth.decision
basic_auth.username

Edges

info

Basic Auth is not a supported HTTPS Edge module yet.

Pricing

This module is available on all plans.

Try it out

Start ngrok in one terminal:

Loading…

In another terminal, curl that endpoint.

Without any credentials:

Loading…

401 Unauthorized

With incorrect credentials:

Loading…

401 Unauthorized

And finally with valid credentials:

Loading…

HTTP/2 200