You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 09f3269
Browse filesBrowse the repository at this point in the historyBrowse files
Before installing tinyauth you may be wondering _Why should I use tinyauth instead of Authelia/Authentik/Keycloack?_ which is a really valid question and I would like to answer in depth.
4
+
5
+
## The issue with authentication on homelabs
6
+
7
+
Most of us like using an authentication middleware in front of our apps to either protect them when they don't offer a login screen or just to add an additional level of authentication. While the projects mentioned above can certainly do the job and offer a variety of configuration options, they can be hard to configure for new users, resource hungry (apps like Authentik and Keycloack are designed for businesses and not the average homelabber) or simply too annoying to set up and maintain. This is where tinyauth comes in to play.
8
+
9
+
## Why I created tinyauth
10
+
11
+
Tinyauth was created to test my skills in making a quite complex app and most importantly to solve the issues mentioned above. I tried a wide variety of authentication projects but most of them didn't even support traefik's forward auth out of the box so they needed weird plugins requiring more and more containers. When I created tinyauth I only had one thing in mind, make it as simple as possible, no fancy dashboards, no complex configuration files, no databases and the entire configuration could be done with simple environment variables everyone knows and loves.
12
+
13
+
## The use case for tinyauth
14
+
15
+
Tinyauth by no means is made for production use cases, by this I mean that it is designed solely for adding a login screen to the apps of an average homelaber that just wants to secure his infrastructure a bit more. While I consider tinyauth secure enough to even be exposed in the internet it has some limitations like being completely stateless (meaning that the server cannot expire a session) and not being able to get configured dynamically (e.g. updating the users requires a restart). If you need an app to handle multiple users and support more advanced backends (like LDAP) my recommendation is Authentik.
16
+
17
+
## The future plans for tinyauth
18
+
19
+
Tinyauth has reached a really good state where it supports almost everything you would ever need from an app like this, it supports what I believe are the most important features like OAuth, TOTP and even access controls and it also integrates very well with the most popular proxies like nginx, traefik and caddy. I am planning to keep the app in this state while slowly adding QOL updates, I am not planning to add any fancy dashboards or configuration files since I do not want to change the project's base idea.
Copy file name to clipboardExpand all lines: docs/getting-started.md
+45-12Lines changed: 45 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,9 +6,50 @@ As promised in the readme, tinyauth is extremely easy to get up and running.
6
6
Tinyauth by default ships with the traefik proxy, if you are using a different proxy there are available guides for [Nginx Proxy Manager](/docs/guides/nginx-proxy-manager) and [Caddy](/docs/community/caddy).
7
7
:::
8
8
9
+
## Creating a user
10
+
11
+
A tinyauth user consists of 3 things, a username, a password hash and an optional TOTP secret:
12
+
13
+
```mermaid
14
+
flowchart BR
15
+
user["username:hash:totp"]
16
+
user --> username["Username is your username in plaintext"]
17
+
user --> hash["Hash is your password hashed in bcrypt"]
18
+
user --> totp["TOTP is an optional TOTP secret"]
19
+
```
20
+
21
+
To generate your user you can use the tinyauth CLI like so:
22
+
23
+
```sh
24
+
docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v3 user create --interactive
25
+
```
26
+
27
+
It will ask you for your username and password and then give you your new user. For more information about the create command check out the [reference](/docs/reference/cli.md#create-user-command).
28
+
29
+
::: info
30
+
If you are using docker compose or environment variables make sure to pick yes in the format for docker so as your bcrypt hash is escaped correctly.
31
+
:::
32
+
33
+
You can repeat this step as many times as you like and create a comma separated list of your users.
34
+
35
+
## Setting up your domains
36
+
37
+
The way tinyauth works is by setting a cookie for the parent domain of the app URL, in other words if your app URL is `http://tinyauth.sub.example.com`, tinyauth will set a cookie for `.sub.example.com` in order to be able to authenticate you. This means that all your apps will have to be under this subdomain. Here is an example:
38
+
39
+
```mermaid
40
+
flowchart BR
41
+
domain["sub.example.com"]
42
+
domain --> tinyauth["tinyauth.sub.example.com"]
43
+
domain --> app["app.sub.example.com"]
44
+
```
45
+
46
+
::: warning
47
+
You cannot use tinyauth directly in DDNS services (e.g. `tinyauth562.duckdns.org`) it **_has to_** be under a subdomain (e.g. `tinyauth.mylab562.duckdns.org`) as well as all of your apps.
48
+
:::
49
+
9
50
## Installation
10
51
11
-
To get started simply add the tinyauth service next to your traefik container:
52
+
Now it's time to create our docker compose file which can be as simple as this:
Make sure to set the labels according to your own setup, this guide includes the most basic ones.
30
-
:::
31
-
32
-
::: info
33
-
Tinyauth accepts a comma separated list of `username:hash` combinations. Make sure escape the dollar signs by doubling them. If you are unsure on how to create your user you can use the tinyauth CLI by running `docker run -i -t --rm --name tinyauth ghcr.io/steveiliop56/tinyauth:v3 user create --interactive` or use [IT Tools](https://it-tools.tech/bcrypt) to generate the password hash.
34
-
:::
35
-
36
69
::: tip
37
-
Use this command to generate the `SECRET` value: `tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo`
70
+
You can generate the `SECRET` environment variable using `openssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 32`.
38
71
:::
39
72
40
73
Then for every app you want tinyauth to protect just add the following label:
Copy file name to clipboardExpand all lines: docs/guides/runtipi.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,11 +12,11 @@ The runtipi app also includes inputs for Github, Google and Tailscale so if you
12
12
13
13
Runtipi by default uses its own login screen for authentication, we want to replace that with tinyauth. This can be done by enabling advanced settings:
For authentication to work correctly you either need to use the local domain or make sure that the expose domain is under the same root level domain as tinyauth. For example `tinyauth.example.com` and `nginx.example.com` will work but `tinyauth.domain1.com` and `nginx.domain2.com` will **not** work.
Tinyauth has built-in support for TOTP, this means that you can use your favorite authenticator app to get 2FA codes when trying to login to tinyauth.
4
+
5
+
## Generating the secret
6
+
7
+
We firstly need to generate our TOTP secret, to do this we will need our current `username:hash`. Then we can use the tinyauth CLI to create our new user. This can be done like so:
8
+
9
+
```sh
10
+
docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v3 totp generate --interactive
11
+
```
12
+
13
+
It will prompt you for your user and then give you (a massive) QR code to scan with your authenticator app. After you add it you can copy your newly generated user (the part after the `user=` log message) and add it to your tinyauth user list and restart. Finally every time you try to login tinyauth will prompt your for your TOTP code.
14
+
15
+
## Verifying your user
16
+
17
+
If you are unsure if your user is correct you can use the following command to check:
18
+
19
+
```sh
20
+
docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v3 user verify --interactive
21
+
```
22
+
23
+
It will prompt you for your user (`username:hash:totp`), your username, your password (actual password) and a TOTP code from your authenticator app. If everything succeeds you should see the user verified message.
0 commit comments