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

ngrok http 80 --basic-auth "username1:password1" --basic-auth "username2:password2"

Agent Config

tunnels:
  example:
    proto: http
    addr: 80
    basic_auth:
      - username1:password1
      - username2:password2

SSH

ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http \
  --basic-auth "username1:password1" \
  --basic-auth "username2:password2"

Go

import (
	"context"
	"net"

	"golang.ngrok.com/ngrok"
	"golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
	return ngrok.Listen(ctx,
		config.HTTPEndpoint(
			config.WithBasicAuth("username1", "password1"),
			config.WithBasicAuth("username2", "password2"),
		),
		ngrok.WithAuthtokenFromEnv(),
	)
}

Go Package Docs:

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

Javascript

const ngrok = require("@ngrok/ngrok");

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		basic_auth: ["username1:password1", "username2:password2"],
	});

	console.log(`Ingress established at: ${listener.url()}`);
})();

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

import ngrok

listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
    basic_auth=["username1:password1", "username2:password2"])

print(f"Ingress established at: {listener.url()}");

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

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;

    let tun = sess
        .http_endpoint()
        .basic_auth("username1", "password1")
        .basic_auth("username2", "password2")
        .listen()
        .await?;

    println!("Listening on URL: {:?}", tun.url());

    Ok(tun)
}

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.

ngrok http 80 \
  --basic-auth "user1:password1" \
  --basic-auth "user2:password2"

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.

ngrok http 80 \
  --basic-auth "username:password" \
  --request-header-remove "authorization" \
  --request-header-add "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

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:

ngrok http https://httpbin.org --url your-domain.ngrok.app --basic-auth "falken:joshuahunter2"

In another terminal, curl that endpoint.

Without any credentials:

curl https://your-domain.ngrok.app/status/200

401 Unauthorized

With incorrect credentials:

curl https://your-domain.ngrok.app/status/200 --user "foo:bar"

401 Unauthorized

And finally with valid credentials:

curl https://your-domain.ngrok.app/status/200 --user "falken:joshuahunter2" -I

HTTP/2 200