ProxyAuth

  • Lastest version 0.7.4
  • License: Apache 2.0
  • Author: Vladimir SOUCHET (vBlackOut)

Getting Started

ProxyAuth secures backend APIs through a fast authentication gateway. It encrypts tokens using ChaCha20 + HMAC-SHA256, with config-defined secrets. It features built-in rate limiting (on proxy and auth routes) and uses Argon2 with auto-generated salts for secure password hashing. The service is extremely fast, handling 100,000+ requests per second under load.

Motivation
  1. ProxyAuth to improve the security of your tokens.
  2. Accelerate your backend API development and gain better security insights with ProxyAuth.
  3. ProxyAuth performs ultra-fast token verification. 🚀
  4. ProxyAuth is written in Rust! 🦀
Small demo on loki/grafana
This is a simplified diagram. It might not be fully accurate, but it represents the general idea.

Build/Install

⚠️ Danger

To ensure better security, I cannot deliver the container, as ProxyAuth generates the cryptographic secret randomly during the build.
Building it yourself is very important. (Do not run any container pulled from Docker Hub, Bitbucket, or any other public cloud).

Auto Build/Install via curl (build/install and create the configuration)

// latest stable version
$curl -fsSL https://proxyauth.app/sh/install | bash
// latest beta version
$curl -fsSL https://proxyauth.app/sh/beta-install | bash
// automaticaly launch proxyauth show status on systemd
$sudo systemctl status proxyauth
// use a specific version with @x.x.x (must be >= 0.5.6) versions lower than 0.5.6 are not supported.
$curl -fsSL https://proxyauth.app/sh/install@0.7.0 | bash

Use Docker (you don't need to install rust on your local machine)

// clone the project
$git clone https://github.com/ProxyAuth/Docker ProxyAuth && cd ProxyAuth/latest
// ⚠️ important: Ensure correct permissions on the configuration file owned by the proxyauth user inside the container.
$sudo chown 1000:1000 config/config.json config/routes.yml
// build & launch proxyauth inside docker container
$docker compose build && docker compose up -d

Uninstall

Uninstall all file ProxyAuth, User/config ect...

$curl -fsSL https://proxyauth.app/sh/uninstall | bash

CLI command

proxyauth stats

Notice

The token ID isn't the real token, it's just a way to reference it.
The real token is private and securely handled — it is never stored.

Used to display token usage statistics. In previous versions, it was possible to revoke a specific token ID.
Example: The user "admin" has used the token ID "AVzjugA=yY!$#..." a total of 2 times.


curl give stats

The admin token is in /etc/proxyauth/config/config.json (automatically created at launch).
// show stats
$curl -k -H 'X-Auth-Token: [YOUR_TOKEN_ADMIN]' https://127.0.0.1:8080/adm/stats
response
[
  {
    "user": "admin",
    "tokens": [
      {
        "token_id": "QzK=8S*lx9A@gebUZBB%m$a5+uo@lPx*F+d2QdCssbA+sl(R",
        "count": 1,
        "delivery_at": "2025-05-28T18:18:02.251295314Z",
        "expire_at": "2025-05-28T19:17:47Z"
      }
    ]
  }
]

Configuration

Notice

Configuration Path: ProxyAuth stores its configuration in /etc/proxyauth/config/ (version >= 0.5.6)
Please install via (curl or docker)


File config.json

Complete file: /etc/proxyauth/config/config.json 
{
  "token_expiry_seconds": 3600,
  "secret": "supersecretvalue",
  "host": "0.0.0.0",
  "port": 8080,
  "worker": 4,
  "log": {"type": "local"},
  "stats: true,
  "max_idle_per_host": 200,
  "timezone": "Europe/Paris",
  "ratelimit_auth": {
    "burst": 10,
    "block_delay": 500,
    "requests_per_second": 10
  },
  "ratelimit_proxy": {
    "burst": 10,
    "block_delay": 500,
    "requests_per_second": 10
  },
  "users": [
    {
      "username": "admin",
      "password": "$argon2id$v=19$m=19456,t=2..."
    },
    {
      "username": "alice",
      "password": "$argon2id$v=19$m=19456,t=2..."
    }
  ]
}

Options Documentation

* All is Required.
token_expiry_seconds
1-31536000 (Max 5 Years)
Default: 3600
secret
Please generate a secure token (64 characters or more!)
Default: unset
host
IP address where the server listens
Default: 0.0.0.0
timezone
A timezone defines how a specific region offsets from UTC (Coordinated Universal Time).
you can select a timezone like Europe/Paris, UTC, or America/New_York to properly convert and display timestamps in local time.
[ show all possible value ]
Default: Europe/Paris
port
Valid range: 1–65535
Default: 8080
worker
Number of CPUs available
Default: 4
log
type: local → do not use remote logging
type: loki → use Loki logging {"type": "loki", "host": "127.0.0.1:1234"}
Default: local
stats
boolean: true/false → do not use remote stats /adm/stats or proxyauth stats
Default: false
max_idle_per_host
int: 0-3000 → defines the maximum number of idle (keep-alive) connections that can be kept open per host. This helps optimize performance by reusing connections instead of opening new ones for each request, while also preventing excessive resource usage by limiting the number of unused open connections.
Default: 50
ratelimit_auth
request_per_seconds: 0 for disable the rate limit, Maximum number of authentication requests allowed per second from a single client.
burst: Number of extra requests allowed beyond the per-second rate before blocking is enforced.
block_delay: Time a client must wait (after exceeding limits) before sending new authentication
Default: Disabled
ratelimit_proxy
request_per_seconds: 0 for disable the rate limit, Maximum number of forward proxy requests allowed per second from a single client.
burst: Number of extra requests allowed beyond the per-second rate before blocking is enforced.
block_delay: Time a client must wait (after exceeding limits) before sending forward request inside ProxyAuth
Default: Disabled
users
Array of user objects for authentication.
Key username username to use with the /auth route to obtain a token
Key password password to use with the /auth route to obtain a token


File routes.yml

Complete file: /etc/proxyauth/config/routes.yml 
routes:
  - prefix: "/redoc"
    target: "http://127.0.0.1:8000/redoc"
    secure: false

  - prefix: "/api_test/openapi.json"
    target: "http://localhost:8000/api_test/openapi.json"
    secure: false
    backends:
      - http://localhost:8001/api_test/openapi.json
      - http://localhost:8002/api_test/openapi.json

  - prefix: "/api_test_default"
    target: "http://localhost:8000/api_test_default"
    username: ["admin", "alice1", "alice15", "alice30"]

  - prefix: "/api_test_proxy"
    target: "http://localhost:8000/api_test_proxy"
    username: ["admin", "alice1", "alice15", "alice30"]
    proxy: true
    proxy_config: "http://127.0.0.1:8888"

  - prefix: "/api_test_cert"
    target: "https://localhost:8000/api_test_cert"
    username: ["admin", "alice1", "alice15", "alice30"]
    cert: {"file": "certificat.p12", "password": "1234"}

Options Documentation

prefix * Required
Defines the URL prefix to use when forwarding the original request to the target service.
target * Required
Specifies the destination URL or service that will receive the forwarded request.
backends
Defines a failover mechanism by providing alternative URLs or services. In the event of a failure or downtime of the primary service, requests will be redirected to a secondary target, ensuring fault tolerance and service continuity.
username
A list of allowed usernames authorized to access this route.
Default: unset.
secure
Determines whether the route requires authentication.
Set the secure key to true to require a token, or false to disable authentication.
Default: true
proxy
Enable or disable proxy forwarding.
Use true to need token for access this resource, false to no token need for access this route by
Default: false.
proxy_config
Configuration object for the proxy destination.
Key host [IP:PORT] or hostname of the proxy target.
Default: unset.
cert * Experimental
SSL/TLS certificate configuration:
Key file Path to the certificate file (e.g., certificate.p12).
Key password Password used to unlock the certificate.
Default: unset.

Credential Route

ProxyAuth authenticate route for give token.

METHOD POST
URL [host:port]/auth
HEADER Content-Type: application/json
PARAMS { "username": <string>, "password": <string> }
  1. Rate limiting can be configured here via the ratelimit field in config.json."
SHOW EXEMPLE ▶
// default login is admin and admin123 change this in config.json
$curl -k -X POST https://127.0.0.1:8080/auth -H "Content-Type: application/json" -d '{"username": "admin", "password": "admin123"}'
// Header
HTTP/1.1 200 OK
content-length: 191
x-ratelimit-remaining: 4
x-ratelimit-limit: 5
content-type: application/json
date: Sun, 27 Apr 2025 07:29:21 GMT
// Response body
{"expires_at":"2025-04-27 09:37:05","token":"85l19fN5l+DKozxk29xeMtw2PgH/aNnVAgEJLxNo8M7xsumcO1cxS1BsfsUQIg+EXdV1vpxQMSNpiPPymBvfGUx2ufPT1jK7JVT9Aw3amQTOs5k8oBs+Qh6EbKHJsyohcioACLP9MWQ/DHhb"}
// Header
HTTP/1.1 429 Too Many Requests
content-length: 30
x-ratelimit-remaining: 0
x-ratelimit-limit: 5
x-ratelimit-after: 6
retry-after: 6
content-type: text/plain; charset=utf-8
date: Sun, 27 Apr 2025 07:29:21 GMT
// Response body
Too many requests, retry in 6s
Send Login/password for give token
This route returns an expiration date and a different token on each call.
sequenceDiagram autonumber participant C as Client participant P as ProxyAuth C->>+P: POST https://[host:port]/auth
-H "Content-Type: application/json"
-d {"username": "user", "password": "pass"} P->>+P: Check credential P->>+C: return json format
{"expires_at":"2025-04-12 16:15:20","token":"4GJeCUwOzILd..."}

Forward Route

ProxyAuth forwards your original request to the target after validating the token.

METHOD ALL
URL https://[host:port]/[prefix]
HEADER "Authorization: Bearer <your_token>"
  1. If the secure option is set to true in your routes.yml configuration, then the route will be secured
  2. Rate limiting can be configured here via the ratelimit field in config.json."
SHOW EXEMPLE ▶
// use route in routes.yml
$curl -k -X GET https://127.0.0.1:8080/api_test -H "Authorization: Bearer YOUR_TOKEN_HERE"
Scenario 1 send a valid token.
sequenceDiagram autonumber participant C as Client participant P as ProxyAuth participant A as API/Service C->>+P: Send token Header
-X POST https://[host:port]/api -H "Content-Type: application/json"
-H "Authorization: Bearer UmbC0ZgATdXE..." -d {"data": "test"} P->>+P: Check token send by client P->>+A: Forward original request
POST http://[host_target]/api_test
-H "Content-Type: application/json"
-d {"data": "test"} A-->>-P: Response P-->>-C: Response


Scenario 2 send a invalid token/expired.
sequenceDiagram autonumber participant C as Client participant P as ProxyAuth participant E as API/Service C->>+P: Send token Header
-H "Authorization: Bearer UmbC0ZgATdXE..." P->>+P: Check token send by client P-->>-C: Invalid Token Note over E: No external request made

Forward route via other proxy

Notice

ProxyAuth allows you to forward your request through another proxy to access your target destination.


sequenceDiagram autonumber participant C as Client participant P as ProxyAuth participant P2 as Other Proxy participant A as API/Service C->>+P: Send token Header
-X POST https://[host:port]/api -H "Content-Type: application/json"
-H "Authorization: Bearer UmbC0ZgATdXE..." -d {"data": "test"} P->>+P: Check token send by client P->>+P2: Forward original request
POST http://[host_target]/api_test
-H "Content-Type: application/json"
-d {"data": "test"} P2-->>+A: Forward A->>-P2: Response P2->>P: Response P-->>-C: Response

Forwarding with HTTPS Certificate (PKCS#12 / .p12) (UNTESTED)

⚠️ TESTING [Version 0.6.21]

ProxyAuth enables forwarding of HTTPS requests in order to securely access a remote machine.


sequenceDiagram autonumber participant C as Client participant P as ProxyAuth participant A as HTTPS/TLS
API/Service C->>+P: Send token Header
-X POST https://[host:port]/api -H "Content-Type: application/json"
-H "Authorization: Bearer UmbC0ZgATdXE..." -d {"data": "test"} P->>+P: Check token send by client P->>+A: Forward original https over https request
POST https://[host_target]/api_test
-H "Content-Type: application/json"
-d {"data": "test"} A-->>-P: Response P-->>-C: Response

Forwarding with HTTPS [Works Now]

Notice

You need a valid Let's Encrypt or other trusted certificate for the redirection to work correctly.

sequenceDiagram autonumber participant C as Client participant P as ProxyAuth participant A as HTTPS/TLS
API/Service C->>+P: Send token Header
-X POST https://[host:port]/api -H "Content-Type: application/json"
-H "Authorization: Bearer UmbC0ZgATdXE..." -d {"data": "test"} P->>+P: Check token send by client P->>+A: Forward original https over https request
POST https://[host_target]/api_test
-H "Content-Type: application/json"
-d {"data": "test"} A-->>-P: Response P-->>-C: Response

Logs via Loki


Coming up... undocumented but it's tested and work

Changelog #back to top

You can find the version history (CHANGELOG.md)

Changelog



                        -----------------------------------------------------------------------------------------
                        Version 0.7.4
                        -----------------------------------------------------------------------------------------
                            [ADD] Support for exporting and importing keystores for multi-service
                                  cryptographic integration change libs for oppenssl.
                            [SECURITY] Rewrite all headers from original requests and replace the server name.

                        -----------------------------------------------------------------------------------------
                        Version 0.7.3
                        -----------------------------------------------------------------------------------------
                            [ADD] Export build parameters as part of the GPG multi-service integration.
                            [ADD] New cryptographic build export for multi-service integration generated by GPG File.

                        -----------------------------------------------------------------------------------------
                        Version 0.7.2
                        -----------------------------------------------------------------------------------------
                            [ADD] Better Logs Proxy
                            [ADD] token ID random over timestamp
                            [ADD] reuse client Cache

                        -----------------------------------------------------------------------------------------
                        Version 0.7.1
                        -----------------------------------------------------------------------------------------
                            [ADD] Failover to backup backends if the primary route is unreachable.
                            [ADD] Timezone support when creating tokens.
                            [ADD] Token stats now include expire_at and delivery_at fields.

                        -----------------------------------------------------------------------------------------
                        Version 0.6.21
                        -----------------------------------------------------------------------------------------
                            [FIX] The design has been improved. Proxy functionality is restored. Rate limiting
                                  is now applied per route and per user.

                        -----------------------------------------------------------------------------------------
                        Version 0.6.9
                        -----------------------------------------------------------------------------------------
                            [CLEANCODE] Clean all warning.

                            PS: I'm tired, going to sleep now 🙂 Sorry for deploying so many versions
                                in such a short time but it's better to keep improving, it's not finished yet...

                        -----------------------------------------------------------------------------------------
                        Version 0.6.8
                        -----------------------------------------------------------------------------------------
                            [ADD] Download default config from proxyauth.app
                                  Check build version status via proxyauth.app to detect invalid or yanked versions.
                                  Allows blocking specific versions during the build process if marked as such.

                        -----------------------------------------------------------------------------------------
                        Version 0.6.5
                        -----------------------------------------------------------------------------------------
                            [PERF] Complete rewrite of proxy architecture.
                            [DISABLED] Proxy forwarding via `routes.yml`.
                            [DISABLED] Certificate-based forwarding in `routes.yml` rules.
                            [WORKING] HTTPS forwarding if valid certificates are present.
                            [WORKING] Token validation: invalid/expired tokens are properly handled.
                            [WORKING] HTTP request forwarding is operational.
                            [WORKING] `User-Agent` header rewritten to `ProxyAuth`.
                            [WORKING] Disable/Enable/Redirect logs on loki/local
                            [WORKING] Disable/Enable stats on cmd proxyauth stats
                            [WORKING] Disable/Enable ratelimit over /auth or your rules routes...
                            [ULTRA FAST] Achieves ~ 600k HTTPS requests per second on server hardware.

                        -----------------------------------------------------------------------------------------
                        Version 0.6.1-0.6.3
                        -----------------------------------------------------------------------------------------
                            [TEST] Optimized Configuration.

                        -----------------------------------------------------------------------------------------
                        Version 0.6.0
                        -----------------------------------------------------------------------------------------
                            [ADD] H2 / use HTTPS only / generate certs in /etc/proxyauth/certs/

                        -----------------------------------------------------------------------------------------
                        Version 0.5.34
                        -----------------------------------------------------------------------------------------
                            [REBUILD] Rebuild all proxy conception.

                        -----------------------------------------------------------------------------------------
                        Version 0.5.28
                        -----------------------------------------------------------------------------------------
                            [BUGFIX] Load configuration ratelimit possible disable if key si unset or
                                     request_per_seconds is 0.

                        -----------------------------------------------------------------------------------------
                        Version 0.5.23-0.5.27
                        -----------------------------------------------------------------------------------------
                            [PERF] Improve performance ~ 1 Millions requests per seconds

                        -----------------------------------------------------------------------------------------
                        Version 0.5.22
                        -----------------------------------------------------------------------------------------
                            [Security] Rotate random params

                        -----------------------------------------------------------------------------------------
                        Version 0.5.21
                        -----------------------------------------------------------------------------------------
                            [Security] Better security hash token ID

                        -----------------------------------------------------------------------------------------
                        Version 0.5.20
                        -----------------------------------------------------------------------------------------
                            [Optimized] Better performance

                        -----------------------------------------------------------------------------------------
                        Version 0.5.19
                        -----------------------------------------------------------------------------------------
                            [FIX] ratelimit no detect configuration

                        -----------------------------------------------------------------------------------------
                        Version 0.5.17
                        -----------------------------------------------------------------------------------------
                            [FIX] FIX launch cmd proxyauth stats for user

                        -----------------------------------------------------------------------------------------
                        Version 0.5.15
                        -----------------------------------------------------------------------------------------
                            [FIX] cmd cli stats for routes /adm/stats

                        -----------------------------------------------------------------------------------------
                        Version 0.5.14
                        -----------------------------------------------------------------------------------------
                            [ADD] clear project /adm/stats

                        -----------------------------------------------------------------------------------------
                        Version 0.5.13
                        -----------------------------------------------------------------------------------------
                            [ADD] Route Admin /adm/stats

                        -----------------------------------------------------------------------------------------
                        Version 0.5.12
                        -----------------------------------------------------------------------------------------
                            [ADD] New CLI command `proxyauth stats` to display token usage statistics

                        -----------------------------------------------------------------------------------------
                        Version 0.5.11
                        -----------------------------------------------------------------------------------------
                            [ADD] Token usage stats per user

                        -----------------------------------------------------------------------------------------
                        Version 0.5.10
                        -----------------------------------------------------------------------------------------
                            [ADD] Improved rate limit configuration for proxy routes and the /auth authentication endpoint.

                        -----------------------------------------------------------------------------------------
                        Version 0.5.9
                        -----------------------------------------------------------------------------------------
                            [UPDATE] Launching Actix Web with rate limiting enabled.
                                     Available modes: NO_RATELIMIT_AUTH, NO_RATELIMIT_PROXY,
                                                      RATELIMIT_GLOBAL_ON, RATELIMIT_GLOBAL_OFF.

                        -----------------------------------------------------------------------------------------
                        Version 0.5.8
                        -----------------------------------------------------------------------------------------
                            [BUGFIX] Default launch now correctly uses HTTPS/TLS

                        -----------------------------------------------------------------------------------------
                        Version 0.5.7
                        -----------------------------------------------------------------------------------------
                            [FIX] Improved installation script
                            [ADD] Clearer explanation of rate limiting (wait time in milliseconds)

                        -----------------------------------------------------------------------------------------
                        Version 0.5.6
                        -----------------------------------------------------------------------------------------
                            [FIX] Better compatibility with Alpine and other Linux distributions

                        -----------------------------------------------------------------------------------------
                        Version 0.5.5
                        -----------------------------------------------------------------------------------------
                            [ADD] Introduced new 'prepare' command
                            [ADD] Program now launches as root and creates/uses the 'proxyauth' user to write in /etc/proxyauth
                            [TODO] Documentation is coming to explain this setup
                            [NOTE] First-time usage: run `sudo proxyauth prepare` before launching the app

                        -----------------------------------------------------------------------------------------
                        Version 0.5.4
                        -----------------------------------------------------------------------------------------
                            [ADD] create automatically the file configuration use github repo.

                        -----------------------------------------------------------------------------------------
                        Version 0.5.3
                        -----------------------------------------------------------------------------------------
                            [FIX] Replace host label with app to improve log display in Loki.

                        -----------------------------------------------------------------------------------------
                        Version 0.5.2
                        -----------------------------------------------------------------------------------------
                            [ADD] integration log for loki/Grafana.

                        -----------------------------------------------------------------------------------------
                        Version 0.5.0
                        -----------------------------------------------------------------------------------------
                            [ADD] Experimental feacture forward on https requests.


                        -----------------------------------------------------------------------------------------
                        Version 0.4.2
                        -----------------------------------------------------------------------------------------
                            [FIX] Minor bug over message proxy


                        -----------------------------------------------------------------------------------------
                        Version 0.4.1
                        -----------------------------------------------------------------------------------------
                            [ADD] possible config proxy on file routes.yml


                        -----------------------------------------------------------------------------------------
                        Version 0.4.0
                        -----------------------------------------------------------------------------------------
                            [ADD] ratelimit over routes /auth.
                            [ADD] use auto Argo2 for encrypt passsword in config.json

                        -----------------------------------------------------------------------------------------
                        Version 0.3.5
                        -----------------------------------------------------------------------------------------
                            [SECURITY] Improved security and re-checking of the factor if it exceeds the defined limit.
                            [SECURITY] Use of SHA-256 instead of SHA-1.
                            [SECURITY] Add HMAC SHA-256 over CHACHA20 AED

                        -----------------------------------------------------------------------------------------
                        Version 0.3.4
                        -----------------------------------------------------------------------------------------
                            [REFACTO] Moved the utils method into security.
                            [ADD] Enhanced hash security.

                        -----------------------------------------------------------------------------------------
                        Version 0.3.3
                        -----------------------------------------------------------------------------------------
                            [FIX] Bug with rate limiting when an anonymous user makes requests to unsecured routes (docs, etc.).
                            [ADD] Better logging / error handling when token encryption fails
                                  triggers a warning log message with the source IP.

                        -----------------------------------------------------------------------------------------
                        Version 0.3.2
                        -----------------------------------------------------------------------------------------
                            [ADD] Improved log messages.
                            [ADD] Applied rate limiting only on proxy routes and not on /refresh_token.
                            [ADD] ulimit setting in Docker configuration for better performance.

                        -----------------------------------------------------------------------------------------
                        Version 0.3.1
                        -----------------------------------------------------------------------------------------
                            [ADD] delay_block setting in the config file.

                        -----------------------------------------------------------------------------------------
                        Version 0.3.0
                        -----------------------------------------------------------------------------------------
                            [ADD] Rate limiting per request and per user.

                        -----------------------------------------------------------------------------------------
                        Version 0.2.1
                        -----------------------------------------------------------------------------------------
                            [FIX] Bug related to date handling.
                            [ADD] Added logging via tracing.

                        -----------------------------------------------------------------------------------------
                        Version 0.2.0
                        -----------------------------------------------------------------------------------------
                            Improved user check — users are now checked via an index.
                            [BUG] Date checking issue still present.
                            Improved the /auth route algorithm.
                            Added Dockerfile and docker-compose.yml, built from rust:alpine.

                        -----------------------------------------------------------------------------------------
                        Version 0.1.0
                        -----------------------------------------------------------------------------------------
                            Implemented CHACHA20/SHA1/ROTATE algorithm for token handling.
                            Implemented request forwarding routes.
                            Added configuration files: routes.yml and config.json.
                            [BUG] Date checking issue to be fixed.
                            Added worker execution count handling.
                            [TODO] Improve user checking (ID inside chacha20)
                            (Performance improvement: no need to iterate through all users).

Dependancies Libs

Chargement...