Documentation / Password Protection

Password Protection

Secure your tunnels with password protection and OAuth authentication

Overview

stunl offers multiple authentication methods to secure access to your tunnels:

🔐 Basic Auth Password

Simple password protection using HTTP Basic Auth. Great for quick sharing with a single password.

Pro

🔑 OAuth Authentication

Enterprise SSO with GitHub, Google, or Microsoft. Restrict by domain, email, or team membership.

Pro

Note on TCP/UDP Tunnels

Password protection applies to HTTP/WebSocket tunnels only. TCP and UDP tunnels rely on application-level authentication (e.g., database passwords, SSH keys).

Basic Password Protection

The simplest way to protect your tunnel. Visitors will be prompted for a password before accessing your site.

Create a password-protected tunnel 
$ stunl -port 3000 -password mysecretpass123

  ● STUNL

  ╭── ◎ ── HTTP (🔒 Password Protected)
  │   HTTPS    https://abc123.stunl.io
  │   HTTP     http://abc123.stunl.io
  │   Local    localhost:3000
  │   Auth     Password Required
How visitors access protected tunnels
  • 1. Visitor opens your tunnel URL in their browser
  • 2. Browser prompts for username and password (HTTP Basic Auth)
  • 3. Username can be anything (or left blank), password must match
  • 4. Once authenticated, access is granted until browser is closed
Accessing from CLI or code 
# Using curl
$ curl -u :mysecretpass123 https://abc123.stunl.io

# Using wget
$ wget --password=mysecretpass123 https://abc123.stunl.io

# In JavaScript (fetch)
fetch('https://abc123.stunl.io', {
  headers: {
    'Authorization': 'Basic ' + btoa(':mysecretpass123')
  }
})

OAuth Authentication

For enterprise security, use OAuth to require users to authenticate with their existing identity provider. This allows fine-grained access control based on email domains, specific users, or team membership.

GitHub OAuth

# Require GitHub authentication
$ stunl -port 3000 -oauth github

# Restrict to specific GitHub organization
$ stunl -port 3000 -oauth github -oauth-github-org acme-corp

# Restrict to specific team within organization
$ stunl -port 3000 -oauth github -oauth-github-team acme-corp/developers

# Multiple orgs or teams (comma-separated)
$ stunl -port 3000 -oauth github \
    -oauth-github-org "acme-corp,partner-org" \
    -oauth-github-team "acme-corp/developers,acme-corp/qa"

Google OAuth

# Require Google authentication
$ stunl -port 3000 -oauth google

# Restrict to specific email domain (Google Workspace)
$ stunl -port 3000 -oauth google -oauth-allow-domain acme.com

# Allow multiple domains
$ stunl -port 3000 -oauth google \
    -oauth-allow-domain "acme.com,partner.com"

Microsoft OAuth (Azure AD)

# Require Microsoft authentication
$ stunl -port 3000 -oauth microsoft

# Restrict to Azure AD tenant domain
$ stunl -port 3000 -oauth microsoft -oauth-allow-domain acme.onmicrosoft.com

Email-Based Restrictions

Fine-grained access control by allowing specific email addresses or domains.

Email restrictions 
# Allow only specific email addresses
$ stunl -port 3000 -oauth google \
    -oauth-allow-email "alice@acme.com,bob@acme.com,carol@partner.com"

# Allow entire domain
$ stunl -port 3000 -oauth google \
    -oauth-allow-domain "acme.com"

# Combine domain and specific emails
$ stunl -port 3000 -oauth google \
    -oauth-allow-domain "acme.com" \
    -oauth-allow-email "contractor@external.com"

OAuth Flags Reference

Flag Description
-oauth OAuth provider: github, google, or microsoft
-oauth-allow-domain Restrict to email domain(s), comma-separated
-oauth-allow-email Restrict to specific email(s), comma-separated
-oauth-github-org Require GitHub org membership(s), comma-separated
-oauth-github-team Require GitHub team membership(s), format: org/team

Multi-Port with Authentication

When using multi-port tunneling, authentication applies to all HTTP endpoints in the tunnel.

Multi-port with password protection 
$ stunl -id myapp \
    -ports "web:3000:http,api:8080:http" \
    -password secretpass

  ● STUNL

  ╭── ◎ ── HTTP web (🔒)
  │   HTTPS    https://myapp.stunl.io
  │   Local    localhost:3000

  ╭── ◎ ── HTTP api (🔒)
  │   HTTPS    https://myapp.stunl.io/api
  │   Local    localhost:8080

# Both endpoints require the same password

Pro Authentication Features

Feature Pro
Password protection ✓
OAuth (GitHub) ✓
OAuth (Google) ✓
OAuth (Microsoft) ✓
Email domain restrictions ✓
GitHub org/team restrictions ✓

Security Best Practices

Use strong passwords

Choose passwords at least 12 characters long with a mix of letters, numbers, and symbols. Avoid common words or patterns.

Prefer OAuth for teams

For team access, OAuth is more secure than sharing a password. Each user authenticates with their own credentials.

Restrict by domain when possible

Using -oauth-allow-domain ensures only verified users from your organization can access the tunnel.

Use E2E encryption for sensitive data

Combine password protection with end-to-end encryption (-e2e) for maximum security.

Next Steps