Authorizer

Open-source authentication and authorization for your applications.
Bring your own database and stay in control of user data.

Documentation · OAuth 2.0 / OIDC · v1 → v2 migration · Contributing · Discord

Authorizer is an open-source authentication and authorization server you can self-host. Connect any supported database (13+ backends including Postgres, MySQL, SQLite, SQL Server, YugaByte, MariaDB, Cassandra, ScyllaDB, MongoDB, ArangoDB, DynamoDB, and Couchbase) and run OAuth2/OIDC, social login, MFA, magic links, RBAC, webhooks, and email templates from one place.

v2 note: Authorizer v2 uses CLI arguments for all configuration. The server does not read from .env or OS environment variables. Pass config when starting the binary (e.g. ./authorizer --client-id=... --client-secret=...). See MIGRATION.md.

Quick start (local)

Prerequisites: Go ≥ 1.24 (see go.mod).

git clone https://github.com/authorizerdev/authorizer.git
cd authorizer
make dev

make dev runs the server with SQLite and development defaults (RS256 keys, sample client credentials). Open the URL printed in the logs (default port 8080) and sign in with --admin-secret (admin in dev).

For production builds, tests, and Docker, see Getting Started below.

Introduction

We offer the following functionality

• ✅ Sign-in / Sign-up with email ID and password
• ✅ Secure session management
• ✅ Email verification
• ✅ OAuth2 and OpenID compatible APIs
• ✅ APIs to update profile securely
• ✅ Forgot password flow using email
• ✅ Social logins (Google, Github, Facebook, LinkedIn, Apple more coming soon)
• ✅ Role-based access management
• ✅ Password-less login with magic link login
• ✅ Multi factor authentication
• ✅ Email templating
• ✅ Webhooks

Roadmap

• VueJS SDK
• Svelte SDK
• Golang SDK
• React Native SDK
• Flutter SDK
• Android Native SDK
• iOS native SDK
• Python SDK
• PHP SDK
• WordPress plugin
• Kubernetes Helm Chart
• Local Stack
• AMI
• Digital Ocean Droplet
• Azure
• Render
• Edge Deployment using Fly.io
• Password-less login with mobile number and OTP SMS

Getting Started

Step 1: Get Authorizer Instance

Deploy Production Ready Instance

Deploy production ready Authorizer instance using one click deployment options available below

Infra provider	One-click link	Additional information
Railway.app		docs
Heroku		docs
Render		docs
Koyeb		docs
RepoCloud		docs
Alibaba Cloud		docs

Deploy Authorizer Using Source Code

This guide helps you practice using Authorizer to evaluate it before you use it in a production environment. It includes instructions for installing the Authorizer server in local or standalone mode.

Prerequisites

• OS: Linux or macOS or Windows
• Go >= 1.24 (see go.mod)
• Node.js >= 18 and npm (only if building the web app and dashboard)

Project Setup

1. Fork the authorizer repository (skip if you already have access)
2. Clone: git clone https://github.com/authorizerdev/authorizer.git (or your fork URL)
3. cd authorizer
4. Fastest path: make dev — SQLite, RS256 dev keys, sample OAuth client (see Quick start)
5. Full build: make build (or go build -o build/authorizer .); optionally make build-app and make build-dashboard
6. Custom flags instead of make dev:

./build/authorizer \
  --database-type=sqlite \
  --database-url=test.db \
  --jwt-type=HS256 \
  --jwt-secret=test \
  --admin-secret=admin \
  --client-id=123456 \
  --client-secret=secret

v2: The server does not read from .env. All configuration must be passed as CLI arguments. See MIGRATION.md for the full mapping of env vars to flags.

Run with Docker

The default image runs as non-root (UID 65532). Writable mounts (SQLite under /authorizer/data, etc.) are usually root-owned, so pick one of:

1. Run as root for that container (simplest for local SQLite + volumes):

   docker run -p 8080:8080 -u root \
     -v authorizer_data:/authorizer/data \
     lakhansamani/authorizer \
     --database-type=sqlite \
     --database-url=/authorizer/data/data.db \
     --client-id=123456 \
     --client-secret=secret \
     --admin-secret=admin \
     --jwt-type=HS256 \
     --jwt-secret=test

2. Keep non-root and make the mount writable by 65532 (good for production-style bind mounts):

   mkdir -p ./data && sudo chown -R 65532:65532 ./data
   docker run -p 8080:8080 \
     -v "$(pwd)/data:/authorizer/data" \
     lakhansamani/authorizer \
     --database-type=sqlite \
     --database-url=/authorizer/data/data.db \
     ...

3. Build from source with the root target (no -u at run time):

   docker build --target final-root -t authorizer:root .
   docker run -p 8080:8080 -v authorizer_data:/authorizer/data authorizer:root \
     --database-type=sqlite --database-url=/authorizer/data/data.db ...

• Port 8080 serves the app and GraphQL; use -p 8080:8080 to expose it.
• Volume authorizer_data persists the SQLite DB; use a named volume or a host path (e.g. -v $(pwd)/data:/authorizer/data).
• All config is passed as CLI arguments (the image uses ENTRYPOINT ["./authorizer"] so args after the image name go to the binary). See MIGRATION.md for the full list of flags.

Database on your laptop (Postgres, MySQL, etc.)

Inside a container, localhost / 127.0.0.1 is the container itself, not your machine. Use a host alias instead:

• Docker Desktop (macOS / Windows): use host.docker.internal in --database-url or --database-host (built in).

  docker run -p 8080:8080 lakhansamani/authorizer \
    --database-type=postgres \
    --database-url="postgres://user:pass@host.docker.internal:5432/dbname?sslmode=disable" \
    ...

• Linux (Docker Engine): add the same hostname so it resolves to the host:

  docker run -p 8080:8080 --add-host=host.docker.internal:host-gateway \
    lakhansamani/authorizer \
    --database-type=postgres \
    --database-url="postgres://user:pass@host.docker.internal:5432/dbname?sslmode=disable" \
    ...

• Alternative on Linux: use the docker bridge gateway IP (often 172.17.0.1) if your DB listens on 0.0.0.0, or run with --network host so the container shares the host network (then localhost works; port mapping -p is not used the same way).

Ensure the database accepts non-localhost connections (e.g. listen_addresses in Postgres, bind address in MySQL) and that your OS firewall allows the Docker subnet.

Extending the image with env-based config (e.g. Railway): If you FROM lakhansamani/authorizer and use a shell-form CMD so that env vars are expanded at runtime, you must override ENTRYPOINT in your Dockerfile or the binary will receive /bin/sh and -c as arguments and fail. Use:

FROM lakhansamani/authorizer:2.0.0-rc.1
# v2 uses CLI arguments only. Railway (etc.) inject env vars; shell form CMD expands them at runtime.
# Override ENTRYPOINT so CMD is run by a shell; otherwise the base ENTRYPOINT would receive /bin/sh -c "..." as args.
ENTRYPOINT ["/bin/sh", "-c"]
CMD ./authorizer \
  --database-type="$${DATABASE_TYPE:-postgres}" \
  --database-url="$${DATABASE_URL}" \
  --client-id="$${CLIENT_ID}" \
  --client-secret="$${CLIENT_SECRET}" \
  --admin-secret="$${ADMIN_SECRET}" \
  ...

Use $$ in the Dockerfile so Docker does not expand $VAR at build time.

Deploy Authorizer using binaries

Deploy / Try Authorizer using binaries. With each Authorizer Release, binaries are baked with required deployment files and bundled. You can download a specific version for the following operating systems:

• macOS (amd64, arm64)
• Linux (amd64, arm64)

Download and unzip bundle

• Download the bundle for your OS/arch from the release page

Note: For Windows, we recommend running Authorizer via Docker.

• Unzip (Mac / Linux):

  tar -zxf authorizer-VERSION-OS-ARCH.tar.gz
  cd authorizer-VERSION-OS-ARCH

Start Authorizer

• Run the binary with required CLI arguments:

  ./authorizer \
    --database-type=sqlite \
    --database-url=test.db \
    --jwt-type=HS256 \
    --jwt-secret=test \
    --admin-secret=admin \
    --client-id=123456 \
    --client-secret=secret

v2: The binary is named authorizer (not server). Configuration is passed via CLI arguments; .env is not read. On macOS you may need: xattr -d com.apple.quarantine authorizer

Step 2: Setup Instance

• Open the Authorizer instance endpoint in your browser
• Sign in as admin using the --admin-secret you configured at startup

v2: Environment variables are not configurable from the dashboard. All configuration is set at startup via CLI arguments. See MIGRATION.md for the full list of flags.

Things to consider

• For social logins, you will need respective social platform key and secret
• For having verified users, you will need an SMTP server with an email address and password using which system can send emails. The system will send a verification link to an email address. Once an email is verified then, only able to access it.

  Note: One can always disable the email verification to allow open sign up, which is not recommended for production as anyone can use anyone's email address 😅

• For persisting user sessions, you will need Redis URL (not in case of railway app). If you do not configure a Redis server, sessions will be persisted until the instance is up or not restarted. For better response time on authorization requests/middleware, we recommend deploying Redis on the same infra/network as your authorizer server.

Testing

• Check the testing instructions here

Integrating into your website

This example demonstrates how you can use [@authorizerdev/authorizer-js](/authorizer-js/getting-started) CDN version and have login ready for your site in few seconds. You can also use the ES module version of [@authorizerdev/authorizer-js](/authorizer-js/getting-started) or framework-specific versions like [@authorizerdev/authorizer-react](/authorizer-react/getting-started)

Copy the following code in html file

Note: Change AUTHORIZER_URL in the below code with your authorizer URL. Also, you can change the logout button component

<script src="https://unpkg.com/@authorizerdev/authorizer-js/lib/authorizer.min.js"></script>

<script type="text/javascript">
	const authorizerRef = new authorizerdev.Authorizer({
		authorizerURL: `YOUR_AUTHORIZER_INSTANCE_URL`,
		redirectURL: window.location.origin,
		clientID: 'YOUR_CLIENT_ID', // value of --client-id flag used to start the server
	});

	// use the button selector as per your application
	const logoutBtn = document.getElementById('logout');
	logoutBtn.addEventListener('click', async function () {
		await authorizerRef.logout();
		window.location.href = '/';
	});

	async function onLoad() {
		const res = await authorizerRef.authorize({
			response_type: 'code',
			use_refresh_token: false,
		});
		if (res && res.access_token) {
			// you can use user information here, eg:
			const user = await authorizerRef.getProfile({
				Authorization: `Bearer ${res.access_token}`,
			});
			const userSection = document.getElementById('user');
			const logoutSection = document.getElementById('logout-section');
			logoutSection.classList.toggle('hide');
			userSection.innerHTML = `Welcome, ${user.email}`;
		}
	}
	onLoad();
</script>

---

Support my work