Documentation Index
Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Basic Authentication (Basic Auth) is a simple but effective way to restrict access to your services by requiring a valid username and password before allowing requests to reach your upstream service.
When Basic Authentication is enabled:
🔐 Requests without valid credentials are automatically rejected with a 401 Unauthorized response.
🔐 Only authenticated users can access your protected services.
⚡ Authentication is enforced at the gateway level, reducing security overhead for your backend.
🔍 What are the benefits of basic authentication?
HTTP Basic Authentication is a simple yet effective way to restrict access to sensitive services without requiring complex identity providers or OAuth-based authentication systems.
Key Benefits:
- Securing development or staging environments from public access.
- Adding a lightweight authentication layer when no other auth system is available.
- Protecting internal admin panels, dashboards, or API endpoints.
- Protect temporary or short-lived services without setting up an OAuth provider.
If you need more secure authentication methods for production traffic, consider the OAuth, OIDC, and JWT Validation guides.
Basic authentication examples
The following examples show how to set up an endpoint that accepts requests that contain basic auth credentials for either user:password1 or admin:password2.
All other requests will be denied with a 401 response code.
Check out the basic auth Traffic Policy action page for more details about how it functions and the parameters it accepts.
AgentEndpoint
CloudEndpoint
Ingress
Gateway API
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
name: example-agent-endpoint
spec:
url: https://example-hostname.ngrok.io
upstream:
url: http://my-service.my-namespace:8080
trafficPolicy:
inline:
on_http_request:
- actions:
- type: basic-auth
config:
realm: sample-realm
credentials:
- user:password1
- admin:password2
enforce: true
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: CloudEndpoint
metadata:
name: example-cloud-endpoint
spec:
url: https://example-hostname.ngrok.io
trafficPolicy:
policy:
on_http_request:
- actions:
- type: basic-auth
config:
realm: sample-realm
credentials:
- user:password1
- admin:password2
enforce: true
- type: custom-response
config:
status_code: 200
headers:
content-type: text/plain
body: Successfully Authenticated!
💡 Ingress resources do not natively support Basic Authentication, but they can be extended using a Traffic Policy.1. Create an NgrokTrafficPolicy
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
name: example-tp
namespace: default
spec:
policy:
on_http_request:
- actions:
- type: basic-auth
config:
realm: sample-realm
credentials:
- user:password1
- admin:password2
enforce: true
2. Use the NgrokTrafficPolicy on an Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.ngrok.com/traffic-policy: example-tp
name: example-ingress
namespace: default
spec:
ingressClassName: ngrok
rules:
- host: example-hostname.ngrok.io
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
💡 Gateway API resources do not natively support Basic Authentication, but they can be extended using a Traffic Policy.1. Create an NgrokTrafficPolicy
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
name: example-tp
namespace: default
spec:
policy:
on_http_request:
- actions:
- type: basic-auth
config:
realm: sample-realm
credentials:
- user:password1
- admin:password2
enforce: true
2. Use the NgrokTrafficPolicy on a Gateway
The following example showcases supplying the NgrokTrafficPolicy on a Gateway resource. All requests to the Gateway will run the Traffic Policy.
If you prefer, NgrokTrafficPolicy can also be used on the route level by using an externalRef filter on an HTTPRoute. See the using Gateway API guide for examples.apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
namespace: default
annotations:
k8s.ngrok.com/traffic-policy: example-tp
spec:
gatewayClassName: ngrok
listeners:
- name: example-hostname
hostname: "example-hostname.ngrok.io"
port: 443
protocol: HTTPS
