`FRONT_URL=https://forms.example.com` | | `client/.env` | `NUXT_PUBLIC_APP_URL=https://forms.example.com`
`NUXT_PUBLIC_API_BASE=https://forms.example.com/api` |
Simplified Controller] OAuthFlowOrchestrator[OAuthFlowOrchestrator
Main Orchestrator] subgraph "OAuth Services" OAuthContextService[OAuthContextService
State Management] OAuthUserDataService[OAuthUserDataService
Data Extraction] OAuthInviteService[OAuthInviteService
Invite Validation] OAuthUserService[OAuthUserService
User Management] OAuthProviderService[OAuthProviderService
Provider Management] end subgraph "Supporting Services" WorkspaceInviteService[WorkspaceInviteService
Workspace Creation] end subgraph "OAuth Drivers" GoogleDriver[OAuthGoogleDriver
+ Email Restrictions] GoogleOneTapDriver[OAuthGoogleOneTapDriver] StripeDriver[OAuthStripeDriver] TelegramDriver[OAuthTelegramDriver] NewDriver[OAuthNewProviderDriver] end subgraph "Data Layer" UserModel[User Model] OAuthProviderModel[OAuthProvider Model] Cache[Laravel Cache
State Storage] end end subgraph "External Services" GoogleOAuth[Google OAuth] StripeOAuth[Stripe Connect] TelegramWidget[Telegram Widget] NewProviderOAuth[New Provider OAuth] end %% Frontend to Backend API calls UI --> useOAuth useOAuth --> OAuthController useAuthFlow --> OAuthController %% Controller to Orchestrator OAuthController --> OAuthFlowOrchestrator %% Orchestrator coordination OAuthFlowOrchestrator --> OAuthContextService OAuthFlowOrchestrator --> OAuthUserDataService OAuthFlowOrchestrator --> OAuthInviteService OAuthFlowOrchestrator --> OAuthUserService OAuthFlowOrchestrator --> OAuthProviderService %% Service dependencies OAuthUserService --> WorkspaceInviteService OAuthInviteService --> GoogleDriver OAuthUserDataService --> GoogleDriver OAuthUserDataService --> GoogleOneTapDriver OAuthUserDataService --> StripeDriver OAuthUserDataService --> TelegramDriver %% Drivers to External Services GoogleDriver --> GoogleOAuth GoogleOneTapDriver --> GoogleOAuth StripeDriver --> StripeOAuth TelegramDriver --> TelegramWidget NewDriver --> NewProviderOAuth %% Data persistence OAuthUserService --> UserModel OAuthProviderService --> OAuthProviderModel OAuthContextService --> Cache WorkspaceInviteService --> UserModel %% Cross-window communication useWindowMessage -.->|"OAuth Callbacks"| useOAuth useWindowMessage -.->|"Cache Invalidation"| TanStackQuery %% Cache invalidation TanStackQuery -.->|"Refetch on Changes"| useOAuth classDef frontend fill:#e1f5fe classDef backend fill:#f3e5f5 classDef external fill:#fff3e0 classDef data fill:#e8f5e8 classDef orchestrator fill:#e8f4f8 class UI,useOAuth,useWindowMessage,useAuthFlow,TanStackQuery frontend class OAuthController,OAuthContextService,OAuthUserDataService,OAuthInviteService,OAuthUserService,OAuthProviderService,WorkspaceInviteService,GoogleDriver,GoogleOneTapDriver,StripeDriver,TelegramDriver,NewDriver backend class OAuthFlowOrchestrator orchestrator class GoogleOAuth,StripeOAuth,TelegramWidget,NewProviderOAuth external class UserModel,OAuthProviderModel,Cache data ``` ## Core Components ### 1. OAuthController (`api/app/Http/Controllers/Auth/OAuthController.php`) The simplified controller that delegates all OAuth logic to the orchestrator: ```php theme={null} class OAuthController extends Controller { public function __construct( private OAuthFlowOrchestrator $flowOrchestrator ) {} // Initiates OAuth flow using validated request public function redirect(OAuthRedirectRequest $request, string $provider) { return response()->json( $this->flowOrchestrator->processRedirect( $provider, $request->validated() ) ); } // Handles standard OAuth callbacks public function callback(Request $request, string $provider) { $params = $request->all(); $result = $this->flowOrchestrator->processCallback($provider, $params); return response()->json($result); } // Handles widget-based OAuth public function handleWidgetCallback(Request $request, string $service) { $result = $this->flowOrchestrator->processWidgetCallback($service, $request); return response()->json($result); } } ``` **Key Features:** * **Simplified Architecture**: All logic delegated to `OAuthFlowOrchestrator` * **Request Validation**: Uses `OAuthRedirectRequest` for structured validation * **Consistent Responses**: Standardized JSON response format ### 2. OAuthFlowOrchestrator (`api/app/Service/OAuth/OAuthFlowOrchestrator.php`) The main orchestrator service that coordinates all OAuth flows: ```php theme={null} class OAuthFlowOrchestrator { public const INTENT_AUTH = 'auth'; public const INTENT_INTEGRATION = 'integration'; public function __construct( private OAuthContextService $contextService, private OAuthInviteService $inviteService, private OAuthUserDataService $userDataService, private OAuthUserService $oauthUserService, private OAuthProviderService $oauthProviderService ) {} // Process OAuth redirect with state management public function processRedirect(string $provider, array $params): array // Process OAuth callback with context restoration public function processCallback(string $provider, array $params): array // Process widget-based OAuth public function processWidgetCallback(string $service, Request $request): array } ``` **Key Features:** * **Centralized Coordination**: Single entry point for all OAuth flows * **State Management**: Handles OAuth state tokens for security * **Invite Integration**: Supports workspace invitations with email restrictions * **Intent-based Routing**: Routes to appropriate flow based on auth vs integration intent ### 3. OAuthContextService (`api/app/Service/OAuth/OAuthContextService.php`) Service that manages OAuth context using secure state tokens: ```php theme={null} class OAuthContextService { // Store context with unique state token public function storeContext(array $context): string // Retrieve context using state token public function getContext(?string $stateToken = null): ?array // Clear context after use public function clearContext(?string $stateToken = null): void // Get specific context values public function getIntent(): string public function getInvitedEmail(): ?string public function getInviteToken(): ?string } ``` **Key Features:** * **State Token Security**: Uses cryptographically secure state tokens instead of session storage * **Context Isolation**: Each OAuth flow has isolated context * **Automatic Cleanup**: Context automatically expires and clears after use ### 4. OAuthUserDataService (`api/app/Service/OAuth/OAuthUserDataService.php`) Service that extracts and normalizes user data from OAuth providers: ```php theme={null} class OAuthUserDataService { // Extract user data from standard OAuth redirect public function extractFromRedirect(OAuthProviderService $providerService): array // Extract user data from widget-based authentication public function extractFromWidget(OAuthProviderService $providerService, Request $request): array } ``` **Key Features:** * **Data Normalization**: Standardizes user data across different OAuth providers * **Widget Support**: Handles both redirect and widget-based authentication flows * **Error Handling**: Validates and verifies OAuth provider responses ### 5. OAuthInviteService (`api/app/Service/OAuth/OAuthInviteService.php`) Service that handles workspace invitations and email restrictions: ```php theme={null} class OAuthInviteService { // Validate invite token public function validateInviteToken(string $inviteToken): UserInvite // Get invited email from token public function getInvitedEmail(string $inviteToken): string // Configure driver with email restrictions public function configureDriverEmailRestrictions(OAuthDriver $driver, ?string $invitedEmail = null): void // Validate email matches invitation public function validateEmailRestrictions(string $email, ?string $invitedEmail = null): void } ``` **Key Features:** * **Invite Validation**: Validates workspace invitation tokens * **Email Restrictions**: Enforces email restrictions for OAuth providers that support it * **Capability-based**: Uses interfaces to determine if driver supports email restrictions ### 6. OAuthUserService (`api/app/Service/OAuth/OAuthUserService.php`) Service that handles user-related OAuth operations: ```php theme={null} class OAuthUserService { // Find or create user from OAuth data public function findOrCreateUser(array $userData, OAuthProviderService $providerService, ?string $inviteToken = null): User } ``` **Key Features:** * **User Management**: Creates new users or finds existing ones * **Workspace Integration**: Uses `WorkspaceInviteService` for workspace assignment * **UTM Tracking**: Preserves UTM data for analytics ### 7. OAuthProviderService (`api/app/Service/OAuth/OAuthProviderService.php`) Service that handles OAuth provider record management: ```php theme={null} class OAuthProviderService { // Create or update OAuth provider record public function createOrUpdateProvider(User $user, OAuthProviderService $providerService, array $userData): OAuthProvider } ``` **Key Features:** * **Provider Records**: Manages OAuth provider connections in database * **Token Management**: Stores and updates OAuth access/refresh tokens * **Scope Tracking**: Records granted OAuth scopes ### 8. WorkspaceInviteService (`api/app/Service/WorkspaceInviteService.php`) Service extracted from `RegisterController` that handles workspace creation and invitation acceptance: ```php theme={null} class WorkspaceInviteService { // Get workspace and role based on invitation public function getWorkspaceAndRole(array $data): array } ``` **Key Features:** * **Workspace Creation**: Creates new workspaces for users without invitations * **Invite Processing**: Handles workspace invitation acceptance with atomic updates * **Role Assignment**: Assigns appropriate roles based on invitation or default admin role ### 9. OAuth Drivers Each provider implements the `OAuthDriver` interface with updated methods: ```php theme={null} interface OAuthDriver { public function getRedirectUrl(): string; public function setRedirectUrl(string $url): self; public function setScopes(array $scopes): self; public function setState(string $state): self; // New: Required for state token security public function getUser(): User; public function canCreateUser(): bool; public function getScopesForIntent(string $intent): array; } ``` For widget-based providers, implement `WidgetOAuthDriver`: ```php theme={null} interface WidgetOAuthDriver extends OAuthDriver { public function verifyWidgetData(array $data): bool; public function getUserFromWidgetData(array $data): array; public function isWidgetBased(): bool; } ``` ### 10. Email Restrictions For providers that support email restrictions (like Google), implement `SupportsEmailRestrictions`: ```php theme={null} interface SupportsEmailRestrictions { /** * Set email restrictions/hints for the OAuth flow */ public function setEmailRestrictions(array $emails): self; /** * Check if this driver supports email restrictions */ public function supportsEmailRestrictions(): bool; } ``` The system includes a trait to simplify implementation: ```php theme={null} use App\Integrations\OAuth\Drivers\Traits\HasEmailRestrictions; class OAuthGoogleDriver implements OAuthDriver, SupportsEmailRestrictions { use HasEmailRestrictions; // The trait provides: // - setEmailRestrictions(array $emails): self // - supportsEmailRestrictions(): bool // - getPrimaryEmail(): ?string // - isEmailAllowed(string $email): bool // - getEmailRestrictionParameters(): array } ``` **Email Restrictions Features:** * **Invite Integration**: Automatically configures email hints when OAuth is used for workspace invitations * **Login Hints**: Providers like Google receive `login_hint` parameter to pre-fill login form * **Email Validation**: Validates OAuth email matches invited email during authentication * **Capability-based**: Only applied to drivers that implement `SupportsEmailRestrictions` ## OAuth Flow Types ### Authentication Flow (User Login/Registration) ```mermaid theme={null} flowchart TD A["User clicks 'Sign in with Provider'"] --> B["Frontend: useOAuth.guestConnect()"] B --> C["API: POST /oauth/connect/provider?intent=auth&invite_token=xyz"] C --> D["OAuthFlowOrchestrator.processRedirect()"] D --> E["Validate intent & invite token"] E --> F["Generate secure state token"] F --> G["Store context in cache with state"] G --> H["Configure driver with scopes & email restrictions"] H --> I["Generate OAuth redirect URL with state"] I --> J["Open OAuth provider window"] J --> K["User authorizes at provider"] K --> L["Provider redirects to callback with state"] L --> M["API: GET /oauth/provider/callback?state=xyz&code=abc"] M --> N["OAuthFlowOrchestrator.processCallback()"] N --> O["Retrieve context using state token"] O --> P["Clear context after retrieval"] P --> Q["Extract user data from provider"] Q --> R["Validate email matches invite (if present)"] R --> S["Find or create user"] S --> T["Handle workspace invitation"] T --> U["Create OAuth provider record"] U --> V["Generate JWT token"] V --> W["Return token response"] W --> X["Frontend: Store token"] X --> Y["Send LOGIN_COMPLETE message"] Y --> Z["Close OAuth window"] Z --> AA["Redirect to dashboard"] E --> BB{Invalid invite?} BB -->|Yes| CC["Return error"] O --> DD{Context expired?} DD -->|Yes| EE["Return 419 error"] R --> FF{Email mismatch?} FF -->|Yes| GG["Return email error"] subgraph "Window Communication" HH["OAuth Callback Window"] --> II["useWindowMessage.send()"] II --> JJ["Parent Window Listener"] JJ --> KK["Cache invalidation"] KK --> LL["UI updates"] end classDef process fill:#e3f2fd classDef decision fill:#fff3e0 classDef error fill:#ffebee classDef communication fill:#f3e5f5 classDef state fill:#e8f4f8 class A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,AA process class BB,DD,FF decision class CC,EE,GG error class HH,II,JJ,KK,LL communication class F,G,O,P state ``` ```mermaid theme={null} sequenceDiagram participant U as User participant F as Frontend participant API as OAuthController participant Orch as OAuthFlowOrchestrator participant Ctx as OAuthContextService participant P as OAuth Provider participant Inv as OAuthInviteService participant US as OAuthUserService U->>F: Click "Sign in with Provider" F->>API: POST /oauth/connect/{provider}?intent=auth&invite_token=xyz API->>Orch: processRedirect(provider, params) Orch->>Inv: validateInviteToken(xyz) & getInvitedEmail() Inv-->>Orch: email@domain.com Orch->>Ctx: storeContext({intent, invite_token, invited_email}) Ctx-->>Orch: stateToken: abc123 Orch->>Orch: Configure driver with email restrictions Orch-->>API: {url: oauth_url, state: abc123} API->>P: Redirect user to OAuth provider P->>U: User authorizes app P->>API: Callback with state=abc123&code=def456 API->>Orch: processCallback(provider, params) Orch->>Ctx: getContext(abc123) Ctx-->>Orch: {intent: auth, invited_email: email@domain.com} Orch->>Ctx: clearContext(abc123) Orch->>Orch: Extract user data from provider Orch->>Inv: validateEmailRestrictions(user_email, invited_email) Orch->>US: findOrCreateUser(userData, provider, invite_token) US->>US: Create user & handle workspace invitation US-->>Orch: User object with JWT Orch-->>API: {token, user_data} API->>F: Return JWT token F->>F: Store token, redirect to dashboard ``` **Key Features of New Flow:** 1. **State Token Security**: Each OAuth flow gets a unique, cryptographically secure state token 2. **Context Isolation**: Context is stored with state token, preventing cross-request interference 3. **Invite Integration**: Workspace invitations are validated and email restrictions applied automatically 4. **Automatic Cleanup**: Context is cleared after successful use to prevent replay attacks 5. **Email Validation**: For invites, OAuth email must match the invited email address 6. **Error Handling**: Comprehensive error handling for expired contexts, invalid invites, email mismatches ### Integration Flow (Connect Account) ```mermaid theme={null} sequenceDiagram participant U as Logged User participant F as Frontend participant API as OAuthController participant Orch as OAuthFlowOrchestrator participant Ctx as OAuthContextService participant P as OAuth Provider participant PS as OAuthProviderService U->>F: Click "Connect Account" F->>API: POST /oauth/connect/{provider}?intent=integration&autoClose=true API->>Orch: processRedirect(provider, params) Orch->>Ctx: storeContext({intent: integration, autoClose: true, intention: 'settings'}) Ctx-->>Orch: stateToken: xyz456 Orch->>Orch: Configure driver with integration scopes Orch-->>API: {url: oauth_url, state: xyz456} API->>P: Redirect with full permission scopes P->>U: User authorizes extended permissions P->>API: Callback with state=xyz456&code=def789 API->>Orch: processCallback(provider, params) Orch->>Ctx: getContext(xyz456) Ctx-->>Orch: {intent: integration, autoClose: true, intention: 'settings'} Orch->>Ctx: clearContext(xyz456) Orch->>Orch: Extract user data from provider Orch->>PS: createOrUpdateProvider(user, provider, userData) PS-->>Orch: OAuthProvider record Orch-->>API: {provider: resource, autoClose: true, intention: 'settings'} API->>F: Return provider details + context F->>F: Update UI, invalidate cache ``` **Key Features:** * **Enhanced scopes**: Automatically requests full permissions needed for integrations based on `getScopesForIntent()` * **Context preservation**: Stores `intention`, `autoClose`, and other settings using secure state tokens * **Provider management**: Creates/updates `OAuthProvider` records with full OAuth data * **State security**: Uses same state token security as authentication flows ### Widget Flow (e.g., Telegram) ```mermaid theme={null} sequenceDiagram participant U as User participant W as Widget participant F as Frontend participant API as OAuthController participant Orch as OAuthFlowOrchestrator participant Inv as OAuthInviteService participant UD as OAuthUserDataService participant US as OAuthUserService U->>W: Authenticate with provider widget W->>F: Widget callback with auth data F->>API: POST /oauth/widget-callback/{provider}?intent=auth&invite_token=xyz API->>Orch: processWidgetCallback(provider, request) Orch->>Inv: validateInviteToken(xyz) & getInvitedEmail() [if auth intent] Orch->>UD: extractFromWidget(provider, request) UD->>UD: Verify widget data signature UD->>UD: Extract and normalize user data UD-->>Orch: userData Orch->>Inv: validateEmailRestrictions(user_email, invited_email) [if auth intent] Orch->>US: findOrCreateUser(userData, provider, invite_token) [if auth intent] US->>US: Create user & handle workspace invitation US-->>Orch: User object with JWT Orch-->>API: {token, user_data} or {provider, autoClose, intention} API->>F: Return auth token or provider details F->>F: Update UI, show success ``` **Widget Authentication Features:** * **No redirect flow**: Authentication happens in-place via widget, no OAuth redirect required * **Data verification**: Cryptographic verification of widget data using provider-specific methods * **Direct provider creation**: Immediately creates provider records without state tokens (no callback URL) * **Invite Integration**: Supports workspace invitations with same email validation as redirect flows * **Orchestrated Processing**: Uses same `OAuthFlowOrchestrator` as redirect flows for consistency ## Frontend Integration ### Window Message Communication The frontend uses `useWindowMessage` composable for cross-window communication: ```javascript theme={null} // WindowMessageTypes for consistent messaging export const WindowMessageTypes = { LOGIN_COMPLETE: "login-complete", AFTER_LOGIN: "after-login", OAUTH_PROVIDER_CONNECTED: "oauth-provider-connected", }; // Usage in OAuth callback const { send } = useWindowMessage(WindowMessageTypes.LOGIN_COMPLETE); send(window.opener, { eventType: WindowMessageTypes.LOGIN_COMPLETE, useMessageChannel: false, waitForAcknowledgment: false, }); ``` ### OAuth Composable (`useOAuth`) Centralized OAuth operations with TanStack Query integration: ```javascript theme={null} const { connect, connectMutation, services } = useOAuth(); // Connect to OAuth provider await connect("google", false, true, true); // service, redirect, newtab, autoClose // Service definitions with auth types const services = [ { name: "google", title: "Google", auth_type: "redirect", // Standard OAuth redirect flow }, { name: "telegram", title: "Telegram", auth_type: "widget", // Widget-based authentication widget_file: "TelegramWidget", }, ]; ``` ### Cache Management The system automatically invalidates TanStack Query cache when OAuth connections change: ```javascript theme={null} // Listen for OAuth provider connections windowMessage.listen( (_event) => { invalidateProviders(); // Refresh OAuth providers list }, { useMessageChannel: false, acknowledge: false, } ); ``` ## Adding a New Integration Follow these steps to add a new OAuth provider to OpnForm:
If you need to generate new tokens (e.g. for external scripts) see the [Authentication](../api-reference/introduction#authentication) docs.
Loading…
{{ error.message }}
- {{ ws.name }}