OAuth Flow

Last Updated: May 20, 2025

This document provides an overview of the OAuth authentication flow in the Typus Development Framework.

Overview

OAuth (Open Authorization) is an open standard for access delegation, commonly used as a way for users to grant websites or applications access to their information on other websites without giving them passwords. Typus Framework supports OAuth 2.0 integration with popular providers such as Google.

OAuth Flow Diagram

Supported OAuth Providers

The Typus Framework currently supports the following OAuth providers:

1. Google
   • Authentication via Google accounts
   • Access to basic profile information
   • Optional access to additional Google services

OAuth Process Steps

1. Initialization

1. User clicks "Login with [Provider]" button
2. Frontend requests an OAuth initialization from the backend
3. Backend generates necessary state parameters and constructs the authorization URL
4. User is redirected to the OAuth provider's login page

2. Authorization

1. User logs in to the OAuth provider (if not already logged in)
2. User authorizes the application to access their information
3. OAuth provider redirects back to the application with an authorization code

3. Token Exchange

1. Frontend sends the authorization code to the backend
2. Backend exchanges the code for an access token with the OAuth provider
3. Backend uses the access token to request user information from the provider

4. User Account Management

1. Backend checks if the user already exists in the database
2. If new user, a new account is created with information from the OAuth provider
3. If existing user, the account is updated with the latest information
4. User is authenticated and JWT tokens are generated

5. Session Establishment

1. Backend returns user data and authentication tokens to the frontend
2. Frontend stores tokens for subsequent API requests
3. User is redirected to the appropriate page (typically the dashboard)

API Endpoints

The OAuth flow is handled through two main endpoints:

1. OAuth Initialization Endpoint

   • Initiates the OAuth flow with the selected provider
   • Redirects the user to the provider's authorization page

2. OAuth Callback Endpoint

   • Handles the callback from the OAuth provider
   • Processes the authorization code
   • Authenticates the user and returns tokens

Security Considerations

1. State Parameter: Used to prevent CSRF attacks by validating that the request and callback are part of the same flow
2. Secure Storage: OAuth tokens are securely stored and never exposed to the client
3. Scope Limitation: Only requesting the minimum necessary permissions from the OAuth provider
4. Token Expiration: Access tokens have limited lifetimes and are refreshed as needed
5. HTTPS: All OAuth communication occurs over secure HTTPS connections

Integration with Existing Authentication

The OAuth authentication flow integrates with the existing authentication system:

1. Users can link multiple OAuth providers to a single account
2. Users can switch between password-based and OAuth-based authentication
3. The same JWT tokens are issued regardless of authentication method
4. The same session management applies to all authenticated users

Conclusion

The OAuth integration in Typus Framework provides a secure and user-friendly authentication option. By supporting popular OAuth providers, the framework allows users to authenticate without creating new credentials, while maintaining the security and flexibility of the authentication system.