yourpart3/OAUTH_CREDENTIALS_SETUP.md

OAuth Credentials Setup Guide

Anleitung zum Sammeln der OAuth-Credentials für alle 5 Provider.

Redirect URIs

Für alle Provider benötigst du folgende Redirect URIs (ersetze www.your-part.de mit deiner echten Domain):

https://www.your-part.de/auth/oauth/callback
https://www.your-part.de/auth/oauth/user/callback

Lokal zum Testen:

http://localhost:3000/auth/oauth/callback
http://localhost:3000/auth/oauth/user/callback

---

1. Google

Credentials besorgen:

1. Öffne Google Cloud Console
2. Erstelle ein neues Projekt oder wähle ein bestehendes
3. Navigiere zu APIs & Services → Credentials
4. Klick + CREATE CREDENTIALS → OAuth 2.0 Client IDs
5. Wähle Web application
6. Füge unter Authorized redirect URIs hinzu:
   • https://www.your-part.de/auth/oauth/callback
   • https://www.your-part.de/auth/oauth/user/callback
7. Speichern und die Client ID und Client Secret kopieren

.env:

OAUTH_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
OAUTH_GOOGLE_CLIENT_SECRET=your-client-secret

---

2. Microsoft Azure

Credentials besorgen:

1. Öffne Azure Portal
2. Navigiere zu Azure Active Directory → App registrations → + New registration
3. Gib einen Namen ein (z.B. "YourPart OAuth")
4. Wähle Accounts in any organizational directory (Any Azure AD directory - Multitenant)
5. Bei Redirect URI wähle Web und füge ein:
   • https://www.your-part.de/auth/oauth/callback
6. Klick Register
7. Notiere die Application (client) ID
8. Gehe zu Certificates & secrets → + New client secret
9. Erstelle ein Secret und kopiere den Value (nicht die ID!)
10. Gehe zu Token configuration und stelle sicher, dass die richtigen Claims enthalten sind

Zusätzliche URI hinzufügen:

1. Gehe zu Authentication
2. Unter Redirect URIs klick + Add URI
3. Füge hinzu: https://www.your-part.de/auth/oauth/user/callback

.env:

OAUTH_MICROSOFT_CLIENT_ID=your-application-id
OAUTH_MICROSOFT_CLIENT_SECRET=your-client-secret-value

---

3. Keycloak

Keycloak ist ein Open-Source OIDC Provider. Du kannst ihn selbst hosten oder eine gehostete Lösung nutzen.

Option A: Selbst gehostet mit Docker

docker run -d \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest \
  start-dev

Dann:

1. Öffne http://localhost:8080
2. Login mit admin / admin
3. Realm erstellen: Oben links Dropdown → Create realm
   • Name: yourpart (oder beliebig)
4. Im neuen Realm: Clients → Create client
   • Client ID: yourpart
   • Client Protocol: openid-connect
   • Access Type: confidential
5. Im Settings Tab:
   • Valid Redirect URIs:

     https://www.your-part.de/auth/oauth/callback
     https://www.your-part.de/auth/oauth/user/callback
     

6. Speichern
7. Gehe zu Credentials Tab
   • Client Secret kopieren

Option B: Gehosteter Service

• Keycloak.cloud oder
• Red Hat Managed Keycloak

.env:

OAUTH_KEYCLOAK_ISSUER=https://your-keycloak-domain/realms/yourpart
OAUTH_KEYCLOAK_CLIENT_ID=yourpart
OAUTH_KEYCLOAK_CLIENT_SECRET=your-client-secret

---

4. ORY Hydra / ORY Cloud

ORY ist ein moderner OIDC Provider. Am einfachsten ist ORY Cloud.

Option A: ORY Cloud (empfohlen)

1. Öffne ORY Cloud Console
2. Registriere dich oder logge dich ein
3. Erstelle ein neues Project
4. Gehe zu Applications
5. Klick Create New Application
6. Gib einen Namen ein (z.B. "YourPart")
7. Unter Redirect URLs füge ein:

   https://www.your-part.de/auth/oauth/callback
   https://www.your-part.de/auth/oauth/user/callback
   

8. Speichern
9. Die Client ID und Client Secret werden angezeigt
10. Finde deine Issuer URL in den Project Settings (meist https://your-project-slug.eu.hydra.cloud)

Option B: Selbst gehostet (komplex)

Siehe ORY Hydra Dokumentation

.env:

OAUTH_ORY_ISSUER=https://your-project-slug.eu.hydra.cloud
OAUTH_ORY_CLIENT_ID=your-client-id
OAUTH_ORY_CLIENT_SECRET=your-client-secret

---

5. ZITADEL

ZITADEL ist ein Zero-Trust Identity Platform als SaaS.

Credentials besorgen:

1. Öffne ZITADEL Console
2. Registriere dich oder logge dich ein
3. Erstelle eine neue Organization (oder verwende die existierende)
4. Gehe zu Projects → + New Project
5. Gib einen Namen ein (z.B. "YourPart")
6. Gehe zum Projekt → Applications → + New Application
7. Wähle Type: Web
8. Gib einen Namen ein
9. Bei Redirect URIs füge ein:

   https://www.your-part.de/auth/oauth/callback
   https://www.your-part.de/auth/oauth/user/callback
   

10. Speichern
11. Unter Client Information kopiere:
    • Client ID
    • Client Secret (falls sichtbar, sonst im "CREDENTIALS" Tab generieren)
12. Finde deine Issuer URL in den Organization Settings (meist https://your-instance.zitadel.cloud)

.env:

OAUTH_ZITADEL_ISSUER=https://your-instance.zitadel.cloud
OAUTH_ZITADEL_CLIENT_ID=your-client-id
OAUTH_ZITADEL_CLIENT_SECRET=your-client-secret

---

Komplette .env für alle 5 Provider

# Google
OAUTH_GOOGLE_CLIENT_ID=...
OAUTH_GOOGLE_CLIENT_SECRET=...

# Microsoft
OAUTH_MICROSOFT_CLIENT_ID=...
OAUTH_MICROSOFT_CLIENT_SECRET=...

# Keycloak
OAUTH_KEYCLOAK_ISSUER=...
OAUTH_KEYCLOAK_CLIENT_ID=...
OAUTH_KEYCLOAK_CLIENT_SECRET=...

# ORY
OAUTH_ORY_ISSUER=...
OAUTH_ORY_CLIENT_ID=...
OAUTH_ORY_CLIENT_SECRET=...

# ZITADEL
OAUTH_ZITADEL_ISSUER=...
OAUTH_ZITADEL_CLIENT_ID=...
OAUTH_ZITADEL_CLIENT_SECRET=...

---

Schnell-Checkliste

• Google: Client ID & Secret
• Microsoft: Application ID & Client Secret
• Keycloak: Issuer, Client ID, Secret
• ORY: Issuer, Client ID, Secret
• ZITADEL: Issuer, Client ID, Secret
• Alle Redirect URIs in den Providern konfiguriert
• .env datei aktualisiert
• Server neu gestartet (npm restart)

---

Testing

Nach der Konfiguration:

1. Frontend öffnen: http://www.your-part.de
2. Auf "Login" oder Provider-Button klicken
3. Jeder verfügbare Provider sollte als Button angezeigt werden
4. Test: Mit jedem Provider einloggen
5. Test: Existender Nutzer → Einstellungen → Authentifizierung hinzufügen

---

Troubleshooting

"Invalid redirect URI"

• Stelle sicher, dass die Redirect URIs exakt übereinstimmen (inkl. https:// vs http://)
• Beachte Trailing Slashes

"Invalid client secret"

• Kopiere das Secret neu (nicht die ID)
• Manche Provider verstecken das Secret nach einmaliger Anzeige

"Discovery endpoint not found"

• Überprüfe die Issuer URL (mit/ohne Trailing Slash)
• Für Keycloak: URL muss auf /realms/xxx enden
• Für ORY: URL darf nicht auf / enden

Port-Konflikt lokal

• Keycloak benutzt 8080 → ändere auf: docker run -p 8081:8080 ...
• Stelle sicher, dass 3000 (Frontend) und 5000 (Backend) frei sind