OAuth Authorization Code Flow Migration

[ahmadhamzh]

OAuth Authorization Code Flow Migration

Ref: #1105

Overview

The current authentication mechanism relies on the OAuth Implicit Flow, where tokens are issued directly to the browser and handled by the frontend. This approach introduces several security concerns, including token exposure in URL fragments and access via JavaScript.

To address these limitations, this proposal recommends migrating to the Authorization Code Flow, with token exchange handled by the backend.

---

Motivation

The Implicit Flow is no longer considered best practice due to:

• Token leakage via URL fragments
• Exposure to XSS attacks (tokens accessible in JS)
• Lack of refresh token support
• Short-lived sessions requiring frequent re-authentication

---

Proposed Architecture

• Use Authorization Code Flow with OIDC
• Perform code exchange on the backend
• Store tokens in HttpOnly, Secure cookies
• Introduce refresh tokens for long-lived sessions
• Implement token rotation for improved security

---

Benefits

Area	Improvement
Security	Tokens are never exposed to the browser
Session UX	Long-lived sessions (up to 30 days)
Token Handling	Backend-managed lifecycle
Standards	Aligns with modern OAuth best practices

---

Authentication Flows

Login Flow

This diagram illustrates the authentication process from the moment the user initiates login until the backend sets the authentication cookies.

Key points:

• Authorization code is exchanged on the backend
• Tokens are never exposed to the browser
• Session is established via HttpOnly cookies

Refresh Flow

This diagram illustrates how the application maintains an active session using refresh tokens.

Key points:

• The ID token is short-lived (1 hour)
• The client performs a silent refresh before expiration (55 minutes)
• The backend uses the refresh token to issue a new ID token
• The refresh token is rotated on each use for improved security

Logout Flow

This diagram shows how a user session is securely terminated.

Key points:

• The client sends a logout request to the backend
• The backend clears authentication cookies
• Any stored session or refresh token is invalidated

---

API Design

Endpoint	Method	Description
/api/v2/auth/login	GET	Initiates authentication flow
/api/v2/auth/callback	GET	Handles OIDC callback
/api/v2/auth/refresh	POST	Refreshes tokens
/api/v2/auth/logout	POST	Terminates session

---

Token Strategy

• ID Token TTL: 1 hour (configurable via the OIDC provider)
• Refresh Token TTL: 30 days (configurable via the OIDC provider)
• Rotation: Enabled (recommended)
• Refresh Mechanism: Silent background refresh

This ensures a balance between security and user experience, minimizing re-authentication while limiting token exposure.

---

Considerations

• CSRF protection for cookie-based authentication
• Secure cookie configuration (HttpOnly, Secure, SameSite)
• Handling refresh failures (fallback to login or prompt)

---

Conclusion

Migrating to the Authorization Code Flow significantly improves the security posture of the application while providing a smoother user experience through long-lived sessions and controlled token management.

---

Feedback

Please share any concerns, suggestions, or edge cases that should be addressed before implementation.

[judge-red]

At a quick glance, this sounds nice, thanks! However, I think it doesn't use PKCE. Was this considered? (Not sure Dex/Keycloak support it, tbh.)

[ahmadhamzh]

At a quick glance, this sounds nice, thanks! However, I think it doesn't use PKCE. Was this considered? (Not sure Dex/Keycloak support it, tbh.)

Thanks for the feedback!
We will consider that in our implementation, but since Dex has only recently started supporting PKCE, I want to look into it more during implementation. We will definitely take it into account.
I’ve updated the login flow diagram