Übersicht

Wer mehrere Anwendungen im eigenen Homelab betreibt, kennt das Problem: Für jeden Dienst gibt es einen eigenen Benutzer, ein eigenes Passwort und im besten Fall noch eine separate Zwei-Faktor-Authentifizierung.

Mit einem zentralen Identity Provider können wir diese Anmeldungen zusammenfassen und Single Sign-On für unsere Anwendungen verwenden. Genau hier kommt Pocket-ID ins Spiel. Pocket-ID ist ein schlanker, selbst gehosteter OIDC Provider, der vollständig auf die Anmeldung mit Passkeys setzt.

In diesem Artikel installieren wir Pocket-ID mit Docker, richten die Instanz ein und schauen uns anschließend am Beispiel von NetBird und Proxmox an, wie wir unsere Anwendungen mit Pocket-ID verbinden können.

Video zum Artikel: https://youtu.be/NX1EdDXWMRQ

Installation

Pocket-ID kann ganz bequem via Docker installiert werden oder aber auch als Standalone Version. Ich bevorzuge hierbei den Empfohlenen Weg mit Docker.

Docker

Als Erstes installieren wir Docker, falls das noch nicht geschehen ist, da wir BunkerWeb mit Docker betreiben möchten. Das können wir ganz einfach mit dem offiziellen Convenience Script von Docker machen.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Verzeichnis

Bevor wir fortfahren, müssen wir uns ein geeignetes Verzeichnis erstellen, wo wir Pocket-ID später laufen lassen wollen. Ich habe meine Docker-Compose-Stacks immer gerne unter /opt, darunter erstelle ich einen neuen Ordner für Pocket-ID mit:

sudo mkdir /opt/pocket-id
cd /opt/pocket-id

Docker Compose

Das docker-compose.yml File für Pocket-ID wird mit curl einfach direkt von der offiziellen GitHub-Seite geladen.

Der Befehl dafür:

curl -o docker-compose.yml https://raw.githubusercontent.com/pocket-id/pocket-id/main/docker-compose.yml

An der Datei selber müssen wir soweit keine Veränderungen vornehmen, außer ihr habt ggf. euren Reverse-Proxy mit auf demselben Host und wollt den Service via Docker-Netzwerk direkt anbinden und nur für den Reverse-Proxy erreichbar machen.

services:
  pocket-id:
    image: pocketid/pocket-id:v2 # or ghcr.io/pocket-id/pocket-id:v2
    restart: unless-stopped
    env_file: .env
    ports:
      - 1411:1411
    volumes:
      - "./data:/app/data"
    # Optional healthcheck
    healthcheck:
      test: [ "CMD", "/app/pocket-id", "healthcheck" ]
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s

.env

Zuletzt benötigen wir jetzt noch die .env Datei, die ebenfalls simpel aufgebaut ist und nicht viele Änderungen benötigt.

Auch die bekommen wir per curl-Befehl direkt von der offiziellen GitHub-Seite.

Der Befehl:

curl -o .env https://raw.githubusercontent.com/pocket-id/pocket-id/main/.env.example

Anschließend müssen wir diese einmal öffnen und zwei Anpassungen vornehmen.

1. APP_URL mit der gewünschten URL versehen, über die Pocket-ID später erreicht werden soll.
2. ENCRYPTION_KEY mit openssl rand -base64 32 generieren und der Variable beifügen.

Weitere Anpassungen können optional vorgenommen werden, weitere Infos dazu hier in den offiziellen Docs.

# See the documentation for more information: https://pocket-id.org/docs/configuration/environment-variables

# These variables must be configured for your deployment:
APP_URL=https://pocket.juseclab.de

# Encryption key (choose one method):
# Method 1: Direct key (simple but less secure)
# Generate with: openssl rand -base64 32
ENCRYPTION_KEY=4zpIiov1hTPa62Ln6EYW7jK6ka6CWEzR0Yf8D0N4i+E
# Method 2: File-based key (recommended)
# Put the base64 key in a file and point to it here.
# ENCRYPTION_KEY_FILE=/path/to/encryption_key

# These variables are optional but recommended to review:
TRUST_PROXY=false
MAXMIND_LICENSE_KEY=
PUID=1000
PGID=1000

Reverse Proxy

Bevor wir mit dem Setup starten können, müssen wir erst einmal dafür sorgen, dass wir auf unsere Instanz ordentlich mit gültigem Zertifikat und via https zugreifen können.

Das ist am einfachsten mit einem Reverse-Proxy. In diesem Setup habe ich einen bereits eingerichteten Nginx Proxy Manager auf einem anderen System, welches den Pocket-ID Server erreicht.

Ihr habt auch die Möglichkeit, das Ganze direkt mit auf dem Host zu konfigurieren und Pocket-ID ohne zusätzliche Ports ausschließlich über den Reverse-Proxy erreichbar zu machen.

Zwei verschiedene Ansätze dazu findet ihr auch noch einmal hier:

• Reverse Proxy mit Caddy
• Reverse Proxy mit NPM

Auf dem genannten Nginx Proxy Manager in dem aktuellen Setup sieht der Eintrag dann so aus:

Erster Start

Alles ist vorbereitet und Pocket-ID kann gestartet werden. Das machen wir mit dem Befehl:

docker compose up -d

Nach kurzem Starten können wir dann zum initialen Setup navigieren unter:

https://<eure.domain.de>/setup

Dort angekommen können wir unseren ersten Benutzer erstellen.

Danach werden wir direkt aufgefordert, einen Passkey zu unserem Account hinzuzufügen.

Das solltet ihr unbedingt tun, denn darüber könnt ihr euch dann später authentifizieren.

Einrichtung

Damit haben wir unseren Account erstellt, der automatisch auch Administrator der Instanz ist. Durch die Administratoren-Rolle sehen wir den Menüpunkt Verwaltung mit seinen Unterpunkten.

Benutzer

Wie der Reiter vermuten lässt, können wir hier weitere Benutzer anlegen, um diesen Zugriff bzw. die Möglichkeit zu geben, sich bei unseren Anwendungen mit diesem Account zu authentifizieren.

Benutzergruppen

Der Reiter dient zum Erstellen von Gruppen. Diese können wir dann wiederum für die Berechtigung auf unsere verschiedenen Anwendungen verwenden, um alles ein wenig komfortabler zu halten und nicht jeden Benutzer überall einzeln hinzufügen zu müssen.

OIDC Clients

Das Herzstück von Pocket-ID. Hier binden wir all unsere gewünschten Applikationen an, um uns dort per Single Sign-On anmelden zu können.

Das werden wir uns gleich einmal beispielhaft anschauen.

APIs & API-Schlüssel

Die beiden Punkte dienen für den Zugriff via API. Der Reiter APIs gibt die Möglichkeit, einen API-Zugang zu erstellen, über den Clients Zugriffstokens anfordern können. API-Schlüssel dienen dabei eher für das Ansteuern des ganzen Systems via API.

Anwendungskonfiguration

Der letzte Punkt gibt uns die Möglichkeit, unsere Pocket-ID-Instanz zu personalisieren.

Benutzererstellung

Im Unterreiter Benutzererstellung können wir das automatische Registrieren bspw. deaktivieren.

Passkeys

Hier geben wir alles rund um die Passkeys an.

E-Mail

Ein SMTP-Server für den Mail-Versand kann hier hinterlegt werden.

LDAP

Gibt die Möglichkeit, bereits bestehende Benutzer bspw. aus einem Active Directory zu synchronisieren.

Hinzufügen von Anwendungen

Beispiel mit NetBird

Wir nehmen als Beispiel einmal den NetBird Management Server. Hier kann man die Authentifizierung mit eigenen Identity Providern wie bspw. auch Pocket-ID einrichten.

Die Einstellungen variieren von Applikation zu Applikation immer ein wenig, hier hilft die Dokumentation der entsprechenden Anwendung meist weiter. Das Prinzip ist aber immer dasselbe.

In Pocket-ID, als Admin, gehen wir auf den Reiter OIDC-Clients und fügen einen neuen Client hinzu.

Dort füllen wir jetzt die Felder mit den gewünschten Informationen aus.

Die Callback-URL ist dabei eine Information, die man sich von der Gegenseite suchen muss. Entweder findet man diese in der Dokumentation oder aber auch im Einrichtungsprozess.

Wir können dann noch ein Logo hinterlegen und weiter unten angeben, wie lange der Token gültig ist, bis man sich neu authentifizieren muss.

Anschließend erstellen wir die Anwendung mit Klick auf Speichern.

Nachdem die Anwendung in Pocket-ID existiert, erhalten wir ein paar mehr Konfigurationsmöglichkeiten, wenn wir die Anwendung noch einmal öffnen.

Unter anderem erhalten wir ganz oben die Client-ID. Die benötigen wir für die Gegenseite.

Im Reiter Zugangsdaten können wir uns dann noch das ebenfalls benötigte Client-Secret erstellen.

Die Informationen müssen wir auf der Gegenseite einmal einfügen.

Als Letztes müssen wir der Anwendung bei Pocket-ID noch eine Gruppe hinterlegen, die die Anwendung verwenden darf.

Wenn wir jetzt in der Gruppe sind, können wir uns an NetBird mit unserem Pocket-ID-Account anmelden.

Beispiel Proxmox

Viele nutzen Proxmox in ihrem Homelab für das Hosten von VMs. Auch hier kann man seinen eigenen Identity Provider hinterlegen.

Zuerst muss die Anwendung erstellt werden.

Auf Proxmox-Seite geben wir jetzt wieder die benötigten Informationen ein. Dafür gehen wir auf die Datacenter-Ebene → Permission → Realms.

Dort geben wir wieder Issuer URL, Client ID und Client Key ein. Dann können wir Autocreate User anhaken, damit werden die Benutzer automatisch erstellt, wenn sie noch nicht vorhanden sind.

Bei Username_Claim könnt ihr euch ganz einfach in der Vorschau von Pocket-ID das passende Attribut aussuchen.

Dafür geht ihr einfach auf OIDC-Daten-Vorschau.

Dort seht ihr dann alle verfügbaren Werte.

Anschließend alles speichern und bei der Anmeldung den neuen Realm auswählen.

Fazit

Pocket-ID bietet eine einfache Möglichkeit, eine zentrale Authentifizierung für die eigenen Anwendungen aufzubauen. Besonders interessant finde ich dabei den konsequenten Einsatz von Passkeys und die vergleichsweise unkomplizierte Einrichtung.

Wie wir an NetBird und Proxmox gesehen haben, lassen sich Anwendungen mit OIDC-Unterstützung anschließend relativ einfach anbinden. Welche Einstellungen benötigt werden, unterscheidet sich zwar je nach Anwendung etwas, das grundlegende Prinzip bleibt aber immer gleich.

Wer für sein Homelab einen schlanken, selbst gehosteten Identity Provider sucht und dabei auf Passkeys setzen möchte, sollte sich Pocket-ID auf jeden Fall einmal genauer anschauen.