TimeTracker/docs/implementation-notes/OIDC_LOGOUT_FIX_SUMMARY.md

OIDC Logout Fix Summary

Issue Description

When OIDC_POST_LOGOUT_REDIRECT_URI was not set (unset/None), the application was still attempting RP-Initiated Logout at the OIDC provider. This caused issues with Identity Providers like Authelia that don't support RP-Initiated Logout yet.

For example, users would be incorrectly redirected to:

https://auth.example.de/api/oidc/revocation?id_token_hint=...

This would fail because the provider doesn't support the endpoint, instead of simply logging out locally and returning to the TimeTracker login page.

Root Cause

In app/routes/auth.py, the logout function had this logic:

post_logout = getattr(Config, 'OIDC_POST_LOGOUT_REDIRECT_URI', None) or url_for('auth.login', _external=True)

The problem was the or url_for('auth.login', _external=True) fallback. Even when OIDC_POST_LOGOUT_REDIRECT_URI was None (not configured), it would fall back to generating a logout redirect URL, causing the application to always attempt RP-Initiated Logout.

Solution

Modified the logout logic to only perform RP-Initiated Logout if OIDC_POST_LOGOUT_REDIRECT_URI is explicitly configured:

if auth_method in ('oidc', 'both'):
    # Only perform RP-Initiated Logout if OIDC_POST_LOGOUT_REDIRECT_URI is explicitly configured
    post_logout = getattr(Config, 'OIDC_POST_LOGOUT_REDIRECT_URI', None)
    if post_logout:
        # ... proceed with RP-Initiated Logout

Now:

• If OIDC_POST_LOGOUT_REDIRECT_URI is NOT set: Users are logged out locally and redirected to TimeTracker's login page
• If OIDC_POST_LOGOUT_REDIRECT_URI IS set: Users are redirected to the provider's logout endpoint (RP-Initiated Logout)

Files Changed

1. app/routes/auth.py

• Modified logout function to check if OIDC_POST_LOGOUT_REDIRECT_URI is set before attempting provider logout
• Added comment explaining the behavior

2. docs/OIDC_SETUP.md

• Updated documentation for OIDC_POST_LOGOUT_REDIRECT_URI to clarify it's optional
• Added guidance: only set if your provider supports end_session_endpoint
• Updated troubleshooting section with specific guidance for providers like Authelia

3. env.example

• Added clear comments explaining when to set OIDC_POST_LOGOUT_REDIRECT_URI
• Noted that if unset, logout will be local only (recommended for providers without RP-Initiated Logout support)

4. tests/test_oidc_logout.py (NEW)

• Created comprehensive test suite with 9 tests covering:
  • Unit tests for logout without OIDC_POST_LOGOUT_REDIRECT_URI configured
  • Unit tests for logout with OIDC_POST_LOGOUT_REDIRECT_URI configured
  • Tests for different auth methods (local, oidc, both)
  • Tests for provider metadata loading failures
  • Tests for session token cleanup
  • Smoke tests for configuration validation

Behavior Matrix

AUTH_METHOD	OIDC_POST_LOGOUT_REDIRECT_URI	Logout Behavior
local	(any)	Local logout → /login
oidc or both	Not set (None)	Local logout → /login
oidc or both	Set	RP-Initiated Logout → Provider logout endpoint

Testing

All tests pass:

• ✅ 9 new OIDC logout tests (all passing)
• ✅ Existing logout tests remain passing (backward compatibility confirmed)
• ✅ No linter errors

Run tests with:

python -m pytest tests/test_oidc_logout.py -v

Migration Guide

For Users with Authelia or Similar Providers

If your OIDC provider doesn't support RP-Initiated Logout:

1. Remove or comment out OIDC_POST_LOGOUT_REDIRECT_URI from your environment:

   # OIDC_POST_LOGOUT_REDIRECT_URI=https://yourapp.example.com/
   

2. Restart the application

3. Test logout - you should now be redirected to TimeTracker's login page instead of the provider's revocation endpoint

For Users with Providers Supporting RP-Initiated Logout

No changes needed. If you have OIDC_POST_LOGOUT_REDIRECT_URI configured, the behavior remains the same.

Security Considerations

This fix does not reduce security:

• Users are still logged out of TimeTracker (session invalidated)
• The ID token is removed from the session
• For providers that support RP-Initiated Logout, full logout still occurs when configured

The only difference is that providers without RP-Initiated Logout support no longer receive logout requests they cannot handle.

Compatibility

• ✅ Backward compatible - existing configurations continue to work
• ✅ Forward compatible - new optional behavior
• ✅ Works with all OIDC providers (Azure AD, Okta, Keycloak, Authelia, Google, etc.)
• ✅ No database migration required
• ✅ No breaking changes

References

• Issue: Authelia doesn't support RP-Initiated Logout
• OIDC Spec: RP-Initiated Logout
• Related: end_session_endpoint is optional in OIDC providers