auth-proxy

Auth Proxy

A reverse proxy for putting authentication and route-based authorization in front of services.

I created this for integrations like Google Sheets (both loading and retrieving data), Ollama, and OpenClaw.

1. Setup some users and/or tokens and/or "guest"

   csvauth init
   csvauth store --roles '/' 'my-admin-user'
   csvauth store --roles '/' --token 'an-admin-token'
   csvauth store --roles 'GET:/public/ POST:/dropbox/' --ask-password 'guest'
   

2. Stand up the proxy behind the TLS Proxy
   (snirouter, Caddy, Traefik, Nginx+certbot, etc)

   auth-proxy --port 8080 --target-proxy http://localhost:11343
   

3. Enjoy protected access!

Table of Contents

• Installation
• Supported Authentication Methods
  (all "basic" types - no signature verification)
• Credential Management
  • By Hand
  • By csvauth
  • "guest" to skip auth
• Permission Pattern Matching
  • / (full access)
  • GET:example.com/api/endpoint (granular access)
  • GET:/endpoint/{$} (exact path match)

Installation

For right now, it's just go install

# csvauth (optional, but recommended)
go install github.com/therootcompany/golib/auth/csvauth/cmd/csvauth@v1

# auth-proxy (this thing)
go install github.com/therootcompany/golib/cmd/auth-proxy@v1

Later I'll add this to GitHub Releases and webi.

If you don't have go:

curl https://webi.sh/go | sh
source ~/.config/envman/PATH.env

(installs safely to ~/.local/opt/go and ~/go/)

Supported Methods

Authentication is checked for in this order:

The first match wins (even if it has lower privileges).

You can control which methods are allowed:

--token-schemes 'Bearer,Token' # '*' for any
--token-headers 'X-API-Key,X-Auth-Token,X-Access-Token'
--token-params 'access_token,token'

Tips:

• Use an empty string '' or 'none' to disable that method.
• Set --token-headers 'Authorization' for scheme-less Authorization: <token>

Credential Management

Credentials are managed in credentials.tsv:

--credentials ./credentials.tsv
--comma "\t"
--aes-128-key ~/.config/csvauth/aes-128.key

# by default this is read from ~/.config/csvauth/aes-128.key
export CSVAUTH_AES_128_KEY=0123456789abcdeffedcba9876543210

The AES key is used if reversible algorithms are used, or if tokens are used (as part of deriving an id). 128-bits was chosen for the same reason your browser uses it: 256-bit isn't more secure.

Plain Text by Hand

Create a comma-separated list of credentials with the plain algorithm:

purpose,name,algo,salt,derived,roles,extra
login,guest,plain,,,GET:/{$},
login,tom,plain,,my-plain-text-password,/,
login,harry,plain,,another-plain-password,GET:/ POST:/logs,

You need to set the delimiter back to comma to manage this way by hand (it's tab by default).

--comma ","

Password / token comparisons will still be done via timing-safe hashes, even when the algorithm is plain.

Secure with csvauth

This create a tab-separated list of credentials (default: pdfkdf2 for 'login', aes-128-gcm for 'token')

csvauth init

You MUST supply space-delimited --roles in the form of [METHOD:][HOST]/[PATH].

csvauth store --roles '/' 'my-admin-user'
csvauth store --roles '/' --token 'an-admin-token'

The password or token will be randomly generated and printed to the screen by default.

--roles '/' # space-delimited patterns
--token # generates a token (no username required)
--ask-password # you'll be asked to type in or paste the password / token

Note: csv store --token <same-name-as-before> will NOT replace the existing token (because their ids are pairwise with their value). For now you'll have to delete old tokens by hand.

Public Access

Any routes that you want to make public (no auth protection) should be granted to a user named guest and have NO PASSWORD.

To do this use --ask-password and hit enter instead of giving one.

csvauth store --roles 'GET:/{$} GET:/public/ POST:/dropbox/' --ask-password 'guest'

Permission Matching

The patterns are based on Go's ServeMux pattern matching, but using : instead of space because roles are space-delimited in csvauth.

[METHOD:][HOST]/[PATH]

Meaning

• Method is optional - all of GET, POST, etc are allowed by default
• Hostname is optional - any domain is allowed by default
• / is required - no paths are allowed by default

The syntax looks like this:

/
GET:example.com/api
GET:/api
example.com/api

Very simple patterns are also supported

• {x} for an optional wildcard path component
• {$} for an exact match
• /path and /path/ are always considered equal

For example:

You can also use vanity wildcards (instead of just {x}):

• /api/users/{userID}/favorites
• /api/files/{fullpath...}