AuthTranslator

AuthTranslator

AuthTranslator is a lightweight, pluggable reverse‑proxy that swaps short‑lived caller credentials for the long‑lived tokens third‑party APIs expect – and it can do the opposite on the way back in. “Stop sprinkling API keys around; translate auth at the edge instead.”

✨ Key ideas

🚀 30‑second quick‑start

1. Run the proxy (Docker)

docker run --rm -p 8080:8080 \
  -e SLACK_TOKEN=demo-token \
  -v $(pwd)/examples:/conf \
  ghcr.io/winhowes/authtranslator:latest \
    -config /conf/config.yaml -allowlist /conf/allowlist.yaml -denylist /conf/denylist.yaml

Or run from source:

go run ./app -config examples/config.yaml -allowlist examples/allowlist.yaml -denylist examples/denylist.yaml

1. Curl through the proxy

curl -H "Host: slack" \
     -H "X-Auth: demo-token" \
     -H "Content-Type: application/json" \
     --data '{"channel": "#general", "username": "AuthTranslator", "text": "Hello from AuthTranslator"}' \
     http://localhost:8080/api/chat.postMessage
# alternatively set `X-AT-Int: slack` if you can’t change the Host header

🗺️ How it fits together

graph LR
  subgraph Your VPC
    Caller([Caller])
    AuthT[AuthTranslator]
  end
  Caller -->|short‑lived token| AuthT
  AuthT -->|long‑lived API key| Slack(Slack API)

1. Auth plug‑in validates + strips caller credential → forwards request allowing your services to use short lived credentials when sending requests to or receiving requests from 3rd parties.
2. The allowlist enforces either capability‑based rules or precise filters on path, method, query params, headers, and JSON‑body or form‑data keys.

📄 Configuration overview

AuthTranslator eats YAML (or pure JSON) for two files:

Example snippets live under examples/ and a full JSON‑Schema is in schemas/ – CI fails if you drift.

Secret back‑ends

Secrets can be pulled from several providers:

• env: SLACK_TOKEN=…
• file: path to an on‑disk file
• k8s: Kubernetes secrets
• gcp: Google Cloud KMS
• aws: AWS Secrets Manager
• azure: Azure Key Vault
• vault: HashiCorp Vault

Need another store? Writing a plug‑in takes ~50 LoC – see app/secrets/plugins/env.

🔧 CLI helpers

# List loaded integrations
go run ./cmd/integrations list

# Add a Slack integration from env vars
go run ./cmd/integrations slack \
  -token env:SLACK_TOKEN -signing-secret env:SLACK_SIGNING

Also see cmd/allowlist for CRUD operations on the allowlist.

📊 Observability & ops

Official container images include a Docker HEALTHCHECK that polls the health endpoint; the container reports healthy once it returns 200.

📚 Documentation map

• Docs home – /docs – deep dives, secret back‑ends, Terraform, plug‑in guides.
• Examples – /examples – minimal runnable configs.
• Helm chart – charts/authtranslator – helm install authtranslator charts/authtranslator in one line.

🛠️ Development

make precommit  # fmt + vet + lint
make test       # run unit tests
make tidy       # update go.mod/go.sum
make ci         # run full checks + tests with coverage
make docker     # build container

• Requires Go 1.24+.
• Run golangci‑lint run to match CI.

🤝 Contributing & security

Found a bug? Have an auth plug-in idea? Open an issue or PR – but please read CONTRIBUTING.md first. Security issues? Email [email protected] – see SECURITY.md.

📝 License

MIT © Winston Howes & contributors.