https://github.com/sansneo/au
Highly configurable single static binary local authentication server!
https://github.com/sansneo/au
au authentication jwks
Last synced: 10 days ago
JSON representation
Highly configurable single static binary local authentication server!
- Host: GitHub
- URL: https://github.com/sansneo/au
- Owner: sansneo
- License: mit
- Created: 2025-08-21T15:32:29.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-11-21T10:10:04.000Z (2 months ago)
- Last Synced: 2025-11-21T12:09:25.285Z (2 months ago)
- Topics: au, authentication, jwks
- Language: Go
- Homepage: https://pkg.go.dev/github.com/sansneo/au/
- Size: 304 KB
- Stars: 9
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Audit: audit/ffuf.sh
Awesome Lists containing this project
README
# au
> Hyper configurable local authentication server in a single executable.
Stop reimplementing authentication, it's hard to make it secure and even if you can it's really time consuming.
People would often point you to third party remote solutions or something local like this one.
Introducing `au`, blazingly fast, unopinionated and headless authentication solution!
> [!WARNING]
> This is a toy and very much still in development not to be used for anything in production.
> You gotta love the idea though!
## Usage
Start an authentication API with no extra features enabled.
```sh
au
```
Start an authentication API on port `2300` using an in memory database and TOTP as a MFA method.
```sh
au -p 2300 -d ":memory:" -t
```
All the available options!
```
Usage: au [--port] [--prefix] [--rate-limit] [--database] [--journal-mode] [--pepper] [--bcrypt-cost] [--jwt-issuer] [--jwt-expiry] [--refresh-expiry] [--locking] [--failed-attempts] [--lockout-time] [--totp] [--totp-skew] [--totp-length] [--totp-algorithm] [--smtp] [--smtp-user] [--smtp-password] [--smtp-address] [--smtp-port] [--smtp-from] [--smtp-template] [--origins] [--documentation] [--version]
Options:
--port, -p specifies API port [default: 6900, env: PORT]
--prefix, -u specifies API subrouter prefix [default: /api, env: PREFIX]
--rate-limit, -r specifies a rate limit rule for an endpoint (format '/auth/login:10:1h:3h') [env: RATE_LIMIT]
--database, -d specifies database path (can be ':memory:') [default: ./auth.db, env: DATABASE]
--journal-mode, -j specifies database journal mode (must be 'DELETE', 'WAL', 'TRUNCATE', 'PERSIST', 'MEMORY' or 'OFF') [default: DELETE, env: JOURNAL_MODE]
--pepper, -w specifies an optional password pepper [env: PEPPER]
--bcrypt-cost, -b specifies bcrypt cost factor (must be between 10 and 14) [default: 12, env: BCRYPT_COST]
--jwt-issuer, -i specifies the JWT issuer [default: local, env: JWT_ISSUER]
--jwt-expiry specifies JWT expiry (format 1h, 30m, 15s) [default: 30m, env: JWT_EXPIRY]
--refresh-expiry specifies opaque reference refresh token expiry (format 1h, 30m, 15s) [default: 24h, env: REFRESH_EXPIRY]
--locking, -l specifies whether to enable/disable account locking [default: true, env: LOCKING_ENABLED]
--failed-attempts specifies maximum failed login attempts before account locking [default: 10, env: LOCKING_ATTEMPTS]
--lockout-time specifies account lockout time (format 1h, 30m, 15s) [default: 1h, env: LOCKING_TIME]
--totp, -t specifies whether to enable/disable TOTP as a MFA method [default: false, env: TOTP_ENABLED]
--totp-skew specifies TOTP skew [default: 1, env: TOTP_SKEW]
--totp-length specifies TOTP codes length (should be 6 or 8) [default: 6, env: TOTP_LENGTH]
--totp-algorithm specifies TOTP algorithm (must be 'SHA1', 'SHA256', 'SHA512') [default: SHA1, env: TOTP_ALGORITHM]
--smtp, -s specifies whether to enable/disable SMTP for account verification and recovery [default: false, env: SMTP_ENABLED]
--smtp-user specifies SMTP server user [env: SMTP_USER]
--smtp-password specifies SMTP server user password [env: SMTP_PASSWORD]
--smtp-address specifies SMTP server address [env: SMTP_ADDRESS]
--smtp-port specifies SMTP server port [env: SMTP_PORT]
--smtp-from specifies SMTP from email [env: SMTP_FROM]
--smtp-template specifies path to email HTML template [env: SMTP_TEMPLATE]
--origins, -o specifies CORS origins [env: CORS_ORIGINS]
--documentation specifies whether/disable to serves API documentation [default: false, env: DOCS_ENABLED]
--version, -v show current version and exit
--help, -h display this help and exit
```
## Design
* Runs no matter what and everything is customizable with a flag.
* Follows RFCs and best practicies unless specified differently.
* Has a manual page and an OpenAPI specification optionally served with ScalarUI.
* JWKS instead of JWT secrets by default and Opaque Reference Tokens triggering IP and User Agent validation by default, limiting a stolen JWT's potential damage!
* Extensively audited against the OWASP TOP 10 including BOLA, CSRF and XSS.
* Static analysis and anti debugging in release builds!
* Very well documented and aiming for an high unit testing coverage for each package.
> [!NOTE]
> Can't believe I understand all of these things.
## Installation
Grab a [release](https://github.com/sansneo/au/releases) for your architecture and operating system or do it another way.
### With Go's toolchain installed
```
go install github.com/sansneo/au/cmd/au@latest
```
### From source
```
make
```
### Using Docker
```
docker build -t sansneo/au .
```
## Debugging with Delve
It's an API, so you need to attach to the process using the PID.
```
dlv attach $(pgrep au)
```
## Screenshots
Inspired by modern tools such as [fzf](https://github.com/junegunn/fzf), [rg](https://github.com/BurntSushi/ripgrep) and [fd](https://github.com/sharkdp/fd)
### Contributions
Check out [TODO](./TODO.md) and send a PR for me to review!
#### Bounties
For a big PR I will buy you a Yogurt I like. Motivated yet?