Basic Auth
Overview
This modules enforces HTTP Basic Authentication in front of you 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
- Agent Config
- SSH
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
ngrok http 80 --basic-auth "username1:password1" --basic-auth "username2:password2"
tunnels:
example:
proto: http
addr: 80
basic_auth:
- username1:password1
- username2:password2
ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http \
--basic-auth "username1:password1" \
--basic-auth "username2:password2"
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:
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:
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:
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:
This module is not supported by the Kubernetes Ingress Controller.
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:
-
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.
-
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
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 --domain 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