Guide

Tinyauth - un SSO con 2FA per i vostri servizi web

Hai sviluppato una webapp o scoperto un servizio self-hosted ma non sai come proteggerlo in modo sicuro? Tinyauth è un SSO leggero con supporto 2FA che si integra facilmente con NGINX, offrendo un'autenticazione solida e centralizzata per i tuoi servizi web. Vediamo come integrarlo con NGINX.

I loghi di NGINX ed Tinyauth

Se frequentate siti come selfh.st o Awesome-Selfhosted, vi sarà sicuramente capitato di imbattervi in un servizio così utile da volerlo subito installare nella vostra infrastruttura. Peccato solo che, spesso, non disponga di un sistema di autenticazione abbastanza sicuro da permettervi di esporlo tranquillamente online.

Oppure magari avete sviluppato una webapp ma –come nel mio caso– l’implementazione di un sistema di login robusto non è il vostro forte, e preferireste evitare di reinventare la ruota.

In scenari come questi, Tinyauth è la soluzione perfetta: un piccolo software che aggiunge un ulteriore layer di autenticazione, integrandosi con il vostro reverse proxy (come NGINX) in modo semplice ed efficace.

Come funziona

Quando un utente cerca di accedere al vostro servizio:

La richiesta passa da NGINX.
NGINX la redirige verso Tinyauth per l'autenticazione.
Solo se Tinyauth conferma che l'utente è autenticato, NGINX lo reindirizza verso il servizio di destinazione.

Un'ulteriore comodità derivante dall'utilizzo di un servizio di SSO (Single Sign On) è che gli altri siti che avete protetto con Tinyauth saranno raggiungibili senza autenticarsi nuovamente, fino allo scadere del timeout di sessione.

Prerequisiti

Reverse Proxy

Per utilizzare Tinyauth vi servirà un reverse proxy come NGINX, Traefik o Caddy.

In questa guida, utilizzeremo NGINX.
Se non lo avete ancora installato, potete seguire la mia guida apposita:

Introduzione ad NGINX

Cosa è NGINX? Ve lo lascio presentare direttamente dal sito ufficiale, che dice: NGINX (“engine x”) è un HTTP web server, reverse proxy, content cache, load balancer, TCP/UDP proxy server e mail proxy server NGINX è un software magnifico, ma non certo senza difetti. Uno tra tutti, non ha

Firenetwork - BlogSamuele Gabbrielli

Applicativo da proteggere

Ovviamente, avrete bisogno anche di un applicativo web da proteggere.
Se state cercando qualche progetto open source interessante, date un'occhiata a quelli presenti su selfh.st:

selfh.st - Self-hosted content and software

Self-hosted news, content, updates, launches, events, and more

selfh.st

Autenticazione a due Fattori

Per quanto riguarda l'Autenticazione a due Fattori (2FA), potete utilizzare qualsiasi software compatibile, come Google Authenticator o Authy.

Provider OAuth

Tinyauth è compatibile anche con alcuni provider OAuth.

Per utilizzare un provider OAuth, ovviamente avrete bisogno di un account da collegare.

Installazione

(testata su Ubuntu Server 24.04)

Copiate l'URL del file tinyauth-amd64 dell'ultima release disponibile
Scaricate l'eseguibile

wget %URL%

Rinominate l'eseguibile in tinyauth e rendetelo eseguibile

mv tinyauth-amd64 tinyauth
chmod +x tinyauth

Scaricate il template del file con le variabili d'ambiente

curl -o tinyauth.env https://raw.githubusercontent.com/steveiliop56/tinyauth/refs/heads/main/.env.example

Rinominatelo in .env

mv tinyauth.env .env

Create un nuovo utente

./tinyauth user create --interactive

Copiatevi il risultato del comando (saranno due stringhe divise dal carattere ":", con il vostro username come prima stringa)
modificate il file .env

sudo nano .env

Modificate o eliminate le variabili che non vi servono, seguendo la guida di configurazione ufficiale

Per esempio:

PORT=3000
ADDRESS=0.0.0.0
SECRET=%SECRET%
APP_URL=http://url.di.tinyauth
USERS=%STRINGA_UTENTE%
USERS_FILE=users_file
COOKIE_SECURE=false
DISABLE_CONTINUE=true
GENERIC_NAME=Authentication Server
SESSION_EXPIRY=7200
LOGIN_TIMEOUT=300
LOGIN_MAX_RETRIES=5
LOG_LEVEL=0
APP_TITLE=Authentication Server
GENERIC_SKIP_SSL=false

al posto di %SECRET%, indicate una password abbastanza forte generata casualmente
alla variabile APP_URL, indicate l'FQDN con cui raggiungerete Tinyauth
al posto di %STRINGA_UTENTE%, incollate il risultato ottenuto precedentemente col comando user create

Test di funzionamento

Proviamo ora a lanciare Tinyauth per testarne il funzionamento

Prima, esportiamo le variabili del file .env in modo che siano utilizzabili da CLI

export $(grep -v '^#' .env | xargs -d '\n')

Infine, avviamo tinyauth

./tinyauth

Provando ora a raggiungere l'indirizzo di tinyauth, sulla porta 3000, dovreste trovarvi una schermata simile a questa:

Impostazione del servizio

Provvediamo ora ad impostare l'avvio automatico di Tinyauth, usando system

Creiamo il file del servizio

sudo nano /etc/systemd/system/tinyauth.service

Compiliamolo facendolo puntare all'eseguibile ed al file .env (in questo esempio si trovano entrambi in /home/firefoz/

[Unit]
Description=Tinyauth service
After=network.target

[Service]
EnvironmentFile=/home/firefoz/.env
ExecStart=/home/firefoz/tinyauth
Restart=on-failure

[Install]
WantedBy=multi-user.target

Attiviamo ed avviamo il servizio

sudo systemctl daemon-reload
sudo systemctl enable --now tinyauth

Infine monitoriamo l'output del servizio

sudo journalctl -efu tinyauth

Configurazione

su NGINX

Non abbiamo ancora finito: per poter proteggere i nostri servizi web con l'autenticazione di Tinyauth, dobbiamo creare delle regole su NGINX.

Regola per Tinyauth

Prima di tutto, creiamone una per Tinyauth stesso. Nell'esempio seguente:

L'FQDN di Tinyauth è auth.test.it
L'indirizzo IP della macchina di Tinyauth è 192.168.0.200
La porta configurata nel file .env è la 3000

server {
    listen 80;
    server_name auth.test.it;
    location / {
        proxy_pass http://192.168.0.200:3000;
        proxy_set_header x-forwarded-proto $scheme;
        proxy_set_header x-forwarded-host $http_host;
        proxy_set_header x-forwarded-uri $request_uri;
    }
}
server {
    listen 443 ssl;
    server_name auth.test.it;
    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    location / {
        proxy_pass http://192.168.0.200:3000;
        proxy_set_header x-forwarded-proto $scheme;
        proxy_set_header x-forwarded-host $http_host;
        proxy_set_header x-forwarded-uri $request_uri;
    }
}

Regola per i Servizi Web

Per proteggere i vostri servizi web, potete seguire i template che abbiamo già visto nella guida dedicata ai Reverse Proxy, ma con un paio di aggiunte.

💡

Le seguenti modifiche riguardano, nel caso di un Reverse Proxy con Terminazione SSL, solamente la sezione server relativa ad HTTPS

nella location / aggiungete, in fondo, queste due direttive:

auth_request /auth;
error_page 401 = @tinyauth_login;

create una nuova location /auth come segue:

location /auth {
    proxy_pass http://192.168.0.200:3000/api/auth/nginx;
    proxy_set_header x-forwarded-proto $scheme;
    proxy_set_header x-forwarded-host $http_host;
    proxy_set_header x-forwarded-uri $request_uri;
}

create anche una location @tinyauth_login come segue:

location @tinyauth_login {
    return 302 http://auth.test.it/login?redirect_uri=https://fqdn.del.sito;
}

Per comodità, riporto l'esempio presente nella guida relativa ai Reverse Proxy, nella sua versione con l'implementazione di Tinyauth:

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' "";
}

upstream test-default {
    zone test 64k;
    keepalive 2;
    server 192.168.0.1:8080;
}

server {
    listen 80;
    listen [::]:80;
    server_name test.firenetwork.it;
    if ($host = test.firenetwork.it) {
        return 301 https://$host$request_uri;
    }
    return 404;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl http2;
    server_name test.firenetwork.it;
    client_max_body_size 525M;
    ssl_certificate /etc/nginx/certs/test.firenetwork.it/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/test.firenetwork.it/privkey.pem;
    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://test-default;
        
        auth_request /auth;
    error_page 401 = @tinyauth_login;
    }
    
    location /auth {
    proxy_pass http://192.168.0.200:3000/api/auth/nginx;
    proxy_set_header x-forwarded-proto $scheme;
    proxy_set_header x-forwarded-host $http_host;
        proxy_set_header x-forwarded-uri $request_uri;
    }
    
    location @tinyauth_login {
        return 302 http://auth.test.it/login?redirect_uri=https://fqdn.del.sito;
    }
}

Adesso, provando ad accedere al vostro servizio verrete prima rimandati su auth.test.it

Una volta eseguito l'accesso, accederete al servizio web

Non dovrete più loggarvi passando su auth.test.it finché la vostra sessione rimarrà attiva (parametro SESSION_EXPIRY del file .env)

Inoltre potrete sloggarvi manualmente andando su https://auth.test.it e premendo su logout

Aggiungere la 2FA

Per aggiungere l'autenticazione a due fattori (2FA) ad Tinyauth, avremo bisogno di eseguire dei comandi dall'eseguibile di Tinyauth e di modificare nuovamente il file .env

Seguite la procedura di generazione del TOTP

./tinyauth totp generate --interactive

Scansionate il QR Code con la vostra app di autenticazione preferita
Copiatevi la stringa username:password:TOTP
Se volete assicurarvi che l'OTP venga generato correttamente, seguite la procedura di verifica del TOTP per l'utente