docs: add README and dex custom theme

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-08 13:03:29 +07:00 · 2026-03-08 13:03:29 +07:00 · 69c307e7d6
commit 69c307e7d6
parent 12fd2f2e70
12 changed files with 508 additions and 33 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,148 @@
+# chldapasswd
+
+A self-hosted web portal for LDAP account management. Users can log in, view their profile, change their password, recover a lost password, and manage mail aliases — all without requiring direct LDAP access.
+
+## Features
+
+- **Password change** — authenticated users can update their LDAP password (SHA-512 crypt, minimum 12 chars, requires upper/lower/digit)
+- **Lost password recovery** — sends a one-time reset link via email (token expires in 1 hour)
+- **Profile view** — displays LDAP attributes after login
+- **Mail alias management** — create/delete auto-generated email aliases stored as `mailAlias` in LDAP, exposed via an addy.io-compatible API
+- **HTTP Basic Auth endpoint** (`/auth`) — validates credentials against LDAP, forwards `X-Remote-User` header; suitable for use with nginx `auth_request`
+- **Docker registry anonymous read** — optionally allows unauthenticated `GET`/`HEAD` on registry image paths via `X-Special-Auth` header
+- **Altcha PoW CAPTCHA** — proof-of-work challenge on sensitive forms, no third-party service required
+- **CSRF protection** — token-based on state-changing forms
+- **Rate limiting** — per-IP on login, password change, lost password, and alias API endpoints
+- **Security headers** — CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy
+
+## Building
+
+```sh
+go build -ldflags="-s -w" -o chldapasswd
+```
+
+Requires Go 1.23+. A Drone CI pipeline builds and pushes `nemunaire/chldapasswd:latest` on each push to `master`.
+
+## Usage
+
+```
+chldapasswd [flags] [serve]
+chldapasswd [flags] generate-lost-password-link <uid>
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-bind` | `127.0.0.1:8080` | Listen address |
+| `-baseurl` | `/` | URL prefix (for reverse-proxy subpath deployment) |
+| `-config` | _(none)_ | Path to a JSON config file for LDAP settings |
+| `-public-url` | _(none)_ | Base URL used in password reset emails |
+| `-brand-name` | `chldapasswd` | Brand name shown in the UI |
+| `-brand-logo` | _(none)_ | URL of a logo image shown in the UI |
+| `-addy-api-secret` | _(none)_ | HMAC secret for the alias API |
+| `-dev` | `false` | Development mode: disables HSTS and cookie `Secure` flag |
+
+### Environment variables
+
+All LDAP and SMTP settings can be provided via environment variables (they override CLI flags and config file values):
+
+| Variable | Description |
+|----------|-------------|
+| `LDAP_HOST` | LDAP server hostname |
+| `LDAP_PORT` | LDAP server port |
+| `LDAP_STARTTLS` | Enable STARTTLS (`1`/`on`/`true`) |
+| `LDAP_SSL` | Use LDAPS (`1`/`on`/`true`) |
+| `LDAP_BASEDN` | Base DN for searches |
+| `LDAP_SERVICEDN` | DN of the service account |
+| `LDAP_SERVICE_PASSWORD` | Password of the service account |
+| `LDAP_SERVICE_PASSWORD_FILE` | Path to a file containing the service password |
+| `SMTP_HOST` | SMTP server (leave empty to use local `sendmail`) |
+| `SMTP_PORT` | SMTP port |
+| `SMTP_USER` | SMTP username |
+| `SMTP_PASSWORD` | SMTP password |
+| `SMTP_PASSWORD_FILE` | Path to a file containing the SMTP password |
+| `SMTP_FROM` | Sender address for recovery emails |
+| `PUBLIC_URL` | Public base URL (overrides `-public-url`) |
+| `BRAND_NAME` | Brand name (overrides `-brand-name`) |
+| `BRAND_LOGO` | Brand logo URL (overrides `-brand-logo`) |
+| `ADDY_API_SECRET` | HMAC secret for the alias API |
+| `ALIAS_ALLOWED_DOMAINS` | Comma-separated list of domains users may create aliases under |
+| `DOCKER_REGISTRY_SECRET` | Shared secret for anonymous Docker registry read access |
+
+### JSON config file
+
+The `-config` flag accepts a JSON file whose fields map directly to the `LDAP` struct:
+
+```json
+{
+  "Host": "auth.example.com",
+  "Port": 636,
+  "Ssl": true,
+  "BaseDN": "dc=example,dc=com",
+  "ServiceDN": "cn=svc,ou=services,dc=example,dc=com",
+  "ServicePassword": "secret",
+  "MailHost": "smtp.example.com",
+  "MailPort": 587,
+  "MailUser": "mailer",
+  "MailPassword": "secret",
+  "MailFrom": "noreply@example.com"
+}
+```
+
+## HTTP endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET/POST` | `/` or `/change` | Password change form |
+| `GET/POST` | `/login` | Login form — shows user profile on success |
+| `GET/POST` | `/lost` | Lost password form |
+| `GET/POST` | `/reset` | Password reset via token (from email link) |
+| `GET/POST` | `/auth` | HTTP Basic Auth validation for reverse-proxy use |
+| `POST` | `/api/v1/aliases` | Create a mail alias (addy.io-compatible) |
+| `DELETE` | `/api/v1/aliases/{alias}` | Delete a mail alias |
+| `GET` | `/altcha-challenge` | Fetch a PoW challenge for the Altcha widget |
+
+## Mail alias API
+
+The alias API is compatible with the addy.io API format. Tokens are HMAC-SHA224 signed and encoded in Base32:
+
+```sh
+# Create alias
+curl -X POST https://auth.example.com/api/v1/aliases \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"domain": "example.com"}'
+
+# Delete alias
+curl -X DELETE https://auth.example.com/api/v1/aliases/abc123%40example.com \
+  -H "Authorization: Bearer <token>"
+```
+
+The token for a given `uid` is: `base32(uid + ":" + HMAC-SHA224(apiSecret, uid))`.
+
+Alias creation is disabled unless `ALIAS_ALLOWED_DOMAINS` is set.
+
+## Templates
+
+HTML templates are embedded from the `static/` directory at build time. To customise the UI, edit the files in `static/` before building.
+
+The `dextpl/` directory contains a matching theme for [Dex](https://dexidp.io/) to keep a consistent look across the SSO stack.
+
+## Docker
+
+```sh
+docker run -d \
+  -e LDAP_HOST=auth.example.com \
+  -e LDAP_PORT=636 \
+  -e LDAP_SSL=true \
+  -e LDAP_BASEDN=dc=example,dc=com \
+  -e LDAP_SERVICEDN=cn=svc,ou=services,dc=example,dc=com \
+  -e LDAP_SERVICE_PASSWORD=secret \
+  -e SMTP_HOST=smtp.example.com \
+  -e SMTP_PORT=587 \
+  -e SMTP_FROM=noreply@example.com \
+  -e PUBLIC_URL=https://auth.example.com \
+  -p 8080:8080 \
+  nemunaire/chldapasswd
+```
--- a/dextpl/approval.html
+++ b/dextpl/approval.html
@ -0,0 +1,44 @@
+{{ template "header.html" . }}
+
+<div class="theme-panel">
+  <h2 class="theme-heading">Grant Access</h2>
+
+  <hr class="dex-separator">
+  <div>
+    {{ if .Scopes }}
+    <div class="dex-subtle-text">{{ .Client }} would like to:</div>
+    <ul class="dex-list">
+      {{ range $scope := .Scopes }}
+      <li>{{ $scope }}</li>
+      {{ end }}
+    </ul>
+    {{ else }}
+    <div class="dex-subtle-text">{{ .Client }} has not requested any personal information</div>
+    {{ end }}
+  </div>
+  <hr class="dex-separator">
+
+  <div>
+    <div class="theme-form-row">
+      <form method="post">
+        <input type="hidden" name="req" value="{{ .AuthReqID }}"/>
+        <input type="hidden" name="approval" value="approve">
+        <button type="submit" class="dex-btn theme-btn--success">
+            <span class="dex-btn-text">Grant Access</span>
+        </button>
+      </form>
+    </div>
+    <div class="theme-form-row">
+      <form method="post">
+        <input type="hidden" name="req" value="{{ .AuthReqID }}"/>
+        <input type="hidden" name="approval" value="rejected">
+        <button type="submit" class="dex-btn theme-btn-provider">
+            <span class="dex-btn-text">Cancel</span>
+        </button>
+      </form>
+    </div>
+  </div>
+
+</div>
+
+{{ template "footer.html" . }}
--- a/dextpl/device.html
+++ b/dextpl/device.html
@ -0,0 +1,23 @@
+{{ template "header.html" . }}
+
+<div class="theme-panel">
+  <h2 class="theme-heading">Enter User Code</h2>
+  <form method="post" action="{{ .PostURL }}">
+    <div class="theme-form-row">
+      {{ if( .UserCode  )}}
+      <input tabindex="2" required id="user_code" name="user_code" type="text" class="theme-form-input" autocomplete="off" value="{{.UserCode}}" {{ if .Invalid }} autofocus {{ end }}/>
+      {{ else }}
+      <input tabindex="2" required id="user_code" name="user_code" type="text" class="theme-form-input" placeholder="XXXX-XXXX" autocomplete="off"  {{ if .Invalid }} autofocus {{ end }}/>
+      {{ end }}
+    </div>
+
+    {{ if .Invalid }}
+    <div id="login-error" class="dex-error-box">
+      Invalid or Expired User Code
+    </div>
+    {{ end }}
+    <button tabindex="3" id="submit-login" type="submit" class="dex-btn theme-btn--primary">Submit</button>
+  </form>
+</div>
+
+{{ template "footer.html" . }}
--- a/dextpl/device_success.html
+++ b/dextpl/device_success.html
@ -0,0 +1,8 @@
+{{ template "header.html" . }}
+
+<div class="theme-panel">
+  <h2 class="theme-heading">Login Successful for {{ .ClientName }}</h2>
+  <p>Return to your device to continue</p>
+</div>
+
+{{ template "footer.html" . }}
--- a/dextpl/error.html
+++ b/dextpl/error.html
@ -0,0 +1,8 @@
+{{ template "header.html" . }}
+
+<div class="theme-panel">
+  <h2 class="theme-heading">{{ .ErrType }}</h2>
+  <p>{{ .ErrMsg }}</p>
+</div>
+
+{{ template "footer.html" . }}
--- a/dextpl/footer.html
+++ b/dextpl/footer.html
@ -0,0 +1,3 @@
+    </div>
+  </body>
+</html>
--- a/dextpl/header.html
+++ b/dextpl/header.html
@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+    <title>{{ issuer }}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link href="{{ url .ReqPath "static/main.css" }}" rel="stylesheet">
+    <link href="{{ url .ReqPath "theme/styles.css" }}" rel="stylesheet">
+    <link rel="icon" href="{{ url .ReqPath "theme/favicon.png" }}">
+  </head>
+
+  <body class="theme-body">
+    <div class="theme-navbar">
+      <div class="theme-navbar__logo-wrap">
+        <img class="theme-navbar__logo" src="{{ url .ReqPath logo }}">
+      </div>
+    </div>
+
+    <div class="dex-container">
--- a/dextpl/login.html
+++ b/dextpl/login.html
@ -0,0 +1,19 @@
+{{ template "header.html" . }}
+
+<div class="theme-panel">
+  <h2 class="theme-heading">Log in to {{ issuer }} </h2>
+  <div>
+    {{ range $c := .Connectors }}
+      <div class="theme-form-row">
+        <a href="{{ $c.URL }}" target="_self">
+          <button class="dex-btn theme-btn-provider">
+            <span class="dex-btn-icon dex-btn-icon--{{ $c.Type }}"></span>
+            <span class="dex-btn-text">Log in with {{ $c.Name }}</span>
+          </button>
+        </a>
+      </div>
+    {{ end }}
+  </div>
+</div>
+
+{{ template "footer.html" . }}
--- a/dextpl/main.css
+++ b/dextpl/main.css
@ -0,0 +1,153 @@
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+}
+
+.dex-container {
+  color: #333;
+  margin: 45px auto;
+  max-width: 500px;
+  min-width: 320px;
+  text-align: center;
+}
+
+.dex-btn {
+  border-radius: 4px;
+  border: 0;
+  box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.2), 0 1px 2px rgba(0, 0, 0, 0.25), 0 0 1px rgba(0, 0, 0, 0.25);
+  cursor: pointer;
+  font-size: 16px;
+  padding: 0;
+}
+
+.dex-btn:focus {
+  outline: none;
+}
+
+.dex-btn:active {
+  box-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);
+  outline: none;
+}
+
+.dex-btn:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.dex-btn-icon {
+  background-position: center;
+  background-repeat: no-repeat;
+  background-size: 24px;
+  border-radius: 4px 0 0 4px;
+  float: left;
+  height: 36px;
+  margin-right: 5px;
+  width: 36px;
+}
+
+.dex-btn-icon--google {
+  background-color: #FFFFFF;
+  background-image: url(../static/img/google-icon.svg);;
+}
+
+.dex-btn-icon--local {
+  background-color: #84B6EF;
+  background-image: url(../static/img/email-icon.svg);
+}
+
+.dex-btn-icon--gitea {
+  background-color: #F5F5F5;
+  background-image: url(../static/img/gitea-icon.svg);
+}
+
+.dex-btn-icon--github {
+  background-color: #F5F5F5;
+  background-image: url(../static/img/github-icon.svg);
+}
+
+.dex-btn-icon--gitlab {
+  background-color: #F5F5F5;
+  background-image: url(../static/img/gitlab-icon.svg);
+  background-size: contain;
+}
+
+.dex-btn-icon--keystone {
+  background-color: #F5F5F5;
+  background-image: url(../static/img/keystone-icon.svg);
+  background-size: contain;
+}
+
+.dex-btn-icon--oidc {
+  background-color: #EBEBEE;
+  background-image: url(../static/img/oidc-icon.svg);
+  background-size: contain;
+}
+
+.dex-btn-icon--bitbucket-cloud {
+  background-color: #205081;
+  background-image: url(../static/img/bitbucket-icon.svg);
+}
+
+.dex-btn-icon--atlassian-crowd {
+  background-color: #CFDCEA;
+  background-image: url(../static/img/atlassian-crowd-icon.svg);
+}
+
+.dex-btn-icon--ldap {
+  background-color: #84B6EF;
+  background-image: url(../static/img/ldap-icon.svg);
+}
+
+.dex-btn-icon--saml {
+  background-color: #84B6EF;
+  background-image: url(../static/img/saml-icon.svg);
+}
+
+.dex-btn-icon--linkedin {
+  background-image: url(../static/img/linkedin-icon.svg);
+  background-size: contain;
+}
+
+.dex-btn-icon--microsoft {
+  background-image: url(../static/img/microsoft-icon.svg);
+}
+
+.dex-btn-text {
+  font-weight: 600;
+  line-height: 36px;
+  padding: 6px 12px;
+  text-align: center;
+}
+
+.dex-subtle-text {
+  color: #999;
+  font-size: 12px;
+}
+
+.dex-separator {
+  color: #999;
+}
+
+.dex-list {
+  color: #999;
+  display: inline-block;
+  font-size: 12px;
+  list-style: circle;
+  text-align: left;
+}
+
+.dex-error-box {
+  background-color: #DD1327;
+  color: #fff;
+  font-size: 14px;
+  font-weight: normal;
+  max-width: 320px;
+  padding: 4px 0;
+}
+
+.dex-error-box {
+  margin: 20px auto;
+}
--- a/dextpl/oob.html
+++ b/dextpl/oob.html
@ -0,0 +1,9 @@
+{{ template "header.html" . }}
+
+<div class="theme-panel">
+  <h2 class="theme-heading">Login Successful</h2>
+  <p>Please copy this code, switch to your application and paste it there:</p>
+  <input type="text" class="theme-form-input" value="{{ .Code }}" />
+</div>
+
+{{ template "footer.html" . }}
--- a/dextpl/password.html
+++ b/dextpl/password.html
@ -0,0 +1,43 @@
+{{ template "header.html" . }}
+
+<div class="theme-panel">
+  <h2 class="theme-heading">Log in to Your Account</h2>
+  <form method="post" action="{{ .PostURL }}">
+    <div class="theme-form-row">
+      <div class="theme-form-label">
+        <label for="login">{{ .UsernamePrompt }}</label>
+      </div>
+	  <input tabindex="1" required id="login" name="login" type="text" class="theme-form-input" placeholder="{{ .UsernamePrompt | lower }}" {{ if .Username }} value="{{ .Username }}" {{ else }} autofocus {{ end }}/>
+    </div>
+    <div class="theme-form-row">
+      <div class="theme-form-label">
+        <label for="password">Password</label>
+      </div>
+	  <input tabindex="2" required id="password" name="password" type="password" class="theme-form-input" placeholder="password" {{ if .Invalid }} autofocus {{ end }}/>
+    </div>
+
+    {{ if .Invalid }}
+      <div id="login-error" class="dex-error-box">
+        Invalid {{ .UsernamePrompt }} and password.
+      </div>
+    {{ end }}
+
+    <button tabindex="3" id="submit-login" type="submit" class="dex-btn theme-btn--primary">Login</button>
+
+  </form>
+  {{ if .BackLink }}
+  <div class="theme-link-back">
+    <a class="dex-subtle-text" href="{{ .BackLink }}">Select another login method.</a>
+  </div>
+  {{ end }}
+</div>
+
+
+<script type="text/javascript">
+  document.querySelector('form').onsubmit = function(e) {
+    var el = document.querySelector('#submit-login');
+    el.setAttribute('disabled', 'disabled');
+  };
+</script>
+
+{{ template "footer.html" . }}
--- a/main.go
+++ b/main.go
@ -17,7 +17,7 @@ import (
 	"syscall"
 )

-var myPublicURL = "https://ldap.nemunai.re"
+var myPublicURL = ""
 var devMode bool
 var brandName = "chldapasswd"
 var brandLogo = ""
@ -35,7 +35,7 @@ var myLDAP = LDAP{
 	Port:     389,
 	BaseDN:   "dc=example,dc=com",
 	MailPort: 587,
-	MailFrom: "noreply@nemunai.re",
+	MailFrom: "noreply@example.com",
 }

 type ResponseWriterPrefix struct {
@ -79,37 +79,34 @@ func StripPrefix(prefix string, h http.Handler) http.Handler {
 }

 func main() {
-	var bind = flag.String("bind", "127.0.0.1:8080", "Bind port/socket")
-	var baseURL = flag.String("baseurl", "/", "URL prepended to each URL")
-	var configfile = flag.String("config", "", "path to the configuration file")
-	var publicURL = flag.String("public-url", myPublicURL, "Public base URL used in password reset emails")
-	var dev = flag.Bool("dev", false, "Development mode: disables HSTS and cookie Secure flag for local HTTP testing")
-	var bname = flag.String("brand-name", "chldapasswd", "Brand name displayed in the UI")
-	var blogo = flag.String("brand-logo", "", "URL of brand logo displayed in the UI (added to CSP img-src)")
-	flag.Parse()
+	baseURL := "/"
+	bind := "127.0.0.1:8080"

-	myPublicURL = *publicURL
-	devMode = *dev
-	brandName = *bname
-	brandLogo = *blogo
 	if val, ok := os.LookupEnv("BRAND_NAME"); ok {
 		brandName = val
 	}
 	if val, ok := os.LookupEnv("BRAND_LOGO"); ok {
 		brandLogo = val
 	}
+
+	var configfile = flag.String("config", "", "path to the configuration file")
+	flag.StringVar(&baseURL, "baseurl", baseURL, "URL prepended to each URL")
+	flag.StringVar(&bind, "bind", bind, "Bind port/socket")
+	flag.StringVar(&brandName, "brand-name", brandName, "Brand name displayed in the UI")
+	flag.StringVar(&brandLogo, "brand-logo", brandLogo, "URL of brand logo displayed in the UI (added to CSP img-src)")
+	flag.BoolVar(&devMode, "dev", devMode, "Development mode: disables HSTS and cookie Secure flag for local HTTP testing")
+	flag.StringVar(&myPublicURL, "public-url", myPublicURL, "Public base URL used in password reset emails")
+	flag.Parse()
+
 	if devMode {
 		log.Println("WARNING: running in development mode — security features relaxed, do not use in production")
 	}

 	// Sanitize options
-	log.Println("Checking paths...")
-	if *baseURL != "/" {
-		tmp := path.Clean(*baseURL)
-		baseURL = &tmp
+	if baseURL != "/" {
+		baseURL = path.Clean(baseURL)
 	} else {
-		tmp := ""
-		baseURL = &tmp
+		baseURL = ""
 	}

 	// Load config file
@ -231,20 +228,20 @@ func main() {
 	signal.Notify(interrupt, os.Interrupt, syscall.SIGTERM)

 	// Register handlers
-	http.HandleFunc(fmt.Sprintf("GET %s/altcha.min.js", *baseURL), serveAltchaJS)
-	http.HandleFunc(fmt.Sprintf("GET %s/style.css", *baseURL), serveStyleCSS)
-	http.HandleFunc(fmt.Sprintf("GET %s/altcha-challenge", *baseURL), serveAltchaChallenge)
-	http.HandleFunc(fmt.Sprintf("%s/{$}", *baseURL), changePassword)
-	http.HandleFunc(fmt.Sprintf("POST %s/api/v1/aliases", *baseURL), addyAliasAPI)
-	http.HandleFunc(fmt.Sprintf("DELETE %s/api/v1/aliases/{alias}", *baseURL), addyAliasAPIDelete)
-	http.HandleFunc(fmt.Sprintf("%s/auth", *baseURL), httpBasicAuth)
-	http.HandleFunc(fmt.Sprintf("%s/login", *baseURL), tryLogin)
-	http.HandleFunc(fmt.Sprintf("%s/change", *baseURL), changePassword)
-	http.HandleFunc(fmt.Sprintf("%s/reset", *baseURL), resetPassword)
-	http.HandleFunc(fmt.Sprintf("%s/lost", *baseURL), lostPassword)
+	http.HandleFunc(fmt.Sprintf("GET %s/altcha.min.js", baseURL), serveAltchaJS)
+	http.HandleFunc(fmt.Sprintf("GET %s/style.css", baseURL), serveStyleCSS)
+	http.HandleFunc(fmt.Sprintf("GET %s/altcha-challenge", baseURL), serveAltchaChallenge)
+	http.HandleFunc(fmt.Sprintf("%s/{$}", baseURL), changePassword)
+	http.HandleFunc(fmt.Sprintf("POST %s/api/v1/aliases", baseURL), addyAliasAPI)
+	http.HandleFunc(fmt.Sprintf("DELETE %s/api/v1/aliases/{alias}", baseURL), addyAliasAPIDelete)
+	http.HandleFunc(fmt.Sprintf("%s/auth", baseURL), httpBasicAuth)
+	http.HandleFunc(fmt.Sprintf("%s/login", baseURL), tryLogin)
+	http.HandleFunc(fmt.Sprintf("%s/change", baseURL), changePassword)
+	http.HandleFunc(fmt.Sprintf("%s/reset", baseURL), resetPassword)
+	http.HandleFunc(fmt.Sprintf("%s/lost", baseURL), lostPassword)

 	srv := &http.Server{
-		Addr:    *bind,
+		Addr:    bind,
 		Handler: securityHeaders(http.DefaultServeMux),
 	}

@ -253,7 +250,7 @@ func main() {
 		log.Fatal(srv.ListenAndServe())
 	}()
 	log.Printf("Using LDAP server at %s:%d (baseDN: %s)", myLDAP.Host, myLDAP.Port, myLDAP.BaseDN)
-	log.Printf("Ready, listening on %s", *bind)
+	log.Printf("Ready, listening on %s", bind)

 	// Wait shutdown signal
 	<-interrupt