VOOZH about

URL: https://deepwiki.com/mathsgod/light/5.2.5-oauth-and-social-login

⇱ OAuth and Social Login | mathsgod/light | DeepWiki

Loading...
Loading...
Last indexed: 31 January 2026 (cf9511)
Menu

OAuth and Social Login

Purpose and Scope

This document covers the OAuth 2.0 and social login integration in the Light framework, which enables users to authenticate using third-party identity providers. The system supports Google, Microsoft, and Facebook as authentication providers, allowing both standalone social login and account linking for existing users.

For information about password-based authentication, see Password Authentication. For JWT token structure and session management after social login, see JWT Token System.

System Overview

The Light framework implements OAuth 2.0 authentication through a dual-mode system:

  1. Standalone Social Login: Users can authenticate directly using their social provider account. The system looks up the user by provider ID and creates a session.
  2. Account Linking: Authenticated users can link multiple social provider accounts to their profile, enabling login via any linked provider.

All OAuth mutations are exposed through GraphQL via the AuthController class and follow a token-based verification pattern where the frontend obtains OAuth credentials from providers and submits them to the backend for validation.

Sources: src/Controller/AuthController.php1-636

Supported OAuth Providers

The system supports three OAuth providers, each with distinct integration patterns:

ProviderField in User ModelConfiguration KeyToken TypeValidation Method
Googlegoogleauthentication_google_client_idJWT ID TokenGoogle API Client verification
Microsoftmicrosoftauthentication_microsoft_client_idAccess TokenMicrosoft Graph API
Facebookfacebookauthentication_facebook_app_idAccess TokenFacebook Graph API

Provider-Specific Integration Details

Google: Uses the google/apiclient package to verify JWT ID tokens. The system validates the token signature and extracts the sub (subject) claim as the unique user identifier.

Microsoft: Validates access tokens by calling the Microsoft Graph API (https://graph.microsoft.com/v1.0/me) and uses the id field from the response as the unique identifier.

Facebook: Validates access tokens by calling the Facebook Graph API (https://graph.facebook.com/me) and uses the id field as the unique identifier.

Sources: src/Controller/AuthController.php204-234 src/Controller/AuthController.php237-267 src/Controller/AuthController.php270-300

OAuth Authentication Flow



Sources: src/Controller/AuthController.php303-330 src/Controller/AuthController.php237-267 src/Controller/AuthController.php270-300




GraphQL OAuth Mutations


Login Mutations


All login mutations follow a similar pattern: validate the OAuth token with the provider, look up the user by provider ID, and create a session.


lightAuthLoginGoogle




Implementation Details:


    

  • Validates JWT ID token using Google_Client::verifyIdToken()
    • 

  • Extracts payload['sub'] as the unique Google user identifier
    • 

  • Requires google/apiclient composer package
    • 

  • Requires authentication_google_client_id configuration
    • 

  • Looks up user with google field matching and status = 0 (active)
    • 

  • Calls $app->userLogin($user) on success
    • 



Sources: src/Controller/AuthController.php303-330


lightAuthLoginMicrosoft




Implementation Details:


    

  • Validates access token by calling https://graph.microsoft.com/v1.0/me
    • 

  • Uses GuzzleHttp client with SSL verification disabled
    • 

  • Extracts id field from Microsoft Graph API response
    • 

  • Requires authentication_microsoft_client_id configuration
    • 

  • Looks up user with microsoft field matching and status = 0
    • 



Sources: src/Controller/AuthController.php237-267


lightAuthLoginFacebook




Implementation Details:


    

  • Validates access token by calling https://graph.facebook.com/me?fields=id,name,email
    • 

  • Uses GuzzleHttp client with SSL verification disabled
    • 

  • Extracts id field from Facebook Graph API response
    • 

  • Requires authentication_facebook_app_id configuration
    • 

  • Looks up user with facebook field matching and status = 0
    • 



Sources: src/Controller/AuthController.php270-300




Account Linking


Authenticated users can link social provider accounts to their profile using registration mutations. These mutations require the @Logged annotation and are only available to authenticated users.




Sources: src/Controller/AuthController.php204-234 src/Controller/AuthController.php188-201 src/Controller/AuthController.php121-150


Registration Mutations


lightAuthRegisterGoogle




Behavior:


    

  1. Validates Google JWT credential using Google_Client::verifyIdToken()
    2. 

  2. Resets any existing users with the same Google ID (sets google = "")
    3. 

  3. Stores payload['sub'] in current user's google field
    4. 

  4. Enforces one-to-one mapping: one Google account can only link to one user
    5. 



Sources: src/Controller/AuthController.php204-234


lightAuthRegisterMicrosoft




Behavior:


    

  1. Accepts Microsoft account ID directly (no validation)
    2. 

  2. Resets any existing users with the same Microsoft ID
    3. 

  3. Stores account_id in current user's microsoft field
    4. 



Sources: src/Controller/AuthController.php188-201


lightAuthRegisterFacebook




Behavior:


    

  1. Validates access token with Facebook Graph API
    2. 

  2. Resets any existing users with the same Facebook ID
    3. 

  3. Stores Facebook id in current user's facebook field
    4. 



Sources: src/Controller/AuthController.php121-150




Account Unlinking


Users can unlink social provider accounts through dedicated mutations. All unlinking mutations require authentication via @Logged annotation.



























MutationEffectGraphQL Signature
lightAuthUnlinkGoogleSets user->google = ""mutation { lightAuthUnlinkGoogle }
lightAuthUnlinkMicrosoftSets user->microsoft = ""mutation { lightAuthUnlinkMicrosoft }
lightAuthUnlinkFacebookSets user->facebook = ""mutation { lightAuthUnlinkFacebook }


Implementation: All three mutations follow identical patterns:


    

  1. Check if provider field is set
    2. 

  2. Clear the provider field
    3. 

  3. Call $user->save()
    4. 

  4. Return true
    5. 



Sources: src/Controller/AuthController.php174-183 src/Controller/AuthController.php163-172 src/Controller/AuthController.php152-161




Configuration Requirements


Database Configuration


OAuth provider settings are stored in the Config model and retrieved using Config::Value():




User Model Schema


The User model must include the following fields to store provider identifiers:































FieldTypePurposeExample Value
googlestringGoogle subject identifier"109234567890123456789"
microsoftstringMicrosoft account ID"abc123def456..."
facebookstringFacebook user ID"123456789012345"


Required Dependencies


Google authentication requires the optional google/apiclient package:




The system checks for package installation before allowing Google operations:




Sources: src/Controller/AuthController.php208-210 src/Controller/AuthController.php212-214 src/Controller/AuthController.php240-242 src/Controller/AuthController.php274-275




Token Validation Mechanics


Google JWT Validation


Google uses JWT ID tokens that must be verified server-side to prevent token forgery:




Implementation:


    

  • Creates Google_Client instance with configured client_id
    • 

  • Uses GuzzleHttp client with SSL verification disabled
    • 

  • Calls verifyIdToken() which validates JWT signature against Google's public keys
    • 

  • Returns payload containing sub (subject), email, name, etc.
    • 



Sources: src/Controller/AuthController.php216-218 src/Controller/AuthController.php314-316


Microsoft Access Token Validation


Microsoft uses opaque access tokens validated by calling the Microsoft Graph API:




Implementation:


    

  • Creates GuzzleHttp client with SSL verification disabled
    • 

  • Makes GET request to https://graph.microsoft.com/v1.0/me
    • 

  • Includes access token in Authorization: Bearer {token} header
    • 

  • Parses JSON response to extract id field
    • 



Sources: src/Controller/AuthController.php244-254 src/Controller/AuthController.php248-252


Facebook Access Token Validation


Facebook uses opaque access tokens validated via the Facebook Graph API:




Implementation:


    

  • Creates GuzzleHttp client with SSL verification disabled
    • 

  • Makes GET request to https://graph.facebook.com/me?fields=id,name,email
    • 

  • Includes access token in Authorization: Bearer {token} header
    • 

  • Parses JSON response to extract id field
    • 



Sources: src/Controller/AuthController.php277-287 src/Controller/AuthController.php280-285




Session Creation After OAuth


After successful OAuth validation, the system creates a user session by calling $app->userLogin($user). This method performs the following operations:


    

  1. Generate JWT Tokens: Creates access token (short-lived) and refresh token (long-lived)
    2. 

  2. Set HTTP Cookies: Stores tokens in secure, HTTP-only cookies
    3. 

  3. Create UserLog Entry: Records login event with IP, user agent, and JWT ID (jti)
    4. 

  4. Return Control: Allows GraphQL mutation to return true
    5. 



The JWT tokens include the user's ID and permissions, enabling stateless authentication for subsequent requests. See JWT Token System for detailed information about token structure and lifecycle.


Sources: src/Controller/AuthController.php262 src/Controller/AuthController.php295 src/Controller/AuthController.php327




Security Considerations


One-to-One Provider Mapping


The system enforces that each OAuth provider ID can only be linked to one user account at a time. When linking a provider to a user, the system first resets all existing users with that provider ID:




This prevents multiple users from sharing the same social login credentials.


Sources: src/Controller/AuthController.php225-228 src/Controller/AuthController.php193-196 src/Controller/AuthController.php138-141


Active User Requirement


All OAuth login mutations include a status = 0 filter when querying users:




This ensures that disabled or inactive user accounts cannot authenticate via social login, even if their OAuth credentials are valid.


Sources: src/Controller/AuthController.php322 src/Controller/AuthController.php257 src/Controller/AuthController.php290


SSL Verification Disabled


All OAuth token validation uses GuzzleHttp clients with SSL verification disabled:




This configuration may be necessary in development environments but should be reviewed for production deployments where proper SSL certificate validation is critical.


Sources: src/Controller/AuthController.php125-127 src/Controller/AuthController.php217 src/Controller/AuthController.php244-246 src/Controller/AuthController.php277-279


Configuration Validation


Before processing OAuth requests, the system verifies that required configuration values are present:




This prevents runtime errors and provides clear error messages to administrators when OAuth is not properly configured.


Sources: src/Controller/AuthController.php310-312 src/Controller/AuthController.php240-242 src/Controller/AuthController.php273-275




Error Handling


All OAuth mutations throw GraphQL\Error\Error exceptions for error conditions:















































Error MessageConditionGraphQL Mutation
"google/apiclient is not installed"Missing Google API Client packagelightAuthLoginGoogle, lightAuthRegisterGoogle
"google client id is not set"Missing configurationlightAuthLoginGoogle, lightAuthRegisterGoogle
"Microsoft client id is not set"Missing configurationlightAuthLoginMicrosoft
"Facebook app id is not set"Missing configurationlightAuthLoginFacebook
"Google login error"Token validation failed or user not foundlightAuthLoginGoogle, lightAuthRegisterGoogle
"Microsoft login error"Token validation failed or user not foundlightAuthLoginMicrosoft
"Facebook login error"Token validation failed or user not foundlightAuthLoginFacebook


Errors are propagated to the GraphQL client as part of the standard GraphQL error response structure.


Sources: src/Controller/AuthController.php209-210 src/Controller/AuthController.php212-214 src/Controller/AuthController.php221-222 src/Controller/AuthController.php240-242 src/Controller/AuthController.php273-275 src/Controller/AuthController.php318-320 src/Controller/AuthController.php258-260 src/Controller/AuthController.php291-293