Skip to content

- oauth2 proxy

OAuth2-Proxy CLI Test Procedures

This document summarizes CLI-based diagnostic tests for validating an OAuth2-Proxy setup (used behind nginx with Keycloak / OpenID Connect).

1. Verify oauth2-proxy is Listening

Check whether the service is running and listening (default port 4180):

sudo ss -tlnp | grep :4180

Test health endpoint:

curl -i http://127.0.0.1:4180/ping

Expected result:

HTTP/1.1 200 OK
OK

2. Test OAuth Start Flow (Without nginx)

Simulate initial authentication redirect:

curl -i -H "Host: dev.public-risk.org" http://127.0.0.1:4180/oauth2/start

Expected: 302 Found redirect to Keycloak auth endpoint.

Validates: - redirect_url correctness - client_id usage - provider configuration

3. Test /oauth2/auth Endpoint (Used by nginx auth_request)

curl -i -H "Host: dev.public-risk.org" http://127.0.0.1:4180/oauth2/auth

Expected (not logged in):

401 Unauthorized

If you see: - 302 → configuration issue - 500 → cookie/secret issue

Cookie secret must decode to exactly 32 bytes:

echo 'YOUR_COOKIE_SECRET' | base64 -d | wc -c

Expected output:

32

5. Follow Full Redirect Flow

curl -k -L -v https://dev.public-risk.org/oauth2/start

Verify: - Correct HTTPS usage - No redirect loops - Correct hostname - Proper Keycloak endpoint

6. Simulate Reverse Proxy Headers

curl -i   -H "X-Forwarded-Proto: https"   -H "X-Forwarded-Host: dev.public-risk.org"   http://127.0.0.1:4180/oauth2/start

Ensures oauth2-proxy correctly interprets external URL context.

7. Enable Debug Logging

Add flags:

--standard-logging=true
--request-logging=true
--auth-logging=true
--log-level=debug

Monitor logs:

journalctl -u oauth2-proxy -f

Useful for detecting: - redirect mismatches - invalid redirect_uri - session issues - logout errors

8. Test Logout Endpoint Directly

curl -i -H "Host: dev.public-risk.org" http://127.0.0.1:4180/oauth2/sign_out

Expected:

302 Found
Set-Cookie: _oauth2_proxy=deleted

9. Validate OIDC Discovery Endpoint

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

Ensure URLs match oauth2-proxy configuration exactly.

After login, decode session:

echo '_oauth2_proxy=...' | cut -d. -f2 | base64 -d | jq .

Check: - issuer - expiry - email - redirect

Issuer must match Keycloak realm URL.

Common Logout Issue

When using:

return 302 /oauth2/sign_out?rd=/kc-logout;

Prefer absolute redirect:

rd=https://dev.public-risk.org/kc-logout

Relative paths often cause logout redirect validation errors.

End of document.