Skip to content

- Mail: - Troubleshooting

Troubleshoot-logboek — SSO / nginx / oauth2-proxy / Keycloak

Dit document groepeert de commando’s die tijdens het debuggen zijn gebruikt per categorie. Doel: snel reproduceren, analyseren en later automatiseren in runbooks of scripts.

1. systemd / Service-gedrag analyseren

Service status controleren

systemctl status oauth2-proxy
systemctl status keycloak
systemctl status nginx

Live logs volgen (meest gebruikt!)

journalctl -u oauth2-proxy -f
journalctl -u keycloak -f
journalctl -u nginx -f

Logs sinds laatste start

journalctl -u oauth2-proxy -b

Unitfile opnieuw inlezen na wijziging

sudo systemctl daemon-reload

Service herstarten

sudo systemctl restart oauth2-proxy

Controleren welke ExecStart actief is

systemctl cat oauth2-proxy

2. Handmatig starten om fouten zichtbaar te maken

Zeer belangrijk bij config-problemen.

sudo oauth2-proxy \
  --alpha-config=/etc/oauth2-proxy-log.d/oauth2-proxy-log.alpha.yaml \
  --email-domain=* \
  --cookie-secret="..."

👉 Hiermee zie je fouten direct op stdout i.p.v. via systemd.

3. Configuratiebestanden inspecteren

Environment file controleren

sudo cat /etc/oauth2-proxy/oauth2-proxy.env

YAML config bekijken

sudo less /etc/oauth2-proxy-log.d/oauth2-proxy-log.alpha.yaml

Rechten controleren (vaak oorzaak!)

ls -l /etc/oauth2-proxy*

4. Controleren of poorten echt luisteren

Welke service luistert?

sudo ss -tlnp | grep 4180
sudo ss -tlnp | grep 8081

Alternatief

sudo lsof -i :4180

5. HTTP-flow testen zonder browser

Basis test via nginx

curl -I https://dev.public-risk.org/

oauth2 auth_request simuleren

curl -v http://127.0.0.1:4180/oauth2/auth

Callback testen

curl -vk https://dev.public-risk.org/oauth2/callback

6. Cookies en sessiegedrag analyseren

curl -c cookies.txt -b cookies.txt -v https://dev.public-risk.org/

Headers inspecteren (belangrijk!)

curl -v https://dev.public-risk.org/ 2>&1 | grep -i auth

7. nginx configuratie debuggen

Config syntax check

sudo nginx -t

Actieve config dumpen

sudo nginx -T

Reload zonder downtime

sudo systemctl reload nginx

auth_request headers controleren

curl -I https://dev.public-risk.org/ | grep X-Auth

8. Keycloak connectiviteit controleren

Bereikbaarheid lokaal testen

curl -I http://127.0.0.1:8081/keycloak/

Via reverse proxy testen

curl -I https://dev.public-risk.org/keycloak/

Issuer endpoint controleren (MOET werken!)

curl https://dev.public-risk.org/keycloak/realms/master/.well-known/openid-configuration

9. Netwerk / DNS / TLS uitsluiten

DNS check

dig dev.public-risk.org

TLS handshake controleren

openssl s_client -connect dev.public-risk.org:443

Timeouts onderscheiden van auth-problemen

curl -w "@curl-format.txt" -o /dev/null -s https://dev.public-risk.org

10. Debuggen van 403 / login loops

Controleren of email claim aanwezig is

Key foutmelding die we zagen:

neither the id_token nor the profileURL set an email

Dus controleren in Keycloak:

  • client scope → email
  • mapper → email
  • claim aanwezig in token

11. Snelle sanity-checks die vaak helpen

date
timedatectl
hostname -f

(Tijdverschil breekt OIDC!)

12. Tijdelijk servicegedrag uitschakelen (development)

In plaats van ExecStart verwijderen:

ExecStart=/usr/bin/true

of runtime override:

systemctl edit oauth2-proxy

Conclusie

De meeste problemen zaten niet in:

  • netwerk
  • nginx
  • TLS

maar in:

  • oauth2-proxy configuratiebron (.env vs YAML)
  • ontbrekende claims uit Keycloak
  • systemd interpretatie van unitfiles

Aanbevolen volgende stap

Dit document kan dienen als basis voor:

  • /usr/local/sbin/sso-diagnose.sh
  • een CI health-check
  • jouw runbook in docs/infrastructure/