Create a custom plugin to integrate social logins using joomla 5 rest api

***

Overview and Prerequisites

Joomla 5 introduces the new Web Services API layer which includes RESTful endpoints to interact with Joomla components, including user authentication systems. Building a custom plugin for social login via REST requires:

- Familiarity with Joomla's plugin system, especially authentication plugins.
- Understanding of OAuth 2.0 flows, used by major social platforms like Google, Facebook, and Twitter.
- Knowledge of Joomla 5 REST API architecture.
- Basic PHP programming and Joomla MVC structure.
- Composer for dependency management, if using external OAuth libraries.

***

Step 1: Planning the Plugin Architecture

Joomla uses plugin groups, and social login plugins should be part of the `authentication` group. This leverages Joomla's existing login framework and user session management.

A social login plugin can handle external OAuth login callbacks and communicate with the Joomla user system to:

- Authenticate existing users.
- Register new users based on social profile information.
- Link social accounts with Joomla user IDs.
- Provide API endpoints using Joomla 5 REST Web Services.

Your custom plugin will primarily extend the authentication system but will also require integration with the Web Services API.

***

Step 2: Setting up Plugin Skeleton

Start by creating the filesystem and necessary files:

1. Directory structure:

/plugins/authentication/sociallogin/  
  ├── sociallogin.php  
  ├── sociallogin.xml  
  ├── src/  
      ├── OAuthHandler.php  
      ├── UserManager.php  
      ├── ApiController.php  

2. `sociallogin.xml` for manifest:

- Defines plugin metadata (name, description, version).
- Lists files and declares plugin group `authentication`.
- Registers language files if needed.

Example `sociallogin.xml`:

xml


    plg_authentication_sociallogin
    Your Name
    1.0.0
    Social Login Authentication Plugin for Joomla 5
    
        sociallogin.php
        src
    
    
        
            
                
                
                
                
                
            
        
    

3. `sociallogin.php` main plugin entry point:

- Extends `JPlugin`.
- Implements Joomla's authentication interface.
- Listens to `onUserAuthenticate()` event to integrate social login logic.

***

Step 3: Register Plugin with Joomla Event System

In `sociallogin.php`:

php
loadLanguage();
    }

    public function onUserAuthenticate($credentials, $options, &$response)
    {
        // Check for social login token or code in credentials
        if (empty($credentials['social_provider']) || empty($credentials['social_token'])) {
            return; // Not social login
        }

        $provider = $credentials['social_provider'];
        $token = $credentials['social_token'];

        // Validate token via OAuthHandler.php
        $oauthHandler = new \SocialLogin\OAuthHandler($this->params);

        $userProfile = $oauthHandler->validateToken($provider, $token);

        if (!$userProfile) {
            $response->status = JAuthentication::STATUS_FAILURE;
            $response->error_message = 'Invalid social login token';
            return;
        }

        // Process user profile (map or create Joomla user)
        $userManager = new \SocialLogin\UserManager();
        $joomlaUser = $userManager->getOrCreateUser($userProfile);

        if ($joomlaUser) {
            $response->status = JAuthentication::STATUS_SUCCESS;
            $response->email = $joomlaUser->email;
            $response->username = $joomlaUser->username;
            $response->fullname = $joomlaUser->name;
            $response->userid = $joomlaUser->id;
        } else {
            $response->status = JAuthentication::STATUS_FAILURE;
            $response->error_message = 'Failed to create or link user';
        }
    }
}

***

Step 4: OAuth Token Validation (`OAuthHandler.php`)

The OAuthHandler handles communication with social providers to validate tokens and retrieve user profiles.

Example for Google OAuth:

php
params = $params;
    }

    public function validateToken($provider, $token)
    {
        switch ($provider) {
            case 'google':
                return $this->validateGoogleToken($token);
            case 'facebook':
                return $this->validateFacebookToken($token);
            default:
                return false;
        }
    }

    protected function validateGoogleToken($token)
    {
        $url = $this->googleEndpoint . urlencode($token);
        $response = $this->makeHttpRequest($url);

        if (!$response || empty($response->email_verified) || $response->email_verified != 'true') {
            return false;
        }

        return [
            'id' => $response->sub,
            'email' => $response->email,
            'name' => $response->name ?? '',
            'avatar' => $response->picture ?? ''
        ];
    }

    protected function validateFacebookToken($token)
    {
        $appId = $this->params->get('facebook_app_id');
        $appSecret = $this->params->get('facebook_app_secret');
        $debugTokenUrl = "https://graph.facebook.com/debug_token?input_token=$token&access_token=$appId|$appSecret";

        $debugResponse = $this->makeHttpRequest($debugTokenUrl);

        if (empty($debugResponse->data->is_valid)) {
            return false;
        }

        $userProfileUrl = "https://graph.facebook.com/me?fields=id,name,email,picture&access_token=$token";

        $profile = $this->makeHttpRequest($userProfileUrl);

        if (empty($profile->email)) {
            return false;
        }

        return [
            'id' => $profile->id,
            'email' => $profile->email,
            'name' => $profile->name,
            'avatar' => $profile->picture->data->url ?? ''
        ];
    }

    protected function makeHttpRequest($url)
    {
        $opts = [
            "http" => [
                "method" => "GET",
                "header" => "User-Agent: Joomla-SocialLoginPlugin\r\n"
            ]
        ];

        $context = stream_context_create($opts);

        $result = @file_get_contents($url, false, $context);

        if ($result === false) {
            return false;
        }

        return json_decode($result);
    }
}

***

Step 5: User Management (`UserManager.php`)

This module checks for existing users by email or social ID, creates new Joomla users when needed, and links social account data.

php
getQuery(true)
            ->select($db->quoteName(['id', 'username', 'name', 'email']))
            ->from($db->quoteName('#__users'))
            ->where($db->quoteName('email') . ' = ' . $db->quote($profile['email']));

        $db->setQuery($query);
        $userData = $db->loadObject();

        if ($userData) {
            return $this->getUserObject($userData);
        }

        return $this->createUser($profile);
    }

    protected function createUser($profile)
    {
        $user = new User;
        $user->name = $profile['name'] ?: 'Social User';
        $user->username = $this->generateUsername($profile['email']);
        $user->email = $profile['email'];
        $user->passwordClear = $this->generateRandomPassword();
        $user->block = 0;
        $user->activation = '';
        $user->groups = [2];  // Registered group

        if (!$user->save()) {
            return false;
        }

        return $user;
    }

    protected function generateUsername($email)
    {
        $username = strstr($email, '@', true);
        return $username ?: 'user_' . uniqid();
    }

    protected function generateRandomPassword($length = 12)
    {
        return bin2hex(random_bytes($length / 2));
    }

    protected function getUserObject($data)
    {
        $user = new User($data->id);
        return $user;
    }
}

***

Step 6: Handling OAuth Redirects and Token Exchanges

Since OAuth requires redirecting to social providers and handling callbacks, you can implement a custom API controller to manage these.

Create `ApiController.php` inside `src` folder for REST API management:

php
input;
        $provider = $input->get('provider', '', 'cmd');
        $code = $input->get('code', '', 'string');

        if (!$provider || !$code) {
            return $this->sendResponse(['error' => 'Invalid request'], 400);
        }

        $oauthHandler = new OAuthHandler($this->params);
        $token = $oauthHandler->exchangeCodeForToken($provider, $code);

        if (!$token) {
            return $this->sendResponse(['error' => 'Failed to exchange code for token'], 400);
        }

        $userProfile = $oauthHandler->validateToken($provider, $token);

        if (!$userProfile) {
            return $this->sendResponse(['error' => 'Invalid token or profile'], 400);
        }

        $userManager = new UserManager();
        $joomlaUser = $userManager->getOrCreateUser($userProfile);

        if (!$joomlaUser) {
            return $this->sendResponse(['error' => 'User creation failed'], 500);
        }

        // Authenticate Joomla session
        $credentials = ['username' => $joomlaUser->username, 'password' => ''];
        $options = ['silent' => true];
        $app = Factory::getApplication();
        $result = $app->login($credentials, $options);

        if ($result !== true) {
            return $this->sendResponse(['error' => 'Joomla login failed'], 401);
        }

        return $this->sendResponse(['message' => 'Login successful', 'user' => [
            'id' => $joomlaUser->id,
            'username' => $joomlaUser->username,
            'email' => $joomlaUser->email,
            'name' => $joomlaUser->name
        ]], 200);
    }

    protected function sendResponse($data, $statusCode = 200)
    {
        http_response_code($statusCode);
        header('Content-Type: application/json');
        echo json_encode($data);
        exit;
    }
}

The controller manages the OAuth authorization code exchange and returns JSON responses, suitable for a client application calling Joomla REST API endpoints.

***

Step 7: Integrating with Joomla REST API System

To expose your plugin functionality through Joomla 5's REST API, register your custom API controller in Joomla's Web Services routing.

1. Create `services.json` in your plugin folder for routing definition:

json
{
    "authentication": {
        "sociallogin": {
            "controller": "ApiController",
            "actions": {
                "login": {
                    "method": "POST",
                    "path": "/sociallogin/login"
                }
            },
            "defaults": {
                "format": "json"
            }
        }
    }
}

2. Load this during plugin registration or API router initialization.

3. Clients can now POST to `/rest/v1/sociallogin/login` with provider and OAuth code to initiate login.

***

Step 8: Registering OAuth Redirect URI

The redirect URI must be registered in the social providers dashboard corresponding to your Joomla URL endpoint that handles OAuth responses.

For example, for Google, it should be something like:

https://your-joomla-site.com/rest/v1/sociallogin/login

The plugin must handle the OAuth code exchange at this endpoint and then authenticate the user in Joomla.

***

Step 9: Configuring Plugin Parameters

In Joomla administrator interface, configure your plugin by entering:

- Google Client ID and Secret
- Facebook App ID and Secret
- OAuth redirect URL (should point to REST API endpoint)
- Additional settings for scopes and user field mappings if required

***

Step 10: Security Considerations

- Validate all OAuth tokens on the server side using the providers' token introspection or validation endpoints.
- Ensure HTTPS is enforced for all OAuth flow endpoints.
- Proper error handling and logging for debugging authentication errors.
- Map social profiles carefully to Joomla users to avoid duplicate or unauthorized accounts.
- Use Joomla's built-in user groups and ACL to define appropriate permissions for social login users.

***

Step 11: User Experience Flow

Typical user flow for social login using your custom plugin:

- User clicks “Login with Google/Facebook” button on Joomla site.
- Browser redirects to the social provider's OAuth authorization screen.
- User authorizes and is redirected to your OAuth redirect URI.
- Joomla REST API controller receives authorization code.
- Controller exchanges code for access token and validates it.
- Plugin checks if Joomla user exists or creates a new user.
- User is authenticated in Joomla session.
- API returns login success with user details.
- Frontend reacts accordingly and updates UI.

***

Additional Enhancements

- Support multiple social providers beyond Google and Facebook.
- Allow users to link/unlink social accounts from their Joomla profiles.
- Integrate with Joomla's User Profile plugin to store additional info.
- Use Joomla's language system to provide multilingual support.
- Cache OAuth tokens securely to avoid redundant validations.
- Add support for refresh tokens and long-term session management.
- Provide admin UI panels for managing social login configurations.

***

Sample OAuth Token Code Exchange for Google

Include this method in `OAuthHandler.php` to exchange authorization code for token.

php
public function exchangeCodeForToken($provider, $code)
{
    if ($provider !== 'google') {
        return false; // Implement other providers similarly
    }

    $clientId = $this->params->get('google_client_id');
    $clientSecret = $this->params->get('google_client_secret');
    $redirectUri = $this->params->get('redirect_uri');

    $postFields = http_build_query([
        'code' => $code,
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'redirect_uri' => $redirectUri,
        'grant_type' => 'authorization_code'
    ]);

    $opts = [
        "http" => [
            "method" => "POST",
            "header" => "Content-Type: application/x-www-form-urlencoded\r\n",
            "content" => $postFields
        ]
    ];

    $context = stream_context_create($opts);

    $response = file_get_contents('https://oauth2.googleapis.com/token', false, $context);

    if (!$response) {
        return false;
    }

    $tokenData = json_decode($response);

    return $tokenData->id_token ?? false;
}

***

Debugging and Testing

- Use Joomla's debug mode to trace plugin execution.
- Log OAuth requests and responses securely.
- Test with real OAuth credentials in a development environment.
- Use REST API testing tools like Postman or curl to simulate login requests.
- Confirm user session creation and proper Joomla ACL assignment.

***

Summary