Tiny Auth: The Lightweight Authentication Middleware for your Homelab

Authentication can be a headache—complex setups, heavy frameworks, or clunky interfaces that make you want to pull your hair out. But what if I told you there’s a super lightweight, easy-to-use solution that’s been making waves in the open-source world? This is Tiny Auth, a minimal authorization middleware that does exactly what it promises: keeps things simple, secure, and fast.

In this article, we’re diving deep into Tiny Auth—what it is, why it’s awesome, how it stacks up against other tools like Oralia and Authentik, and how you can set it up yourself. We’ll walk through its key features, configuration steps, and even explore some advanced use cases like OAuth integration and multi-factor authentication (MFA). Plus, we’ll touch on why this project, built by a 15-year-old developer, has skyrocketed to 1.6K GitHub stars in just a few months. Buckle up—it’s going to be a fun ride!

What Is Tiny Auth?

Tiny Auth is an open-source authentication middleware designed to sit in front of your web services and handle user logins securely. Think of it as a bouncer for your apps: it checks who’s allowed in before letting them access your services. What makes Tiny Auth stand out is its lightweight design. Unlike some beefy authentication frameworks that require tons of resources, Tiny Auth is built to be minimal, fast, and easy to deploy—perfect for homelab setups, small projects, or even larger apps where you don’t want authentication to slow things down.

At its core, Tiny Auth integrates with Traefik, a popular reverse proxy, to manage authentication for any service you put behind it. Want to secure your IT Tools dashboard, Jellyfin media server, or a custom app? Tiny Auth lets you slap a login screen in front of them with minimal fuss. It supports username/password logins, OAuth providers (like GitHub and Google), and even multi-factor authentication using TOTP (Time-based One-Time Passwords). Oh, and did I mention it’s ridiculously easy to set up with Docker Compose? Yeah, it’s that kind of project.

The project’s growth is another reason it’s worth talking about. Since January, Tiny Auth has exploded in popularity, racking up 1.6K stars on GitHub. Part of the buzz comes from its creator—a 15-year-old developer who’s somehow managed to build a tool that’s both powerful and user-friendly. That’s the kind of talent that makes you feel like you need to step up your game!

Why Choose Tiny Auth?

Before we get into the nitty-gritty of setting it up, let’s talk about why Tiny Auth might be the right choice for you. Authentication tools are a dime a dozen—Keycloak, Authentik, Oralia, you name it—so what makes Tiny Auth special? Here are a few reasons it’s turning heads:

1. Lightweight and Fast: Tiny Auth is designed to use minimal resources. It’s not going to hog your CPU or RAM, which is a big win for self-hosted setups on a Raspberry Pi or a small VPS.
2. Dead Simple Setup: If you’re familiar with Docker, you’ll be up and running in minutes. The project includes straightforward Docker Compose files, and configuration is mostly done through environment variables.
3. Traefik Integration: Tiny Auth plays beautifully with Traefik, a modern reverse proxy that’s already popular in the self-hosting community. It uses Traefik’s forwardAuth middleware to handle authentication, making it super flexible.
4. OAuth Support: Want to let users log in with GitHub, Google, or other providers? Tiny Auth has you covered with easy-to-configure OAuth integration.
5. Multi-Factor Authentication: Security matters, and Tiny Auth supports TOTP-based MFA, so you can add an extra layer of protection without breaking a sweat.
6. Active Development: The project is evolving fast, with new features and improvements being added regularly. Plus, the community is growing, which means more support and ideas.
7. Built by a Teen Genius: Okay, this isn’t a technical reason, but come on—a 15-year-old building something this cool? That’s inspiring and a testament to the project’s potential.

Compared to alternatives like Oralia or Authentik, Tiny Auth is less feature-heavy but makes up for it with simplicity. Oralia, for example, is great for complex setups with fine-grained access control, but it can feel overwhelming if you just need a login screen. Authentik, on the other hand, is a full-blown identity provider with tons of bells and whistles—perfect for enterprises but overkill for a homelab. Tiny Auth strikes a balance: it’s minimal enough for small projects but powerful enough to secure real-world services.

Getting Started: What You’ll Need

Ready to give Tiny Auth a spin? Before we dive into the setup, let’s make sure you’ve got everything you need. Don’t worry—it’s not a long list:

• A Server or Machine: This could be a VPS, a home server, or even a Raspberry Pi. Tiny Auth is lightweight, so you don’t need a beastly machine.
• Docker and Docker Compose: Tiny Auth is distributed as a Docker image, and the easiest way to deploy it is with Docker Compose.
• Traefik Reverse Proxy: Since Tiny Auth relies on Traefik’s forwardAuth middleware, you’ll need Traefik set up as your reverse proxy. If you’re new to Traefik, don’t sweat it—we’ll cover the basics.
• A Domain or DNS Setup: For OAuth to work smoothly (and for a polished experience), you’ll want a domain name pointing to your server. If you’re just testing locally, you can use localhost or a local DNS setup.
• Basic CLI Knowledge: You’ll need to run a few commands to generate secrets and configure files, but nothing too scary.
• An OAuth Provider (Optional): If you want to enable logins via GitHub, Google, or another provider, you’ll need an account with that provider to grab API credentials.

Got all that? Awesome. Let’s roll up our sleeves and get Tiny Auth running.

Step 1: Setting Up Traefik

Since Tiny Auth relies on Traefik, let’s start by making sure your Traefik setup is ready. If you already have Traefik running, feel free to skip this section. For everyone else, here’s a quick primer.

Traefik is a reverse proxy that routes incoming web traffic to your services based on rules (like domain names or paths). It’s super flexible and integrates nicely with Docker, which is why Tiny Auth uses it. To set up Traefik, you’ll need a Docker Compose file and a configuration file.

Here’s a basic docker-compose.yml for Traefik:

version: "3.8" services: traefik: image: traefik:v2.10 container_name: traefik ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./traefik.yml:/etc/traefik/traefik.yml - ./certs:/etc/certs networks: - proxy networks: proxy: external: true

And here’s a simple traefik.yml configuration file:

global: checkNewVersion: true sendAnonymousUsage: false entryPoints: web: address: ":80" websecure: address: ":443" api: dashboard: true insecure: true providers: docker: exposedByDefault: false

A few things to note:

• The docker.sock volume lets Traefik talk to Docker to discover services automatically.
• The proxy network is where Traefik and Tiny Auth will communicate. You’ll need to create it with docker network create proxy if it doesn’t exist.
• The certs volume is for SSL certificates (optional for now, but recommended for production).

Run docker-compose up -d to start Traefik, then visit http://localhost:8080 to check the Traefik dashboard. If you see it, you’re golden. Now let’s move on to Tiny Auth.

Step 2: Deploying Tiny Auth with Docker Compose

Tiny Auth’s deployment is a breeze, thanks to its Docker-based setup. The project provides a sample Docker Compose file, but we’ll walk through creating one from scratch to understand what’s going on.

Create a new directory for Tiny Auth (e.g., tiny-auth) and add a docker-compose.yml file like this:

version: "3.8" services: tinyauth: image: steveiliop56/tinyauth:latest container_name: tinyauth environment: - SECRET=${SECRET} - APP_URL=https://auth.yourdomain.com - LOG_LEVEL=0 - USERS_FILE=/users.yml - OAUTH_GITHUB_CLIENT_ID=${OAUTH_GITHUB_CLIENT_ID} - OAUTH_GITHUB_CLIENT_SECRET=${OAUTH_GITHUB_CLIENT_SECRET} - OAUTH_WHITELIST=${OAUTH_WHITELIST} volumes: - ./users.yml:/users.yml networks: - proxy labels: - "traefik.enable=true" - "traefik.http.routers.tinyauth.rule=Host(`auth.yourdomain.com`)" - "traefik.http.routers.tinyauth.entrypoints=websecure" - "traefik.http.services.tinyauth.loadbalancer.server.port=3000" networks: proxy: external: true

Let’s break down the key parts:

• Image: We’re pulling the official Tiny Auth image from Docker Hub.
• Environment Variables: These configure Tiny Auth’s behavior (more on this later).
• Volumes: We’re mounting a users.yml file to store user credentials.
• Networks: Tiny Auth joins the proxy network to talk to Traefik.
• Traefik Labels: These tell Traefik how to route traffic to Tiny Auth (e.g., at auth.yourdomain.com).

Before we can run this, we need to set up the environment variables and the users file.

Step 3: Configuring Environment Variables

Tiny Auth uses environment variables to customize its behavior. You can define these in a .env file or directly in your shell. Here’s what you’ll need:

1. SECRET: A random string used to secure cookies. Generate one with this command:

   openssl rand -base64 32

   Copy the output and add it to your .env file:

   SECRET=your-random-secret-here

2. APP_URL: The URL where Tiny Auth will be accessible. For example:

   APP_URL=https://auth.yourdomain.com

   Replace yourdomain.com with your actual domain (or http://localhost for testing).

3. LOG_LEVEL: Controls how much debugging info Tiny Auth logs. 0 is verbose (great for troubleshooting), while 1 or 2 is quieter:

   LOG_LEVEL=0

4. USERS_FILE: Points to the file where user credentials are stored:

   USERS_FILE=/users.yml

5. OAuth Settings (optional for now): If you’re using GitHub login, you’ll need:

   OAUTH_GITHUB_CLIENT_ID=your-github-client-id OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret OAUTH_WHITELIST=your.email@example.com

   We’ll cover OAuth setup in a later section.

Create a .env file in your tiny-auth directory with these values, and Docker Compose will load them automatically.

Step 4: Creating the Users File

Tiny Auth supports two ways to manage users: inline in the environment variables or via a separate users.yml file. The file approach is cleaner and easier to manage, so that’s what we’ll use.

Create a users.yml file in your tiny-auth directory:

users: - username: alice password: $2b$10$your.bcrypt.hash.here - username: bob password: $2b$10$another.bcrypt.hash.here

To generate a bcrypt hash for a password, use a tool like htpasswd or an online bcrypt generator. For example, to create a hash for the password mypassword:

htpasswd -nbBC 10 username mypassword

This will output something like:

username:$2b$10$some.long.hash.string

Copy the hash (starting with $2b$10$) and paste it into users.yml for each user. For testing, you can create users like Alice and Bob, but in a real setup, use strong passwords and unique usernames.

Step 5: Protecting a Service with Tiny Auth

Now that Tiny Auth is configured, let’s use it to secure a service. For this example, we’ll protect IT Tools, a handy web-based toolkit, but you can apply the same steps to any Dockerized service (e.g., Jellyfin, Homepage, or a custom app).

Assuming you have IT Tools running in Docker, add Tiny Auth’s middleware to its Docker Compose file. Here’s an example docker-compose.yml for IT Tools:

version: "3.8" services: it-tools: image: corentinth/it-tools:latest container_name: it-tools networks: - proxy labels: - "traefik.enable=true" - "traefik.http.routers.it-tools.rule=Host(`it-tools.yourdomain.com`)" - "traefik.http.routers.it-tools.entrypoints=websecure" - "traefik.http.routers.it-tools.middlewares=tinyauth" - "traefik.http.middlewares.tinyauth.forwardauth.address=http://tinyauth:3000/auth" - "traefik.http.middlewares.tinyauth.forwardauth.trustForwardHeader=true" - "traefik.http.middlewares.tinyauth.forwardauth.authResponseHeaders=Authorization" networks: proxy: external: true

Key points:

• The traefik.http.routers.it-tools.middlewares=tinyauth label applies Tiny Auth’s middleware to this service.
• The forwardauth.address points to Tiny Auth’s container (adjust if your setup differs).
• The trustForwardHeader and authResponseHeaders ensure authentication works smoothly.

Run docker-compose up -d to redeploy IT Tools. Now, when you visit it-tools.yourdomain.com, you should see Tiny Auth’s login screen. Try logging in with one of your users (e.g., alice and their password). If everything’s set up right, you’ll be redirected to IT Tools after a successful login.

Step 6: Adding OAuth with GitHub

Username/password logins are great, but letting users sign in with GitHub or Google is even cooler. Tiny Auth supports OAuth providers, and setting up GitHub login is straightforward. Here’s how to do it.

Create a GitHub OAuth App

1. Go to your GitHub account settings and navigate to Developer settings > OAuth Apps > New OAuth App.
2. Fill in the details:
   • Application name: Something like “Tiny Auth Login”.
   • Homepage URL: Your Tiny Auth URL (e.g., https://auth.yourdomain.com).
   • Authorization callback URL: Append /callback/github to your Tiny Auth URL (e.g., https://auth.yourdomain.com/callback/github).
3. Click Register application.
4. Copy the Client ID.
5. Click Generate a new client secret, copy the secret, and store it securely.

Update Tiny Auth’s Configuration

Add the GitHub credentials to your .env file:

OAUTH_GITHUB_CLIENT_ID=your-github-client-id OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret OAUTH_WHITELIST=your.email@example.com

The OAUTH_WHITELIST is crucial—it restricts who can log in via GitHub. For example, if you only want your GitHub account to access the service, add your GitHub email here. Without this, anyone with a GitHub account could log in, which isn’t ideal for private setups.

You’ll also need to update your users.yml to include your GitHub account. Tiny Auth maps OAuth users to local users based on their email. Add an entry like this:

users: - username: your-github-username email: your.email@example.com

Redeploy Tiny Auth with docker-compose up -d. Now, when you visit the login page, you should see a “Sign in with GitHub” button. Click it, authorize the app on GitHub, and you’ll be logged in automatically.

Step 7: Enabling Multi-Factor Authentication (MFA)

For extra security, Tiny Auth supports TOTP-based MFA, which lets users add a second factor (like a code from Google Authenticator or Bitwarden) to their login. Setting it up is a bit technical, but I’ll guide you through it.

Generate a TOTP Secret

1. Find the user you want to enable MFA for in users.yml. For example, let’s use Alice.

2. Run the following command to generate a TOTP secret (replace tinyauth with your container name):

   docker exec tinyauth tinyauth totp generate

3. When prompted, enter the user’s current entry from users.yml, like:

   username: alice password: $2b$10$your.bcrypt.hash.here

4. The command will output a QR code (in ASCII) and a secret key. Scan the QR code with an authenticator app (e.g., Google Authenticator, Authy, or Bitwarden), or manually enter the secret key.

5. The command also outputs an updated user entry with the TOTP secret included, something like:

   username: alice password: $2b$10$your.bcrypt.hash.here totp_secret: some-long-secret-string

6. Copy this updated entry and replace the old one in users.yml.

Test MFA

Redeploy Tiny Auth with docker-compose up -d. Now, when you log in as Alice, you’ll be prompted for a TOTP code after entering the password. Open your authenticator app, grab the code, and enter it. If it works, you’re all set—MFA is active!

Comparing Tiny Auth to Oralia and Authentik

To give you a better sense of where Tiny Auth fits in, let’s compare it to Oralia and Authentik, two other popular authentication tools.

Tiny Auth vs. Oralia

• Purpose: Oralia is designed for advanced access control, supporting complex policies like Role-Based Access Control (RBAC) and Attribute-Based Access Control (ABAC). Tiny Auth focuses on simple authentication with basic authorization.
• Complexity: Oralia requires more setup and configuration, especially for defining policies. Tiny Auth is plug-and-play, with minimal config needed.
• Use Case: Use Oralia for enterprise-grade apps where fine-grained permissions are critical. Use Tiny Auth for homelabs or small projects where you just need a login screen.
• Performance: Both are lightweight, but Tiny Auth’s minimal footprint makes it slightly leaner for basic setups.

Tiny Auth vs. Authentik

• Purpose: Authentik is a full-fledged identity provider, supporting SSO, LDAP, and advanced user management. Tiny Auth is a middleware, not a complete IAM solution.
• Features: Authentik has way more features (e.g., SAML, SCIM, detailed auditing), but that comes with complexity. Tiny Auth keeps it simple with username/password, OAuth, and MFA.
• Ease of Use: Tiny Auth wins for quick setups—think minutes, not hours. Authentik requires more planning and resources.
• Scalability: Authentik is better for large-scale deployments with thousands of users. Tiny Auth is ideal for personal or small-team use.

In short, Tiny Auth is the “keep it simple” option. If you need enterprise features, Oralia or Authentik might be better, but for most self-hosters, Tiny Auth hits the sweet spot.

Advanced Use Cases

Now that you’ve got the basics down, let’s explore some advanced ways to use Tiny Auth to level up your setup.

Securing Multiple Services

Tiny Auth’s strength is its flexibility—you can protect any service behind Traefik with a single middleware. Want to secure your entire homelab? Just add the tinyauth middleware to every service’s Docker Compose file. For example:

• Jellyfin (media server): Add the middleware to stream securely.
• Homepage (dashboard): Protect your app launcher.
• Nextcloud (cloud storage): Keep your files private.

Each service will use the same Tiny Auth login screen, creating a unified authentication experience. You can even mix and match username/password and OAuth logins across services.

Customizing the Login Page

Tiny Auth’s default login page is functional, but what if you want to make it your own? The project is open-source, so you can fork it and tweak the frontend (built with HTML/CSS/JavaScript). For example:

• Change the logo to your brand’s.
• Adjust colors to match your app’s theme.
• Add custom text or instructions.

To customize, clone the Tiny Auth repo, edit the frontend files, and build a new Docker image. It’s a bit of work, but it’s a great way to personalize the experience.

Using Tiny Auth in Production (with Caveats)

Tiny Auth is designed for homelab use, but with some tweaks, you could use it in production for small apps. Here are a few tips:

• Enable HTTPS: Use Traefik with Let’s Encrypt to secure Tiny Auth’s traffic.
• Strong Secrets: Use a robust SECRET and rotate it regularly.
• Backup Users: Store users.yml in a safe place (e.g., a Git repo or encrypted storage).
• Monitor Logs: Set LOG_LEVEL=1 in production to reduce noise but still catch errors.

That said, for high-stakes apps, consider a battle-tested solution like Authentik or Keycloak. Tiny Auth is awesome, but it’s still young and evolving.

Integrating with Other OAuth Providers

Beyond GitHub, Tiny Auth supports providers like Google and potentially others (check the docs for the latest). The setup is similar: grab the provider’s client ID and secret, update your .env, and add the provider’s callback URL. This flexibility makes Tiny Auth a great choice for apps where users expect modern login options.

Troubleshooting Tips

Like any tech project, things might not work perfectly the first time. Here are some common issues and fixes:

• Login Fails: Double-check your users.yml for correct bcrypt hashes. Use a tool like htpasswd to verify.
• OAuth Errors: Ensure your client ID, secret, and callback URL match exactly. Typos are the enemy!
• Traefik Issues: Confirm both Tiny Auth and your service are on the proxy network. Check Traefik’s dashboard for routing errors.
• MFA Not Prompting: Make sure the totp_secret is correctly added to users.yml and the container is redeployed.

If you’re stuck, check Tiny Auth’s logs (docker logs tinyauth) or the project’s GitHub issues page. The community is active and helpful.

Why Tiny Auth’s Growth Matters

Let’s take a moment to appreciate Tiny Auth’s meteoric rise. With 1.6K GitHub stars in just a few months, it’s clear the project is resonating with developers. Why? Because it solves a real problem—authentication doesn’t have to be complicated. In a world of bloated frameworks, Tiny Auth’s minimalist approach is refreshing.

The fact that it’s built by a 15-year-old adds an extra layer of awe. It’s a reminder that great ideas can come from anywhere, and open-source communities thrive when young talent gets involved. By using Tiny Auth, you’re not just securing your services—you’re supporting a project with huge potential.

What’s Next for Tiny Auth?

Tiny Auth is still in active development, which means things are changing fast. Based on its trajectory, here are a few features we might see in the future:

• More OAuth Providers: Support for Discord, Microsoft, or other platforms could make Tiny Auth even more versatile.
• Improved MFA: Options like WebAuthn or push notifications could enhance security.
• Better UI Customization: A built-in way to theme the login page would be a big win.
• Advanced Access Control: Basic RBAC or group-based permissions could bridge the gap with tools like Oralia.

For now, the project’s simplicity is its strength, but it’s exciting to imagine where it’ll go next. Keep an eye on the GitHub repo for updates!

Final Thoughts

Tiny Auth is one of those rare projects that makes you smile. It’s lightweight, easy to use, and packs just enough features to get the job done without overwhelming you. Whether you’re securing a homelab, building a small app, or just experimenting, Tiny Auth is a fantastic choice. Its integration with Traefik, support for OAuth, and MFA make it versatile, while its minimalist design keeps things approachable.

Setting it up is a breeze—Docker Compose, a few environment variables, and some Traefik labels, and you’re good to go. The fact that it’s built by a 15-year-old and has already hit 1.6K GitHub stars? That’s just the cherry on top.